diff --git a/.cursor/.gitignore b/.cursor/.gitignore
new file mode 100644
index 000000000..8bf7cc27a
--- /dev/null
+++ b/.cursor/.gitignore
@@ -0,0 +1 @@
+plans/
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 000000000..e09631a0a
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,19 @@
+.git
+.gitignore
+.DS_Store
+
+node_modules
+**/node_modules
+
+dist
+**/dist
+coverage
+**/coverage
+
+.env
+.env.local
+.env.*.local
+
+.gitnexus
+gitnexus-web/playwright-report
+gitnexus-web/test-results
diff --git a/.env.example b/.env.example
new file mode 100644
index 000000000..ec967c79e
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,15 @@
+# Images (signed Cosign keyless on every push from main / vX.Y.Z tags)
+SERVER_IMAGE=ghcr.io/abhigyanpatwari/gitnexus:latest
+WEB_IMAGE=ghcr.io/abhigyanpatwari/gitnexus-web:latest
+
+# Container names
+SERVER_CONTAINER_NAME=gitnexus-server
+WEB_CONTAINER_NAME=gitnexus-web
+
+# Host ports — the web UI expects the server on http://localhost:4747 by default.
+SERVER_HOST_PORT=4747
+WEB_HOST_PORT=4173
+
+# Optional read-only mount, exposed to the server as /workspace.
+# Override with the directory that contains the repos you want to index.
+WORKSPACE_DIR=./
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 292cb435d..f3530e4d3 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -14,3 +14,62 @@ updates:
     labels:
       - dependencies
       - ci
+
+  # Gitnexus npm deps — tree-sitter grammars checked daily so we catch
+  # new releases that unblock the tree-sitter 0.25 upgrade ASAP. Grammars
+  # are grouped so lockstep bumps produce a single PR. The tree-sitter
+  # RUNTIME is pinned — upgrade deliberately via the drift check workflow.
+  # See .github/scripts/check-tree-sitter-upgrade-readiness.py for
+  # the upgrade readiness tracker.
+  - package-ecosystem: npm
+    directory: /gitnexus
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies
+    groups:
+      tree-sitter-grammars:
+        patterns:
+          - tree-sitter-*
+        exclude-patterns:
+          - tree-sitter
+          - tree-sitter-cli
+    ignore:
+      # Pin the tree-sitter runtime at 0.21.x until the drift check
+      # reports all grammars are peer-dep compatible with 0.25.
+      - dependency-name: tree-sitter
+        update-types:
+          - version-update:semver-major
+          - version-update:semver-minor
+      # tree-sitter-cli follows the runtime's version cadence. Bump when
+      # regenerating vendor/tree-sitter-proto/src/parser.c, not on a schedule.
+      - dependency-name: tree-sitter-cli
+
+  # gitnexus-web (thin frontend client).
+  - package-ecosystem: npm
+    directory: /gitnexus-web
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies
+      - frontend
+
+  # Shared types package.
+  - package-ecosystem: npm
+    directory: /gitnexus-shared
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+    labels:
+      - dependencies
diff --git a/.github/scripts/check-tree-sitter-upgrade-readiness.py b/.github/scripts/check-tree-sitter-upgrade-readiness.py
new file mode 100644
index 000000000..df21533a8
--- /dev/null
+++ b/.github/scripts/check-tree-sitter-upgrade-readiness.py
@@ -0,0 +1,358 @@
+#!/usr/bin/env python3
+"""Monitor tree-sitter 0.25 upgrade readiness.
+
+Tracks two things Dependabot cannot see:
+
+  1. Peer-dep compatibility. Each tree-sitter-* grammar declares a peer
+     dependency on the tree-sitter runtime. We want to know when every
+     grammar's *latest npm release* satisfies tree-sitter@0.25.0 so we
+     can upgrade without --legacy-peer-deps.
+
+  2. Vendored upstream drift. vendor/tree-sitter-proto/ is a snapshot of
+     coder3101/tree-sitter-proto's parser.c. When upstream moves, we want
+     to know whether we can pick it up.
+
+Invoked from .github/workflows/tree-sitter-upgrade-readiness.yml daily.
+Runs locally too:
+
+    python3 .github/scripts/check-tree-sitter-upgrade-readiness.py
+
+Outputs Markdown to stdout. Exit 0 when every grammar is upgrade-ready
+and the vendored proto is in sync. Exit 1 when blockers remain (the
+workflow uses this to open or update a tracking issue).
+
+No external deps -- stdlib only, so it runs on any vanilla runner.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import sys
+import urllib.error
+import urllib.request
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+GITNEXUS_DIR = REPO_ROOT / "gitnexus"
+VENDOR_PROTO_DIR = GITNEXUS_DIR / "vendor" / "tree-sitter-proto"
+
+# ── Upgrade target ──────────────────────────────────────────────────────
+# The runtime version we want to upgrade TO. Update this when the goal
+# changes (e.g. once 0.25 lands and we target 0.26).
+TARGET_RUNTIME = "0.25.0"
+TARGET_RUNTIME_MAJOR_MINOR = ".".join(TARGET_RUNTIME.split(".")[:2])
+
+# Tree-sitter runtime -> (min_abi, max_abi) it can load. Only the current
+# and target entries matter; extend when changing TARGET_RUNTIME.
+RUNTIME_ABI_RANGES: dict[str, tuple[int, int]] = {
+    "0.21": (13, 14),
+    "0.25": (13, 15),
+}
+
+assert TARGET_RUNTIME_MAJOR_MINOR in RUNTIME_ABI_RANGES, (
+    f"RUNTIME_ABI_RANGES has no entry for {TARGET_RUNTIME_MAJOR_MINOR!r}. "
+    f"Add the ABI range after auditing the upstream release notes."
+)
+
+# Grammars we use. Values are the upstream GitHub repos to check for
+# unreleased ABI bumps (owner/repo, branch, parser.c path).
+GRAMMARS: dict[str, tuple[str, str, str]] = {
+    "tree-sitter-c":          ("tree-sitter/tree-sitter-c",          "master", "src/parser.c"),
+    "tree-sitter-c-sharp":    ("tree-sitter/tree-sitter-c-sharp",    "master", "src/parser.c"),
+    "tree-sitter-cpp":        ("tree-sitter/tree-sitter-cpp",        "master", "src/parser.c"),
+    "tree-sitter-dart":       ("UserNobody14/tree-sitter-dart",      "master", "src/parser.c"),
+    "tree-sitter-go":         ("tree-sitter/tree-sitter-go",         "master", "src/parser.c"),
+    "tree-sitter-java":       ("tree-sitter/tree-sitter-java",       "master", "src/parser.c"),
+    "tree-sitter-javascript": ("tree-sitter/tree-sitter-javascript", "master", "src/parser.c"),
+    "tree-sitter-kotlin":     ("fwcd/tree-sitter-kotlin",            "main",   "src/parser.c"),
+    "tree-sitter-php":        ("tree-sitter/tree-sitter-php",        "master", "php/src/parser.c"),
+    "tree-sitter-python":     ("tree-sitter/tree-sitter-python",     "master", "src/parser.c"),
+    "tree-sitter-ruby":       ("tree-sitter/tree-sitter-ruby",       "master", "src/parser.c"),
+    "tree-sitter-rust":       ("tree-sitter/tree-sitter-rust",       "master", "src/parser.c"),
+    "tree-sitter-swift":      ("alex-pinkus/tree-sitter-swift",      "main",   "src/parser.c"),
+    "tree-sitter-typescript": ("tree-sitter/tree-sitter-typescript", "master",  "typescript/src/parser.c"),
+}
+
+UPSTREAM_PROTO_OWNER = "coder3101"
+UPSTREAM_PROTO_REPO = "tree-sitter-proto"
+UPSTREAM_PROTO_BRANCH = "main"
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+def read_current_runtime() -> str:
+    """Return the tree-sitter runtime version pinned in package.json (e.g. '0.21')."""
+    pkg = json.loads((GITNEXUS_DIR / "package.json").read_text())
+    raw = pkg["dependencies"]["tree-sitter"]
+    match = re.search(r"(\d+)\.(\d+)", raw)
+    if not match:
+        raise SystemExit(f"could not parse tree-sitter version: {raw!r}")
+    return f"{match.group(1)}.{match.group(2)}"
+
+
+def npm_view_json(pkg: str) -> dict | None:
+    """Fetch package metadata from the npm registry via HTTPS.
+
+    Uses the registry API directly so we don't depend on the npm CLI
+    being available (it's a batch file on Windows which complicates
+    subprocess calls).
+    """
+    url = f"https://registry.npmjs.org/{pkg}/latest"
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=8) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
+        return None
+
+
+def satisfies_target(peer_range: str | None, target: str) -> bool:
+    """Check if a semver range like '^0.22.4' or '^0.25.0' satisfies the target.
+
+    Simple heuristic: extract the minimum version from the range and check
+    if target >= min. For caret ranges (^X.Y.Z), the upper bound is the
+    next major (for X>0) or next minor (for X==0). We check both bounds.
+    """
+    if peer_range is None:
+        # No peer dep declared = no constraint = compatible.
+        return True
+    match = re.search(r"(\d+)\.(\d+)\.(\d+)", peer_range)
+    if not match:
+        return False
+    min_major, min_minor, min_patch = int(match.group(1)), int(match.group(2)), int(match.group(3))
+
+    t_match = re.search(r"(\d+)\.(\d+)\.(\d+)", target)
+    if not t_match:
+        return False
+    t_major, t_minor, t_patch = int(t_match.group(1)), int(t_match.group(2)), int(t_match.group(3))
+
+    # Target must be >= minimum.
+    target_tuple = (t_major, t_minor, t_patch)
+    min_tuple = (min_major, min_minor, min_patch)
+    if target_tuple < min_tuple:
+        return False
+
+    # For caret ranges with major 0: ^0.X.Y allows [0.X.Y, 0.(X+1).0).
+    if peer_range.startswith("^") and min_major == 0:
+        if t_major != 0 or t_minor >= min_minor + 1:
+            return False
+    # For caret ranges with major >0: ^X.Y.Z allows [X.Y.Z, (X+1).0.0).
+    elif peer_range.startswith("^") and min_major > 0:
+        if t_major >= min_major + 1:
+            return False
+
+    return True
+
+
+_GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN")
+
+
+def fetch_text(url: str, timeout: int = 8) -> str | None:
+    """Fetch a URL and return its text, or None on failure.
+
+    Adds an Authorization header for github.com URLs when GITHUB_TOKEN is
+    set (raises the rate limit from 60 to 5 000 requests/hour).
+    """
+    headers: dict[str, str] = {}
+    if _GITHUB_TOKEN and ("github.com" in url or "githubusercontent.com" in url):
+        headers["Authorization"] = f"Bearer {_GITHUB_TOKEN}"
+    try:
+        req = urllib.request.Request(url, headers=headers)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.read().decode("utf-8", errors="ignore")
+    except (urllib.error.URLError, urllib.error.HTTPError):
+        return None
+
+
+def extract_abi_from_text(text: str) -> int | None:
+    """Extract LANGUAGE_VERSION from parser.c text."""
+    match = re.search(r"#define\s+LANGUAGE_VERSION\s+(\d+)", text[:4096])
+    return int(match.group(1)) if match else None
+
+
+def extract_language_version(parser_c: pathlib.Path) -> int | None:
+    """Return the LANGUAGE_VERSION defined in a parser.c, or None if absent."""
+    if not parser_c.is_file():
+        return None
+    with parser_c.open("r", encoding="utf-8", errors="ignore") as fh:
+        head = fh.read(4096)
+    return extract_abi_from_text(head)
+
+
+def md_h(text: str, level: int = 2) -> str:
+    return f"{'#' * level} {text}\n"
+
+
+# ── Main ────────────────────────────────────────────────────────────────
+
+def main() -> int:
+    blockers: dict[str, str] = {}
+    lines: list[str] = []
+    lines.append(md_h("Tree-sitter 0.25 upgrade readiness", 1))
+    lines.append("")
+
+    current_runtime = read_current_runtime()
+    current_abi_range = RUNTIME_ABI_RANGES.get(current_runtime, (0, 0))
+    target_abi_range = RUNTIME_ABI_RANGES.get(TARGET_RUNTIME_MAJOR_MINOR, (0, 0))
+
+    lines.append(f"- Current runtime: `tree-sitter@{current_runtime}.x` (ABI {current_abi_range[0]}..{current_abi_range[1]})")
+    lines.append(f"- Target runtime: `tree-sitter@{TARGET_RUNTIME}` (ABI {target_abi_range[0]}..{target_abi_range[1]})")
+    lines.append("")
+
+    # ── Grammar peer-dep compatibility ───────────────────────────────
+    lines.append(md_h("Grammar compatibility", 2))
+    lines.append("| Grammar | npm latest | Peer dep | Satisfies 0.25? | ABI | Upstream ABI | Status |")
+    lines.append("|---|---|---|---|---|---|---|")
+
+    ready_count = 0
+    total_count = len(GRAMMARS)
+
+    for name, (upstream_repo, upstream_branch, parser_path) in sorted(GRAMMARS.items()):
+        # Fetch latest npm metadata.
+        info = npm_view_json(name)
+        fetch_failed = info is None
+        npm_version = "?"
+        peer_range = None
+        peer_optional = True
+        if info:
+            npm_version = info.get("version", "?")
+            peers = info.get("peerDependencies") or {}
+            peer_range = peers.get("tree-sitter")
+            meta = info.get("peerDependenciesMeta") or {}
+            ts_meta = meta.get("tree-sitter") or {}
+            peer_optional = ts_meta.get("optional", False) if peer_range else True
+
+        if fetch_failed:
+            peer_display = "? (fetch failed)"
+            compatible = False
+        else:
+            peer_display = peer_range or "none"
+            if peer_range and not peer_optional:
+                peer_display += " (required)"
+            compatible = satisfies_target(peer_range, TARGET_RUNTIME)
+
+        # Check installed ABI using the same parser_path from GRAMMARS.
+        installed_parser = GITNEXUS_DIR / "node_modules" / name / parser_path
+        if not installed_parser.is_file():
+            # Fallback to default location.
+            installed_parser = GITNEXUS_DIR / "node_modules" / name / "src" / "parser.c"
+        installed_abi = extract_language_version(installed_parser)
+        abi_display = str(installed_abi) if installed_abi else "?"
+
+        # Check upstream (main/master branch) ABI for unreleased work.
+        upstream_url = (
+            f"https://raw.githubusercontent.com/{upstream_repo}/"
+            f"{upstream_branch}/{parser_path}"
+        )
+        upstream_text = fetch_text(upstream_url)
+        upstream_abi = extract_abi_from_text(upstream_text) if upstream_text else None
+        upstream_abi_display = str(upstream_abi) if upstream_abi else "?"
+
+        # Determine status.
+        if fetch_failed:
+            status = "Unknown (fetch failed)"
+            blockers[name] = f"`{name}`: npm registry fetch failed — could not verify peer dep"
+        elif compatible:
+            status = "Ready"
+            ready_count += 1
+        elif upstream_abi and upstream_abi >= 15:
+            status = "Unreleased (ABI 15 on main)"
+            blockers[name] = f"`{name}`: ABI 15 on `{upstream_repo}` main but not published to npm"
+        else:
+            status = "Blocking"
+            blockers[name] = f"`{name}@{npm_version}`: peer `{peer_display}` incompatible with 0.25"
+
+        # Also check upstream package.json for relaxed peer dep.
+        if not compatible and not fetch_failed:
+            upstream_pkg_url = (
+                f"https://raw.githubusercontent.com/{upstream_repo}/"
+                f"{upstream_branch}/package.json"
+            )
+            upstream_pkg_text = fetch_text(upstream_pkg_url)
+            if upstream_pkg_text:
+                try:
+                    upstream_pkg = json.loads(upstream_pkg_text)
+                    upstream_peer = (upstream_pkg.get("peerDependencies") or {}).get("tree-sitter")
+                    if upstream_peer and satisfies_target(upstream_peer, TARGET_RUNTIME):
+                        status = "Unreleased (peer relaxed on main)"
+                        blockers[name] = f"`{name}`: peer dep relaxed on `{upstream_repo}` main but not published to npm"
+                except json.JSONDecodeError:
+                    pass
+
+        compat_icon = "Yes" if compatible else "**No**"
+        lines.append(
+            f"| `{name}` | {npm_version} | {peer_display} | {compat_icon} | {abi_display} | {upstream_abi_display} | {status} |"
+        )
+
+    lines.append("")
+    lines.append(f"**{ready_count}/{total_count}** grammars ready for `tree-sitter@{TARGET_RUNTIME}`.")
+    lines.append("")
+
+    # ── Vendored proto drift ─────────────────────────────────────────
+    lines.append(md_h("Vendored tree-sitter-proto", 2))
+    vendored_abi = extract_language_version(VENDOR_PROTO_DIR / "src" / "parser.c")
+
+    upstream_proto_url = (
+        f"https://raw.githubusercontent.com/{UPSTREAM_PROTO_OWNER}/"
+        f"{UPSTREAM_PROTO_REPO}/{UPSTREAM_PROTO_BRANCH}/src/parser.c"
+    )
+    upstream_proto_text = fetch_text(upstream_proto_url)
+    upstream_proto_abi = extract_abi_from_text(upstream_proto_text) if upstream_proto_text else None
+
+    sha_url = (
+        f"https://api.github.com/repos/{UPSTREAM_PROTO_OWNER}/"
+        f"{UPSTREAM_PROTO_REPO}/commits/{UPSTREAM_PROTO_BRANCH}"
+    )
+    sha_text = fetch_text(sha_url)
+    upstream_sha = "?"
+    if sha_text:
+        try:
+            upstream_sha = json.loads(sha_text).get("sha", "?")[:12]
+        except json.JSONDecodeError:
+            pass
+
+    local_proto_path = VENDOR_PROTO_DIR / "src" / "parser.c"
+    local_proto_text = local_proto_path.read_text(encoding="utf-8", errors="ignore") if local_proto_path.is_file() else ""
+    in_sync = bool(
+        upstream_proto_text
+        and local_proto_text.replace("\r\n", "\n")
+        == upstream_proto_text.replace("\r\n", "\n")
+    )
+
+    lines.append(f"- Upstream: `{UPSTREAM_PROTO_OWNER}/{UPSTREAM_PROTO_REPO}@{UPSTREAM_PROTO_BRANCH}` (HEAD `{upstream_sha}`)")
+    lines.append(f"- Upstream ABI: **{upstream_proto_abi}**")
+    lines.append(f"- Vendored ABI: **{vendored_abi}**")
+    lines.append(f"- In sync: {'yes' if in_sync else 'no — upstream has diverged'}")
+
+    if upstream_proto_abi and vendored_abi and upstream_proto_abi > vendored_abi:
+        can_upgrade = upstream_proto_abi <= target_abi_range[1]
+        lines.append(f"- Upstream ABI {upstream_proto_abi} {'is' if can_upgrade else 'is NOT'} within target runtime range ({target_abi_range[0]}..{target_abi_range[1]})")
+        if can_upgrade:
+            lines.append(f"- **Action:** after upgrading to tree-sitter@{TARGET_RUNTIME}, regenerate vendored parser.c from upstream `{upstream_sha}`")
+        else:
+            lines.append(f"- **Action:** wait for runtime upgrade beyond {TARGET_RUNTIME} that supports ABI {upstream_proto_abi}")
+            blockers["vendored-proto-abi"] = f"vendored tree-sitter-proto: upstream ABI {upstream_proto_abi} outside target range"
+    elif not in_sync:
+        lines.append("- **Action:** review upstream changes; vendored copy may need updating")
+        blockers["vendored-proto-sync"] = "vendored tree-sitter-proto: out of sync with upstream"
+
+    # ── Summary ──────────────────────────────────────────────────────
+    lines.append("")
+    lines.append(md_h("Summary", 2))
+    if blockers:
+        lines.append(f"**{len(blockers)} blocker(s) remaining:**\n")
+        for b in blockers.values():
+            lines.append(f"- {b}")
+        lines.append("")
+        lines.append("Upgrade to `tree-sitter@0.25` is **blocked**.")
+    else:
+        lines.append("All grammars are compatible. Upgrade to `tree-sitter@0.25` is **ready**.")
+
+    print("\n".join(lines))
+    return 1 if blockers else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/scripts/check-workflow-concurrency.py b/.github/scripts/check-workflow-concurrency.py
index 300cc7f4b..0d7a49291 100644
--- a/.github/scripts/check-workflow-concurrency.py
+++ b/.github/scripts/check-workflow-concurrency.py
@@ -11,10 +11,14 @@ Rules:
      `concurrency:` block.
   2. Reusable workflows (on: workflow_call ONLY) do NOT declare one.
   3. The `concurrency.group` expression MUST reference either
-     `${{ github.workflow }}` or a literal `CI-` prefix (the documented
-     ci.yml reusable-workflow-safe exception). This is checked by substring
-     containment rather than prefix match because ci.yml's group is a
-     conditional expression that resolves to a `CI-…` literal at runtime.
+     `${{ github.workflow }}` or one of the approved hardcoded literal prefixes
+     for workflows that are simultaneously entry-points AND reusable (on: push/
+     workflow_call). Two such exceptions are currently approved:
+       - `CI-` for ci.yml (the original canonical form)
+       - `docker-build-push-` for docker.yml
+     This is checked by substring containment rather than prefix match because
+     the group value is a conditional expression that resolves to a `CI-…` or
+     `docker-build-push-…` literal at runtime.
 
 We deliberately do not use a YAML library — keeps the script dependency-free
 on any vanilla runner. `on:` block parsing is line-based and handles both the
@@ -28,7 +32,7 @@ import re
 import sys
 
 
-REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-")
+REQUIRED_TOKENS = ("${{ github.workflow }}", "CI-", "docker-build-push-")
 
 
 def is_reusable(lines: list[str]) -> bool:
@@ -150,8 +154,10 @@ def check(workflows_dir: pathlib.Path) -> int:
         if not any(token in group for token in REQUIRED_TOKENS):
             print(
                 f"::error file={path}::concurrency.group `{group}` must "
-                f"reference one of {REQUIRED_TOKENS}. See CONTRIBUTING.md -> "
-                "GitHub Actions — Concurrency Convention."
+                f"reference one of {REQUIRED_TOKENS} (use ${{{{ github.workflow }}}} "
+                "for normal entry-point workflows; use an approved literal prefix "
+                "only for workflows that are both entry-points AND reusable — "
+                "see CONTRIBUTING.md -> GitHub Actions — Concurrency Convention)."
             )
             fail = 1
 
diff --git a/.github/workflows/ci-global-upgrade.yml b/.github/workflows/ci-global-upgrade.yml
deleted file mode 100644
index e181f46ad..000000000
--- a/.github/workflows/ci-global-upgrade.yml
+++ /dev/null
@@ -1,113 +0,0 @@
-name: Global Install Upgrade Smoke
-
-# Catches regressions where `npm install -g gitnexus@<new>` fails to upgrade
-# cleanly over a prior global install. Prior precedent: issue #836 and PR #843's
-# incomplete fix slipped past CI because no global-upgrade test existed.
-#
-# Reusable workflow — only callable from ci.yml. Concurrency is governed by the
-# caller (ci.yml), so no `concurrency:` block here.
-
-on:
-  workflow_call:
-
-jobs:
-  global-upgrade:
-    name: ${{ matrix.os }} / upgrade over ${{ matrix.prior }}
-    strategy:
-      fail-fast: false
-      matrix:
-        # macOS is the reporter's platform (issue #836) and the highest-risk
-        # surface for npm global-install rmdir behavior. Linux and Windows
-        # provide cross-platform regression coverage.
-        os: [macos-latest, ubuntu-latest, windows-latest]
-        # Prior version that must be upgraded OVER. Should be a published rc
-        # that preceded the fix. Bump when a known-bad version changes.
-        prior: ['1.6.2-rc.8']
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'false'
-
-      - name: Install prior published version globally
-        run: npm install -g gitnexus@${{ matrix.prior }}
-
-      - name: Verify prior version installed
-        run: gitnexus --version
-
-      - name: Pack current branch
-        working-directory: gitnexus
-        run: npm pack
-        shell: bash
-
-      - name: Compute packed tarball path
-        id: tarball
-        working-directory: gitnexus
-        run: |
-          TARBALL=$(ls gitnexus-*.tgz | head -1)
-          echo "path=$(pwd)/$TARBALL" >> "$GITHUB_OUTPUT"
-        shell: bash
-
-      - name: Upgrade over prior version (the actual regression test)
-        run: npm install -g "${{ steps.tarball.outputs.path }}"
-        shell: bash
-
-      - name: Verify upgraded version runs
-        run: gitnexus --version
-
-      - name: Verify vendor/ has no nested node_modules after install
-        shell: bash
-        run: |
-          # The original #836 bug was about vendor/tree-sitter-proto/node_modules/
-          # blocking rmdir on upgrade. That is what the fix eliminates. A
-          # vendor/tree-sitter-proto/build/ directory can still appear because
-          # node-gyp-build compiles through the npm-created symlink; the
-          # contents are plain object files and .node binaries that rmdir
-          # handles fine, evidenced by this test getting past the upgrade step.
-          GLOBAL_PREFIX=$(npm root -g)
-          if [ -d "$GLOBAL_PREFIX/gitnexus/vendor/tree-sitter-proto" ]; then
-            echo "=== Contents of global vendor/tree-sitter-proto/ ==="
-            ls -la "$GLOBAL_PREFIX/gitnexus/vendor/tree-sitter-proto/"
-            if [ -d "$GLOBAL_PREFIX/gitnexus/vendor/tree-sitter-proto/node_modules" ]; then
-              echo "::error::vendor/tree-sitter-proto/node_modules/ was created — this is the #836 hazard"
-              exit 1
-            fi
-          fi
-
-  ignore-scripts:
-    name: ${{ matrix.os }} / --ignore-scripts degraded mode
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [macos-latest, ubuntu-latest, windows-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - uses: ./.github/actions/setup-gitnexus
-        with:
-          build: 'false'
-
-      - name: Pack current branch
-        working-directory: gitnexus
-        run: npm pack
-        shell: bash
-
-      - name: Compute packed tarball path
-        id: tarball
-        working-directory: gitnexus
-        run: |
-          TARBALL=$(ls gitnexus-*.tgz | head -1)
-          echo "path=$(pwd)/$TARBALL" >> "$GITHUB_OUTPUT"
-        shell: bash
-
-      - name: Install globally with --ignore-scripts
-        run: npm install -g --ignore-scripts "${{ steps.tarball.outputs.path }}"
-        shell: bash
-
-      - name: Verify CLI boots without postinstall (proto parsing may be unavailable)
-        run: gitnexus --version
diff --git a/.github/workflows/ci-report.yml b/.github/workflows/ci-report.yml
index a1fa33219..ab8d8362c 100644
--- a/.github/workflows/ci-report.yml
+++ b/.github/workflows/ci-report.yml
@@ -36,7 +36,7 @@ jobs:
     steps:
       # ── Download artifacts from the CI run ────────────────────────
       - name: Download artifacts
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             const fs = require('fs');
@@ -132,7 +132,7 @@ jobs:
       - name: Fetch base branch coverage
         if: steps.meta.outputs.skip != 'true'
         id: base-coverage
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             const fs = require('fs');
@@ -416,7 +416,7 @@ jobs:
 
       - name: Comment on PR
         if: steps.meta.outputs.skip != 'true'
-        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2
+        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v2
         with:
           header: ci-report
           number: ${{ steps.meta.outputs.pr_number }}
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
index 27eb75383..7010ee6f3 100644
--- a/.github/workflows/ci-tests.yml
+++ b/.github/workflows/ci-tests.yml
@@ -41,6 +41,9 @@ jobs:
           --outputFile=web-test-results.json
         working-directory: gitnexus-web
 
+      - name: Run docker-server integration tests
+        run: node --test docker-server.test.mjs
+
       - name: Upload test reports
         if: always()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e2eeeaab2..cf0c6d5c5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -48,11 +48,6 @@ jobs:
     permissions:
       contents: read
 
-  global-upgrade:
-    uses: ./.github/workflows/ci-global-upgrade.yml
-    permissions:
-      contents: read
-
   # ── Save PR metadata for the reporting workflow ─────────────────
   # The ci-report.yml workflow (triggered by workflow_run) needs the
   # PR number and job results to post a comment.  We save them as an
@@ -61,7 +56,7 @@ jobs:
   save-pr-meta:
     name: Save PR Metadata
     if: always() && github.event_name == 'pull_request'
-    needs: [quality, tests, e2e, global-upgrade]
+    needs: [quality, tests, e2e]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -72,7 +67,6 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
-          GLOBAL_UPGRADE: ${{ needs.global-upgrade.result }}
         run: |
           mkdir -p pr-meta
           echo "$PR_NUMBER"  > pr-meta/pr_number
@@ -101,7 +95,7 @@ jobs:
   # Single required check for branch protection.
   ci-status:
     name: CI Gate
-    needs: [quality, tests, e2e, global-upgrade]
+    needs: [quality, tests, e2e]
     if: always()
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -112,12 +106,10 @@ jobs:
           QUALITY: ${{ needs.quality.result }}
           TESTS: ${{ needs.tests.result }}
           E2E: ${{ needs.e2e.result }}
-          GLOBAL_UPGRADE: ${{ needs.global-upgrade.result }}
         run: |
           echo "Quality:        $QUALITY"
           echo "Tests:          $TESTS"
           echo "E2E:            $E2E"
-          echo "Global upgrade: $GLOBAL_UPGRADE"
           if [[ "$QUALITY" != "success" ]] ||
              [[ "$TESTS" != "success" ]]; then
             echo "::error::Quality or test jobs failed"
@@ -127,7 +119,3 @@ jobs:
             echo "::error::E2E job failed"
             exit 1
           fi
-          if [[ "$GLOBAL_UPGRADE" != "success" && "$GLOBAL_UPGRADE" != "skipped" ]]; then
-            echo "::error::Global upgrade smoke failed"
-            exit 1
-          fi
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
index d9d9decf6..e5642cb3e 100644
--- a/.github/workflows/claude-code-review.yml
+++ b/.github/workflows/claude-code-review.yml
@@ -57,7 +57,7 @@ jobs:
       # For issue_comment triggers, resolve the PR number, head SHA, and fork repo
       - name: Resolve PR context
         id: pr
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             let pr;
diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml
index c4a2e9450..553d3ab0d 100644
--- a/.github/workflows/claude.yml
+++ b/.github/workflows/claude.yml
@@ -59,7 +59,7 @@ jobs:
       # For PR-related triggers, resolve the fork repo so we can checkout correctly.
       - name: Resolve PR context
         id: pr
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v7
         with:
           script: |
             // Determine if this event is PR-related
diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml
new file mode 100644
index 000000000..1b83a1e4b
--- /dev/null
+++ b/.github/workflows/docker.yml
@@ -0,0 +1,199 @@
+name: Docker Build & Push
+
+on:
+  push:
+    tags:
+      - 'v*'
+  # No workflow_dispatch: publishing is exclusively tag-driven so that every
+  # signed image corresponds 1:1 to a published `gitnexus@X.Y.Z` on npm. A
+  # manual run from a branch ref would fail the version check below anyway.
+  workflow_call:
+    inputs:
+      tag:
+        description: >-
+          The full v-prefixed tag to build (e.g. v1.2.3-rc.1).
+          The tag must already exist in the repo and its tree must contain
+          a gitnexus/package.json whose version matches the tag.
+        required: true
+        type: string
+
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+# Tag refs are unique per release, so distinct tags run in parallel.
+# Re-pushes of the same tag serialize. cancel-in-progress: false — never cancel a publish mid-flight.
+# Hardcoded `docker-build-push-` prefix (not `${{ github.workflow }}`) when invoked as a reusable
+# workflow: in called-workflow context `github.workflow` is ambiguous and could resolve to the
+# caller's name, sharing a concurrency group with the caller → deadlock.
+# Direct tag-push invocations use `docker-build-push-<ref>`; workflow_call invocations get a
+# per-run-unique group (they are already serialized by the caller's own concurrency group).
+concurrency:
+  group: ${{ (github.event_name == 'push') && format('docker-build-push-{0}', github.ref) || format('docker-build-push-nested-{0}', github.run_id) }}
+  cancel-in-progress: false
+
+jobs:
+  build-push:
+    name: Build & Push ${{ matrix.image.name }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      packages: write
+      # Required for Cosign keyless signing via the OIDC token exchange,
+      # and for build provenance / SBOM attestations.
+      id-token: write
+      attestations: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          # Static UI bundle. Small, fast image. Drop-in replacement for the
+          # legacy single-image setup at the same `gitnexus` repository slug
+          # is intentionally avoided — the UI now lives at `gitnexus-web` and
+          # the CLI/server takes the canonical `gitnexus` slug below.
+          - name: gitnexus-web
+            dockerfile: Dockerfile.web
+            slug: gitnexus-web
+          # CLI / `gitnexus serve` backend. Heavy native deps (tree-sitter,
+          # onnxruntime-node) live only in this image.
+          - name: gitnexus
+            dockerfile: Dockerfile.cli
+            slug: gitnexus
+
+    steps:
+      - name: Validate tag input
+        if: github.event_name == 'workflow_call'
+        shell: bash
+        env:
+          TAG_INPUT: ${{ inputs.tag }}
+        run: |
+          if [ -z "${TAG_INPUT}" ]; then
+            echo "::error::No tag provided to docker.yml — refusing to build/push."
+            exit 1
+          fi
+
+      # When triggered by workflow_call the caller passes the RC tag as an input;
+      # we check out that tag so the Dockerfile and package.json match the built image.
+      # For tag-push events github.ref is already the tag ref — no override needed.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+
+      # ── Lock the docker image version to the npm package version ──────────
+      # Mirrors the check in publish.yml: refuse to build unless the git tag
+      # exactly matches `gitnexus/package.json`'s version. This guarantees
+      # `ghcr.io/<owner>/gitnexus:X.Y.Z` always corresponds to the same
+      # `gitnexus@X.Y.Z` published to npm — no drift, no surprises.
+      - name: Verify tag matches gitnexus/package.json version
+        id: version
+        shell: bash
+        env:
+          # For workflow_call the tag comes from the caller input; for push events
+          # it is derived from GITHUB_REF (set to empty so the else-branch fires).
+          INPUT_TAG: ${{ inputs.tag }}
+        run: |
+          if [ -n "$INPUT_TAG" ]; then
+            TAG_VERSION="${INPUT_TAG#v}"
+          else
+            TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          fi
+          if ! [[ "$TAG_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Tag does not follow semver: v$TAG_VERSION"
+            exit 1
+          fi
+          PKG_VERSION=$(node -p "require('./gitnexus/package.json').version")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version (v$TAG_VERSION) does not match gitnexus/package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "version=$PKG_VERSION" >> "$GITHUB_OUTPUT"
+          echo "Version verified: $PKG_VERSION"
+
+      # Required for multi-platform (linux/arm64) emulation.
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Install Cosign
+        uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Computes image tags and labels from the verified semver tag:
+      #   v1.2.3        → :1.2.3, :1.2, :1, :latest (auto, only for non-prerelease)
+      #   v1.2.3-rc.1   → :1.2.3-rc.1 only (prereleases never become :latest)
+      # `:latest` is only emitted for tag pushes thanks to `flavor: latest=auto`,
+      # ensuring it always points at a real npm-published version.
+      #
+      # For workflow_call invocations github.ref is the caller's branch ref, so
+      # the type=semver patterns would not match. In that case we add an explicit
+      # type=raw tag using the version already verified above, so the same
+      # image-naming rules apply regardless of how the workflow was triggered.
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+          flavor: latest=auto
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=${{ steps.version.outputs.version }},enable=${{ github.event_name == 'workflow_call' }}
+
+      - name: Build and push
+        id: build
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          file: ${{ matrix.image.dockerfile }}
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=${{ matrix.image.slug }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.image.slug }}
+          provenance: mode=max
+          sbom: true
+
+      # Cosign keyless signing. Each pushed tag is signed by the workflow's
+      # OIDC identity, so consumers can verify the image with the strict,
+      # fully-anchored identity regex (kept in sync with README.md and
+      # deploy/kubernetes/cluster-image-policy.yaml — update all three together).
+      # NOTE: `${...}` expression syntax is NOT evaluated inside YAML comments, so
+      # the example below uses literal `<owner>/<repo>` placeholders that consumers
+      # substitute themselves; the canonical, fully-rendered command lives in README.md.
+      #   cosign verify ghcr.io/<owner>/<slug>:<tag> \
+      #     --certificate-identity-regexp '^https://github\.com/<owner>/<repo>/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
+      #     --certificate-oidc-issuer https://token.actions.githubusercontent.com
+      # Do NOT relax to `@.*` — that accepts signatures from any ref, including
+      # unprotected branches and PRs, and defeats the supply-chain guarantee.
+      - name: Sign image with Cosign (keyless)
+        env:
+          # Cosign v2 (installed by sigstore/cosign-installer above) makes
+          # keyless the default. COSIGN_EXPERIMENTAL is a v1-only opt-in flag
+          # that is now deprecated/no-op, so it is intentionally omitted.
+          DIGEST: ${{ steps.build.outputs.digest }}
+          TAGS: ${{ steps.meta.outputs.tags }}
+        run: |
+          # Sign every tag at the same digest so consumers can verify by tag or by digest.
+          # Use `while read` instead of `for $TAGS` to be robust against tags that
+          # could ever contain whitespace (the metadata-action output is newline-
+          # separated, not space-separated).
+          while IFS= read -r tag; do
+            [[ -n "$tag" ]] && cosign sign --yes "${tag}@${DIGEST}"
+          done <<< "$TAGS"
+
+      # Attach the SBOM produced by buildx as a verifiable attestation on the digest.
+      - name: Generate build provenance attestation
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-name: ghcr.io/${{ github.repository_owner }}/${{ matrix.image.slug }}
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true
diff --git a/.github/workflows/pr-description-check.yml b/.github/workflows/pr-description-check.yml
index de562fd35..cec32de0f 100644
--- a/.github/workflows/pr-description-check.yml
+++ b/.github/workflows/pr-description-check.yml
@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Check PR description quality
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const MIN_BODY_LENGTH = 50;
diff --git a/.github/workflows/pr-labeler.yml b/.github/workflows/pr-labeler.yml
index aab2fcaef..3c0c52725 100644
--- a/.github/workflows/pr-labeler.yml
+++ b/.github/workflows/pr-labeler.yml
@@ -12,7 +12,7 @@ name: PR Conventional Labeler
 #   autolabel (on: pull_request_target)
 #     Needs `pull-requests: write` to apply labels, so must be
 #     pull_request_target. Uses `release-drafter/release-drafter` with
-#     `disable-releaser: true` to only run the autolabeler against the
+#     `dry-run: true` to only run the autolabeler against the
 #     `.github/release-drafter.yml` config from the BASE ref (release-
 #     drafter reads the config from the repository's default branch, NOT
 #     the PR head — verify with `gh api repos/release-drafter/release-drafter/contents/...`
@@ -57,9 +57,9 @@ jobs:
     permissions:
       pull-requests: read
     steps:
-      # Pinned to v5.5.3. Verify SHA via:
-      #   gh api repos/amannn/action-semantic-pull-request/git/refs/tags/v5.5.3
-      - uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3
+      # Pinned to v6.1.1. Verify SHA via:
+      #   gh api repos/amannn/action-semantic-pull-request/git/refs/tags/v6.1.1
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
@@ -102,12 +102,12 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      # Pinned to v6.0.0. Verify SHA via:
-      #   gh api repos/release-drafter/release-drafter/git/refs/tags/v6.0.0
-      # Note: dependabot will likely propose a bump to v6.x on first run.
-      - uses: release-drafter/release-drafter@3f0f87098bd6b5c5b9a36d49c41d998ea58f9348 # v6.0.0
+      # Pinned to v7.2.0. Verify SHA via:
+      #   gh api repos/release-drafter/release-drafter/git/refs/tags/v7.2.0
+      # v7 removed `disable-releaser`; use `dry-run: true` to only autolabel.
+      - uses: release-drafter/release-drafter@5de93583980a40bd78603b6dfdcda5b4df377b32 # v7.2.0
         with:
           config-name: release-drafter.yml
-          disable-releaser: true
+          dry-run: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 03898a267..3d883425a 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -91,7 +91,7 @@ jobs:
           fi
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
         with:
           body_path: ${{ steps.changelog.outputs.fallback == 'false' && '/tmp/release-notes.md' || '' }}
           generate_release_notes: ${{ steps.changelog.outputs.fallback == 'true' }}
diff --git a/.github/workflows/release-candidate.yml b/.github/workflows/release-candidate.yml
index cc22f4749..61782da1c 100644
--- a/.github/workflows/release-candidate.yml
+++ b/.github/workflows/release-candidate.yml
@@ -125,6 +125,8 @@ jobs:
     permissions:
       contents: write # push rc tag + marker
       id-token: write # npm provenance
+    outputs:
+      vtag: ${{ steps.reltag.outputs.vtag }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -346,7 +348,7 @@ jobs:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Create GitHub prerelease
-        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v2
         with:
           tag_name: ${{ steps.reltag.outputs.vtag }}
           name: Release Candidate ${{ steps.reltag.outputs.vtag }}
@@ -364,3 +366,23 @@ jobs:
 
             Release candidates are pre-stable builds intended for early testing.
             Stable releases remain on the `latest` dist-tag.
+
+  # ── Build & push RC Docker images ────────────────────────────────────
+  # Calls docker.yml as a reusable workflow so that the build, signing, and
+  # attestation logic stays in one place. The publish job exposes `vtag`
+  # (e.g. `v1.2.3-rc.1`) as an output so we can pass it as the tag input.
+  # RC images are signed with Cosign keyless signing; the OIDC identity
+  # will be `docker.yml@refs/heads/main` (the caller's ref) rather than a
+  # tag ref — see README.md § Docker for the correct verify command for RCs.
+  docker:
+    name: Build & Push RC Docker images
+    needs: [guard, publish]
+    if: needs.guard.outputs.should_run == 'true' && needs.publish.outputs.vtag != ''
+    uses: ./.github/workflows/docker.yml
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      attestations: write
+    with:
+      tag: ${{ needs.publish.outputs.vtag }}
diff --git a/.github/workflows/tree-sitter-upgrade-readiness.yml b/.github/workflows/tree-sitter-upgrade-readiness.yml
new file mode 100644
index 000000000..74ce72a27
--- /dev/null
+++ b/.github/workflows/tree-sitter-upgrade-readiness.yml
@@ -0,0 +1,185 @@
+name: Tree-sitter Upgrade Readiness
+
+# Monitors readiness for upgrading tree-sitter to 0.25.x. Tracks:
+#   1. Peer-dep compatibility — can each grammar install cleanly with
+#      tree-sitter@0.25.0 without --legacy-peer-deps?
+#   2. Vendored proto drift — has coder3101/tree-sitter-proto moved
+#      ahead of our vendored snapshot?
+# See .github/scripts/check-tree-sitter-upgrade-readiness.py for the logic.
+#
+# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention".
+
+on:
+  schedule:
+    # Daily at 09:00 UTC. Matches Dependabot's daily cadence so drift
+    # and dep PRs surface together.
+    - cron: '0 9 * * *'
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.github/scripts/check-tree-sitter-upgrade-readiness.py'
+      - '.github/workflows/tree-sitter-upgrade-readiness.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  readiness:
+    name: Check upgrade readiness
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      # Needed to open/update the tracking issue on scheduled runs.
+      issues: write
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'false'
+
+      - name: Run upgrade readiness check
+        id: readiness
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set +e
+          python3 .github/scripts/check-tree-sitter-upgrade-readiness.py > drift-report.md
+          code=$?
+          set -e
+          echo "exit_code=$code" >> "$GITHUB_OUTPUT"
+          {
+            echo 'report<<DRIFT_EOF'
+            cat drift-report.md
+            echo 'DRIFT_EOF'
+          } >> "$GITHUB_OUTPUT"
+          echo "=== Report ==="
+          cat drift-report.md
+
+      # On PR runs, the script validates that it runs correctly. Blockers
+      # are informational — the scheduled run opens a tracking issue.
+      - name: Annotate PR with readiness status
+        if: github.event_name == 'pull_request' && steps.readiness.outputs.exit_code != '0'
+        run: |
+          echo "::warning::Tree-sitter 0.25 upgrade has blockers. See job output for the full readiness report."
+
+      - name: Upsert tracking issue on scheduled runs
+        if: >
+          github.event_name == 'schedule' &&
+          steps.readiness.outputs.exit_code != '0'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          REPORT: ${{ steps.readiness.outputs.report }}
+        with:
+          script: |
+            const title = 'Tree-sitter 0.25 upgrade readiness';
+            const report = process.env.REPORT;
+            const body = report + '\n\n' +
+              '<sub>Generated daily by `.github/workflows/tree-sitter-upgrade-readiness.yml`. ' +
+              'Closes automatically when all blockers are resolved.</sub>';
+            const { data: open } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'tree-sitter-drift',
+              per_page: 10,
+            });
+            const existing = open.find(i => i.title === title);
+            if (existing) {
+              // Extract ready/total count for the changelog comment.
+              const readyMatch = report.match(/\*\*(\d+)\/(\d+)\*\* grammars ready/);
+              const blockerMatch = report.match(/\*\*(\d+) blocker/);
+              const ready = readyMatch ? readyMatch[1] : '?';
+              const total = readyMatch ? readyMatch[2] : '?';
+              const blockers = blockerMatch ? blockerMatch[1] : '?';
+
+              // Find grammars whose status changed by diffing the old and
+              // new table rows.  Each row looks like:
+              //   | `tree-sitter-foo` | ... | Ready |
+              //   | `tree-sitter-foo` | ... | Blocking |
+              const parseRows = (md) => {
+                const map = {};
+                for (const m of md.matchAll(/\| `(tree-sitter-[^`]+)` \|.*?\| (\S+(?:\s\S+)*?) \|$/gm)) {
+                  map[m[1]] = m[2].trim();
+                }
+                return map;
+              };
+              const oldRows = parseRows(existing.body || '');
+              const newRows = parseRows(report);
+              const changes = [];
+              for (const [name, newStatus] of Object.entries(newRows)) {
+                const oldStatus = oldRows[name];
+                if (oldStatus && oldStatus !== newStatus) {
+                  changes.push(`\`${name}\`: ${oldStatus} → ${newStatus}`);
+                }
+              }
+
+              const today = new Date().toISOString().slice(0, 10);
+              let comment = `**${today}:** ${ready}/${total} ready. ${blockers} blocker(s) remaining.`;
+              if (changes.length > 0) {
+                comment += '\n\nChanges:\n' + changes.map(c => `- ${c}`).join('\n');
+              } else {
+                comment += ' No changes from previous run.';
+              }
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body: comment,
+              });
+
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body,
+              });
+              core.info(`Updated existing issue #${existing.number}`);
+            } else {
+              const { data: created } = await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ['tree-sitter-drift', 'dependencies'],
+              });
+              core.info(`Opened issue #${created.number}`);
+            }
+
+      - name: Close tracking issue on clean scheduled runs
+        if: >
+          github.event_name == 'schedule' &&
+          steps.readiness.outputs.exit_code == '0'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const title = 'Tree-sitter 0.25 upgrade readiness';
+            const { data: open } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'tree-sitter-drift',
+              per_page: 10,
+            });
+            const existing = open.find(i => i.title === title);
+            if (existing) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                body: 'All grammars are now compatible with tree-sitter@0.25. Upgrade is ready! Closing automatically.',
+              });
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.number,
+                state: 'closed',
+              });
+              core.info(`Closed issue #${existing.number}`);
+            }
diff --git a/.gitignore b/.gitignore
index 88419e481..92027b529 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,7 @@ Thumbs.db
 .env
 .env.local
 .env.*.local
+docker/.env
 
 # Logs
 *.log
@@ -104,4 +105,4 @@ local_docs/
 
 # Local agent scratch / review prompts (never commit)
 .tmp/
-.agents/
\ No newline at end of file
+.agents/
diff --git a/AGENTS.md b/AGENTS.md
index 651657b02..f4fbcadc0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,117 +1,122 @@
-<!-- version: 1.3.0 -->
-<!--
-  Metadata: version, last reviewed, scope, model policy, reference docs, changelog.
-  Last updated: 2026-03-22
--->
+<!-- version: 1.4.0 -->
+<!-- Last updated: 2026-04-16 -->
 
-Last reviewed: 2026-04-13
+Last reviewed: 2026-04-16
 
 **Project:** GitNexus · **Environment:** dev · **Maintainer:** repository maintainers (see GitHub)
 
-This file uses a standard agent header (version, scope, model policy, reference docs, changelog), adapted for this **TypeScript/JavaScript monorepo**.
-
 ## Scope
 
-| | |
-|--|--|
-| **Reads** | Repository tree as needed for the task: `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/` when present, and docs. |
-| **Writes** | Only paths required for the requested change; keep diffs minimal. Update lockfiles when dependencies change. |
-| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/` when applicable; shell utilities for documented CI/dev workflows. |
-| **Off-limits** | User secrets (e.g. real `.env`), production deployment credentials, unrelated repositories, destructive git history operations without explicit human confirmation. |
+| Boundary | Rule |
+|----------|------|
+| **Reads** | `gitnexus/`, `gitnexus-web/`, `eval/`, plugin packages, `.github/`, `.gitnexus/`, docs. |
+| **Writes** | Only paths required for the change; keep diffs minimal. Update lockfiles when deps change. |
+| **Executes** | `npm`, `npx`, `node` under `gitnexus/` and `gitnexus-web/`; `uv run` for Python under `eval/`; documented CI/dev workflows. |
+| **Off-limits** | Real `.env` / secrets, production credentials, unrelated repos, destructive git ops without confirmation. |
 
 ## Model Configuration
 
-- **Primary:** Pin in **Cursor** (Settings → model). Use a **named** model (e.g. GPT-5.2, Claude Sonnet 4.x). Avoid relying on **Auto** when reproducibility or audit trail matters.
-- **Fallback:** As configured in Cursor or your organization (do not encode `latest` or wildcards in automation configs).
-- **Notes:** The open-source GitNexus CLI indexer does not call an LLM. Optional Nexus AI in the web UI uses end-user provider keys and models.
+- **Primary:** Use a named model (e.g. Claude Sonnet 4.x). Avoid `Auto` or unversioned `latest` when reproducibility matters.
+- **Notes:** The GitNexus CLI indexer does not call an LLM.
 
 ## Execution Sequence (complex tasks)
 
-Long sessions dilute instructions. For **multi-step** work, state up front:
-
+For multi-step work, state up front:
 1. Which rules in this file and **[GUARDRAILS.md](GUARDRAILS.md)** apply (and any relevant Signs).
-2. Current **Scope** boundaries (Reads / Writes / Off-limits).
-3. Which **validation commands** you will run (e.g. `cd gitnexus && npm test`, `npx tsc --noEmit`).
+2. Current **Scope** boundaries.
+3. Which **validation commands** you will run (`cd gitnexus && npm test`, `npx tsc --noEmit`).
 
-On very long threads, the human may add *“Remember: apply all AGENTS.md rules”* to re-weight rule tokens against context dilution.
+On long threads, *"Remember: apply all AGENTS.md rules"* re-weights these instructions against context dilution.
 
 ## Claude Code hooks
 
-Hooks enforce gates that prompts cannot. In **Claude Code**, **PreToolUse** hooks can block tools such as `git_commit` until checks pass. Adapt to this repo: e.g. `cd gitnexus && npm test` before commit.
+**PreToolUse** hooks can block tools (e.g. `git_commit`) until checks pass. Adapt to this repo: `cd gitnexus && npm test` before commit.
 
-## Context budget (Cursor / standards)
+## Context budget
 
-Generic “core standards” playbooks are often long and stack-specific. For this monorepo, commands and gotchas live under **Cursor Cloud specific instructions** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split domain rules into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules live in **`.cursor/index.mdc`** (YAML frontmatter with `alwaysApply: true`). **Claude Code:** optionally load a **`STANDARDS.md`** only when needed (e.g. *“When writing new code, read STANDARDS.md”*) to save context.
+Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.md](CONTRIBUTING.md)**. If always-on rules grow, split into **`.cursor/rules/*.mdc`** (globs). **Cursor:** project-wide rules in `.cursor/index.mdc`. **Claude Code:** load `STANDARDS.md` only when needed.
 
-## Reference Documentation
+## Reference docs
 
-- **This repository:** **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**.
-- **Cursor:** `.cursor/index.mdc` (always-on rules); optional `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` is deprecated — see `.cursor/index.mdc`.
-- **Optional local files:** `NOTES.md` (short vendor-neutral project snapshot). For handoffs, keep notes local (e.g., a scratch file outside the repo) rather than committing `HANDOFF.md`.
-- **GitNexus:** skills under `.claude/skills/gitnexus/`; machine-oriented rules in the `gitnexus:start` … `gitnexus:end` block below.
+- **[ARCHITECTURE.md](ARCHITECTURE.md)**, **[CONTRIBUTING.md](CONTRIBUTING.md)**, **[GUARDRAILS.md](GUARDRAILS.md)**
+- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Typed 6-stage DAG inside the `parse` phase; language-specific behavior behind `inferImplicitReceiver` / `selectDispatch` hooks on `LanguageProvider`. Shared code in `gitnexus/src/core/ingestion/` must not name languages. Types: `gitnexus/src/core/ingestion/call-types.ts`.
+- **Cursor:** `.cursor/index.mdc` (always-on); `.cursor/rules/*.mdc` (glob-scoped). Legacy `.cursorrules` deprecated.
+- **GitNexus:** skills in `.claude/skills/gitnexus/`; MCP rules in `gitnexus:start` block below.
 
 ## Changelog
 
 | Date | Version | Change |
 |------|---------|--------|
+| 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. |
 | 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. |
-| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication (was inlined in Reference Docs bullet). |
-| 2026-03-23 | 1.1.0 | Updated agent instructions (sections, references, Cursor layout). |
-| 2026-03-22 | 1.0.0 | Added structured agent header and changelog. |
+| 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication. |
+| 2026-03-23 | 1.1.0 | Updated agent instructions, references, Cursor layout. |
+| 2026-03-22 | 1.0.0 | Initial structured header and changelog. |
 
 ---
 
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.
 
-> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+> If any tool warns the index is stale, run `npx gitnexus analyze` first.
 
 ## Always Do
 
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+- **MUST run impact analysis before editing any symbol.** `gitnexus_impact({target: "symbolName", direction: "upstream"})` — report blast radius to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** — verify only expected symbols and flows are affected.
+- **MUST warn the user** if impact returns HIGH or CRITICAL risk.
+- Explore unfamiliar code with `gitnexus_query({query: "concept"})` (process-grouped, ranked) instead of grepping.
+- Full context on a symbol: `gitnexus_context({name: "symbolName"})`.
 
 ## When Debugging
 
-1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
-2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
-3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
-4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+1. `gitnexus_query({query: "<error or symptom>"})` — find related execution flows
+2. `gitnexus_context({name: "<suspect function>"})` — callers, callees, process participation
+3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace flow step by step
+4. Regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})`
 
 ## When Refactoring
 
-- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
-- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
-- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+- **Rename:** `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Graph edits are safe; text_search edits need manual review.
+- **Extract/Split:** `gitnexus_context` (incoming/outgoing refs) then `gitnexus_impact` (upstream callers) before moving code.
+- **After any refactor:** `gitnexus_detect_changes({scope: "all"})` to verify scope.
 
 ## Never Do
 
-- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
-- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+- Edit a symbol without running `gitnexus_impact` first.
+- Ignore HIGH/CRITICAL risk warnings.
+- Rename with find-and-replace — use `gitnexus_rename`.
+- Commit without `gitnexus_detect_changes()`.
+- Add language-specific behavior to shared ingestion code (`gitnexus/src/core/ingestion/`) — use a `LanguageProvider` hook. Seeing `provider.mroStrategy === 'xxx'` or an import from `languages/xxx.ts` in shared code means stop and add a hook.
 
 ## Tools Quick Reference
 
-| Tool | When to use | Command |
+| Tool | When to use | Example |
 |------|-------------|---------|
+| `list_repos` | Discover indexed repos | `gitnexus_list_repos({})` |
 | `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
 | `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
 | `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
 | `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
 | `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
 | `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+| `api_impact` | Pre-change API route impact | `gitnexus_api_impact({route: "/api/users", method: "GET"})` |
+| `route_map` | Route → handler → consumer map | `gitnexus_route_map({})` |
+| `tool_map` | MCP/RPC tool definitions | `gitnexus_tool_map({})` |
+| `shape_check` | Response shape vs consumer access | `gitnexus_shape_check({route: "/api/users"})` |
+| `group_list` | List repo groups | `gitnexus_group_list({})` |
+| `group_query` | Cross-repo search in a group | `gitnexus_group_query({name: "myGroup", query: "auth"})` |
+| `group_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` |
+| `group_contracts` | Inspect group contracts | `gitnexus_group_contracts({name: "myGroup"})` |
+| `group_status` | Group staleness report | `gitnexus_group_status({name: "myGroup"})` |
 
 ## Impact Risk Levels
 
 | Depth | Meaning | Action |
 |-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=1 | WILL BREAK — direct callers/importers | MUST update |
 | d=2 | LIKELY AFFECTED — indirect deps | Should test |
 | d=3 | MAY NEED TESTING — transitive | Test if critical path |
 
@@ -119,87 +124,80 @@ This project is indexed by GitNexus as **GitNexus** (4325 symbols, 10556 relatio
 
 | Resource | Use for |
 |----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/GitNexus/context` | Codebase overview, index freshness |
 | `gitnexus://repo/GitNexus/clusters` | All functional areas |
 | `gitnexus://repo/GitNexus/processes` | All execution flows |
 | `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
 
 ## Self-Check Before Finishing
 
-Before completing any code modification task, verify:
 1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. `gitnexus_detect_changes()` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
+2. No HIGH/CRITICAL warnings were ignored
+3. `gitnexus_detect_changes()` confirms expected scope
+4. All d=1 dependents were updated
 
 ## Keeping the Index Fresh
 
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
 ```bash
-npx gitnexus analyze
+npx gitnexus analyze              # basic refresh
+npx gitnexus analyze --embeddings # preserve embeddings
 ```
 
-If the index previously included embeddings, preserve them by adding `--embeddings`:
+Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). Running without `--embeddings` deletes existing vectors.
 
-```bash
-npx gitnexus analyze --embeddings
-```
+> Claude Code: PostToolUse hook handles this after `git commit` and `git merge`.
 
-To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+## CLI Skills
 
-> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
-
-## CLI
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+| Task | Skill file |
+|------|-----------|
+| Architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Debugging / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Refactoring | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools/resources/schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| CLI commands (index, status, clean, wiki) | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
 
 <!-- gitnexus:end -->
 
-## Cursor Cloud specific instructions
+## Repo reference
 
-### Repository structure
+### Packages
 
-This is a monorepo with two main products and supporting config packages:
-
-| Component | Path | Purpose |
-|-----------|------|---------|
-| **GitNexus CLI/Core** | `gitnexus/` | Main product — TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
-| **GitNexus Web UI** | `gitnexus-web/` | React/Vite browser app — graph explorer + AI chat. Runs entirely in WASM. |
-| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace (no build). |
-| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor (no build). |
-| SWE-bench Eval | `eval/` | Python evaluation harness (optional; needs Docker + LLM API keys). |
+| Package | Path | Purpose |
+|---------|------|---------|
+| **CLI/Core** | `gitnexus/` | TypeScript CLI, indexing pipeline, MCP server. Published to npm. |
+| **Web UI** | `gitnexus-web/` | React/Vite thin client. All queries via `gitnexus serve` HTTP API. |
+| **Shared** | `gitnexus-shared/` | Shared TypeScript types and constants. |
+| Claude Plugin | `gitnexus-claude-plugin/` | Static config for Claude marketplace. |
+| Cursor Integration | `gitnexus-cursor-integration/` | Static config for Cursor editor. |
+| Eval | `eval/` | Python evaluation harness (Docker + LLM API keys). |
 
 ### Running services
 
-- **CLI/Core**: `cd gitnexus && npm run dev` (tsx watch mode) or `npm run build && node dist/cli/index.js <command>`
-- **Web UI**: `cd gitnexus-web && npm run dev` (Vite on port 5173)
-- **Backend mode**: `cd <indexed-repo> && node /workspace/gitnexus/dist/cli/index.js serve` (HTTP API on port 3741 by default)
+```bash
+cd gitnexus && npm run dev                 # CLI: tsx watch mode
+cd gitnexus-web && npm run dev             # Web UI: Vite on port 5173
+npx gitnexus serve                         # HTTP API on port 4747 (from any indexed repo)
+```
 
 ### Testing
 
 **CLI / Core (`gitnexus/`)**
-- **Unit tests**: `cd gitnexus && npm test` (vitest, ~2000 tests)
-- **Integration tests**: `cd gitnexus && npm run test:integration` (vitest, ~1850 tests). Two LadybugDB file-locking tests (`lbug-core-adapter`, `search-core`) may fail in containerized environments due to `/tmp` locking limitations — this is a known environment issue, not a code bug.
-- **TypeScript check**: `cd gitnexus && npx tsc --noEmit`
+- `npm test` — full vitest suite (~2000 tests)
+- `npm run test:unit` — unit tests only
+- `npm run test:integration` — integration (~1850 tests). LadybugDB file-locking tests may fail in containers (known env issue).
+- `npx tsc --noEmit` — typecheck
 
 **Web UI (`gitnexus-web/`)**
-- **Unit tests**: `cd gitnexus-web && npm test` (vitest, ~200 tests)
-- **E2E tests**: `cd gitnexus-web && E2E=1 npx playwright test` (Playwright, 5 tests — requires `gitnexus serve` + `npm run dev` running)
-- **TypeScript check**: `cd gitnexus-web && npx tsc -b --noEmit`
+- `npm test` — vitest (~200 tests)
+- `npm run test:e2e` — Playwright (7 spec files; requires `gitnexus serve` + `npm run dev`)
+- `npx tsc -b --noEmit` — typecheck
 
-No separate lint command is configured; TypeScript strict checking serves as the primary static analysis.
+**Pre-commit hook** (`.husky/pre-commit`): formatting (prettier via lint-staged) + typecheck for staged packages. Tests do **not** run in pre-commit — CI only.
 
 ### Gotchas
 
-- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift). Native tree-sitter bindings require `python3`, `make`, and `g++` to be present.
-- `tree-sitter-kotlin` and `tree-sitter-swift` are optional dependencies — install warnings for these are expected and non-blocking.
-- The Web UI uses `vite-plugin-wasm` and requires `Cross-Origin-Opener-Policy`/`Cross-Origin-Embedder-Policy` headers for `SharedArrayBuffer` (handled automatically by Vite dev server).
-- There is no ESLint/Prettier configuration in this repo.
+- `npm install` in `gitnexus/` triggers `prepare` (builds via `tsc`) and `postinstall` (patches tree-sitter-swift, builds tree-sitter-proto). Native bindings need `python3`, `make`, `g++`.
+- `tree-sitter-kotlin` and `tree-sitter-swift` are optional — install warnings expected.
+- ESLint configured via `eslint.config.mjs` (TS, React Hooks, unused-imports). No `npm run lint` script; use `npx eslint .`. Prettier runs via lint-staged. CI checks both in `ci-quality.yml`.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index ac4f46aef..d934cd8b6 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1,99 +1,129 @@
 # Architecture — GitNexus
 
-This repository is a **monorepo** with two main products: the **CLI / MCP package** (`gitnexus/`) and the **browser UI** (`gitnexus-web/`). Supporting folders ship editor integrations and plugins without changing the core graph engine.
+Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`).
 
 ## Repository layout
 
 | Path | Role |
 |------|------|
-| `gitnexus/` | Published npm package `gitnexus`: CLI, MCP server (stdio), local HTTP API for bridge mode, ingestion pipeline, LadybugDB graph, embeddings (optional). |
-| `gitnexus-web/` | Vite + React UI: in-browser indexing (WASM), graph visualization, optional connection to `gitnexus serve`. |
-| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Packaged **skills** and plugin metadata so agents discover the same workflows as documented in `AGENTS.md`. |
-| `eval/` | Evaluation harnesses and docs for benchmarking tool usage. |
-| `.github/` | CI workflows (quality, unit, integration, E2E) and composite actions. |
+| `gitnexus/` | npm package `gitnexus`: CLI, MCP server (stdio), HTTP API, ingestion pipeline, LadybugDB graph, embeddings. |
+| `gitnexus-web/` | Vite + React thin client: graph explorer + AI chat. All queries via `gitnexus serve` HTTP API. |
+| `gitnexus-shared/` | Shared TypeScript types and constants (consumed by CLI and Web). |
+| `.claude/`, `gitnexus-claude-plugin/`, `gitnexus-cursor-integration/` | Agent skills and plugin metadata. |
+| `eval/` | Evaluation harnesses for benchmarking tool usage. |
+| `.github/` | CI workflows + composite actions (`setup-gitnexus/`, `setup-gitnexus-web/`). |
 
 ## End-to-end flow: index → graph → tools
 
-1. **Ingestion** (`gitnexus analyze`)  
-   - Entry: `gitnexus/src/cli/analyze.ts` → `runPipelineFromRepo` in `gitnexus/src/core/ingestion/pipeline.ts`.  
-   - The pipeline is structured as a **DAG (Directed Acyclic Graph)** of named phases (see [Pipeline Phase DAG](#pipeline-phase-dag) below).  
-   - Output is loaded into **LadybugDB** under **`.gitnexus/`** at the repo root (`lbug/`, `meta.json`, etc.). Optional **FTS** indexes and **embeddings** attach to the same store.  
-   - The repo is registered in **`~/.gitnexus/registry.json`** so MCP can find it from any working directory.
+1. **Ingestion** — `analyze.ts` → `runFullAnalysis` (`run-analyze.ts`) → `runPipelineFromRepo` (`pipeline.ts`). DAG of 12 phases builds a `KnowledgeGraph` in memory, then loads into LadybugDB under `.gitnexus/`. Repo registered in `~/.gitnexus/registry.json` for MCP discovery.
 
-2. **Persistence & metadata**  
-   - `gitnexus/src/storage/repo-manager.ts` — paths, registry, cleanup of legacy Kuzu artifacts.  
-   - `gitnexus/src/core/lbug/lbug-adapter.ts` — graph load, queries, embedding restore batches.
+2. **Persistence** — `repo-manager.ts` (paths, registry, KuzuDB cleanup). `lbug-adapter.ts` (graph load, queries, embedding batches).
 
-3. **Query & agents**  
-   - **MCP (stdio):** `gitnexus/src/cli/mcp.ts` → `startMCPServer` → `LocalBackend` (`gitnexus/src/mcp/local/local-backend.ts`) opens registered repos and serves **tools** from `gitnexus/src/mcp/tools.ts` and **resources** from `gitnexus/src/mcp/resources.ts`.  
-   - **Bridge HTTP:** `gitnexus/src/cli/serve.ts` → Express app in `gitnexus/src/server/api.ts` (CORS-limited) exposes REST + MCP-over-HTTP for the web UI.  
-   - **CLI tools (no MCP):** `gitnexus query`, `context`, `impact`, `cypher` in `gitnexus/src/cli/tool.ts` call the same backend for scripts and CI.
+3. **Query layer** — three interfaces to the same backend:
+   - **MCP (stdio):** `mcp.ts` → `LocalBackend` → tools (`tools.ts`) + resources (`resources.ts`)
+   - **HTTP bridge:** `serve.ts` → Express (`api.ts`, `mcp-http.ts`) for web UI
+   - **CLI direct:** `gitnexus query|context|impact|cypher` in `tool.ts`
 
-4. **Staleness**  
-   - `gitnexus/src/mcp/staleness.ts` compares indexed `lastCommit` to `HEAD` and surfaces hints when the graph is behind git.
+4. **Staleness** — `staleness.ts` compares indexed `lastCommit` to `HEAD`, surfaces hints.
 
-## MCP tools (summary)
+## MCP tools
 
 | Tool | Purpose |
 |------|---------|
-| `list_repos` | Discover indexed repositories when more than one is registered. |
-| `query` | Natural-language / keyword search over the graph (hybrid BM25 + optional vectors). |
-| `cypher` | Ad hoc **Cypher** against the schema (see resource `gitnexus://repo/{name}/schema`). |
-| `context` | Callers, callees, processes for one symbol (with disambiguation). |
-| `impact` | Blast radius (upstream/downstream) with depth and risk summary. |
-| `detect_changes` | Map git diffs to affected symbols and processes. |
-| `rename` | Graph-assisted rename with `dry_run` preview (`graph` vs `text_search` confidence). |
+| `list_repos` | Discover indexed repos |
+| `query` | Hybrid BM25 + vector search over the graph |
+| `cypher` | Ad hoc Cypher against the schema |
+| `context` | Callers, callees, processes for one symbol |
+| `impact` | Blast radius (upstream/downstream) with risk summary |
+| `detect_changes` | Map git diffs to affected symbols and processes |
+| `rename` | Graph-assisted multi-file rename with `dry_run` preview |
+| `api_impact` | Pre-change impact report for an API route handler |
+| `route_map` | API route → handler → consumer mappings |
+| `tool_map` | MCP/RPC tool definitions and handlers |
+| `shape_check` | Response shape vs consumer property access mismatches |
+| `group_list` | List repo groups or details for one group |
+| `group_query` | Cross-repo search in a group (reciprocal rank fusion) |
+| `group_sync` | Rebuild group Contract Registry (`contracts.json`) |
+| `group_contracts` | Inspect group contracts and cross-links |
+| `group_status` | Index and Contract Registry staleness per repo in a group |
 
 ## Where to change what
 
-| If you are changing… | Start in… |
-|----------------------|-----------|
-| CLI commands / flags | `gitnexus/src/cli/` (`index.ts`, per-command modules). |
-| Parsing or graph construction | `gitnexus/src/core/ingestion/pipeline-phases/` (individual phase files), `pipeline.ts` (orchestrator). |
-| Graph schema / DB access | `gitnexus/src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`), `gitnexus/src/mcp/core/lbug-adapter.ts` if MCP-specific. |
-| MCP protocol, tools, resources | `gitnexus/src/mcp/server.ts`, `tools.ts`, `resources.ts`. |
-| Search ranking | `gitnexus/src/core/search/` (BM25, hybrid fusion). |
-| Embeddings | `gitnexus/src/core/embeddings/`, phases in `analyze.ts`. |
-| Wiki generation | `gitnexus/src/core/wiki/`. |
-| Web UI behavior | `gitnexus-web/src/` (components, workers, graph client). |
-| CI | `.github/workflows/*.yml`, `.github/actions/setup-gitnexus/`. |
+| Concern | Start in |
+|---------|----------|
+| CLI commands/flags | `src/cli/` (`index.ts`, per-command modules) |
+| Parsing/graph construction | `src/core/ingestion/pipeline-phases/` + `pipeline.ts` |
+| Graph schema/DB | `src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`) |
+| MCP tools/resources | `src/mcp/server.ts`, `tools.ts`, `resources.ts` |
+| Search ranking | `src/core/search/` (BM25, hybrid fusion) |
+| Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` |
+| Wiki generation | `src/core/wiki/` |
+| Language support | `src/core/ingestion/languages/` + `tree-sitter-queries.ts` + `gitnexus-shared/src/languages.ts` |
+| Import resolution | `src/core/ingestion/import-processor.ts` + `import-resolvers/configs/` + `model/resolution-context.ts` |
+| Call resolution/MRO | `src/core/ingestion/call-processor.ts` + `model/resolve.ts` |
+| Type extraction | `src/core/ingestion/type-extractors/` |
+| Worker pool | `src/core/ingestion/workers/` |
+| Web UI | `gitnexus-web/src/` |
+| CI | `.github/workflows/*.yml`, `.github/actions/` |
+
+> Paths above are relative to `gitnexus/` unless they start with `gitnexus-web/` or `.github/`.
+
+---
 
 ## Pipeline Phase DAG
 
-The ingestion pipeline is a DAG of named phases. Each phase is defined in its own file under `gitnexus/src/core/ingestion/pipeline-phases/` with explicit dependencies, typed inputs, and typed outputs.
+12 phases defined in `gitnexus/src/core/ingestion/pipeline-phases/`, each with explicit `deps` and typed output.
 
 ```
 scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
   → crossFile → mro → communities → processes
 ```
 
-### Phase files
+| Phase | File | Deps | Output |
+|-------|------|------|--------|
+| `scan` | `scan.ts` | (root) | File paths + sizes |
+| `structure` | `structure.ts` | `scan` | File/Folder nodes, CONTAINS edges, `allPathSet` |
+| `markdown` | `markdown.ts` | `structure` | Section nodes, cross-link edges from .md/.mdx |
+| `cobol` | `cobol.ts` | `structure` | COBOL program/paragraph/section nodes (regex, no tree-sitter) |
+| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Symbol nodes, IMPORTS/CALLS/EXTENDS edges, extracted routes/tools/ORM queries |
+| `routes` | `routes.ts` | `parse` | Route nodes + HANDLES_ROUTE edges (Next.js, Expo, PHP, decorators) |
+| `tools` | `tools.ts` | `parse` | Tool nodes + HANDLES_TOOL edges |
+| `orm` | `orm.ts` | `parse` | QUERIES edges (Prisma, Supabase) |
+| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological import order |
+| `mro` | `mro.ts` | `crossFile`, `structure` | METHOD_OVERRIDES + METHOD_IMPLEMENTS edges |
+| `communities` | `communities.ts` | `mro`, `structure` | Community nodes + MEMBER_OF edges (Leiden algorithm) |
+| `processes` | `processes.ts` | `communities`, `routes`, `tools`, `structure` | Process nodes + STEP_IN_PROCESS edges |
 
-| Phase | File | Dependencies | What it does |
-|-------|------|-------------|--------------|
-| `scan` | `scan.ts` | (root) | Walk repo filesystem, collect paths + sizes |
-| `structure` | `structure.ts` | `scan` | Build File/Folder nodes + CONTAINS edges |
-| `markdown` | `markdown.ts` | `structure` | Extract headings and cross-links from .md/.mdx |
-| `cobol` | `cobol.ts` | `structure` | Regex-based COBOL/JCL extraction |
-| `parse` | `parse.ts` + `parse-impl.ts` | `structure`, `markdown`, `cobol` | Chunked tree-sitter parse, import/call/heritage resolution |
-| `routes` | `routes.ts` | `parse` | Route registry (Next.js, Expo, PHP, decorator-based) |
-| `tools` | `tools.ts` | `parse` | MCP/RPC tool detection |
-| `orm` | `orm.ts` | `parse` | Prisma/Supabase ORM query edges |
-| `crossFile` | `cross-file.ts` + `cross-file-impl.ts` | `parse`, `routes`, `tools`, `orm` | Cross-file type propagation in topological order |
-| `mro` | `mro.ts` | `crossFile` | Method Resolution Order, METHOD_OVERRIDES edges |
-| `communities` | `communities.ts` | `mro` | Leiden community detection |
-| `processes` | `processes.ts` | `communities`, `routes`, `tools` | Execution flow detection, Route/Tool → Process links |
+**Non-phase files in the same directory:** `parse-impl.ts`, `cross-file-impl.ts` (implementation), `wildcard-synthesis.ts` (whole-module import expansion), `orm-extraction.ts` (sequential ORM fallback), `types.ts`, `runner.ts`, `index.ts`.
+
+### DAG runner
+
+`runner.ts` — static phase graph, no plugins, compile-time type safety.
+
+1. **Validation** — Kahn's topological sort. Rejects on: duplicate names, missing deps, cycles (DFS traces the concrete cycle path, e.g., `A -> B -> C -> A`, plus count of transitively blocked dependents).
+
+2. **Execution** — sequential in topological order. Each phase receives:
+   - `ctx: PipelineContext` — shared mutable `KnowledgeGraph`, `repoPath`, progress callback, options
+   - `deps: ReadonlyMap<string, PhaseResult>` — **declared deps only** (runner filters the results map to prevent hidden coupling)
+
+3. **Error handling** — wraps phase errors with the phase name, emits terminal `error` progress event, swallows progress handler errors to preserve the original cause.
+
+4. **Timing** — per-phase `durationMs` in `PhaseResult`, dev-mode console logging.
+
+**Design patterns:**
+- **Single graph accumulator** — all phases mutate the same `KnowledgeGraph` in `ctx`; the graph is the primary output.
+- **Typed phase access** — `getPhaseOutput<T>(deps, 'name')` for type-safe upstream results.
+- **Binding accumulator lifecycle** — created in `parse`, disposed by `crossFile` (in `finally`). No other phase should take ownership.
+- **Skippable phases** — `skipGraphPhases` omits MRO/communities/processes (faster tests). `skipWorkers` forces sequential parsing.
 
 ### How to add a new phase
 
-1. Create a new file in `pipeline-phases/` (e.g. `my-phase.ts`)
-2. Define a `PipelinePhase<MyOutput>` object with `name`, `deps`, and `execute(ctx, deps)`
-3. Export it from `pipeline-phases/index.ts`
-4. Add it to the `buildPhaseList()` function in `pipeline.ts`
+1. Create `pipeline-phases/my-phase.ts` with a `PipelinePhase<MyOutput>` (name, deps, execute)
+2. Export from `pipeline-phases/index.ts`
+3. Add to `buildPhaseList()` in `pipeline.ts`
 
 ```typescript
-// pipeline-phases/my-phase.ts
-import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
+import type { PipelinePhase, PhaseResult } from './types.js';
 import { getPhaseOutput } from './types.js';
 import type { ParseOutput } from './parse.js';
 
@@ -101,81 +131,235 @@ export interface MyPhaseOutput { /* ... */ }
 
 export const myPhase: PipelinePhase<MyPhaseOutput> = {
   name: 'myPhase',
-  deps: ['parse'],   // runs after parse completes
+  deps: ['parse'],
   async execute(ctx, deps) {
     const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
-    // ... do work, write to ctx.graph ...
+    // ... write to ctx.graph ...
     return { /* typed output */ };
   },
 };
 ```
 
-### DAG runner
+---
 
-The runner (`pipeline-phases/runner.ts`) validates the DAG at startup (detects cycles and missing deps via topological sort), then executes phases in dependency order. Each phase receives:
-- `ctx: PipelineContext` — shared graph, repoPath, progress callback
-- `deps: Map<string, PhaseResult>` — outputs from all upstream phases
+## Call-Resolution DAG
+
+Typed 6-stage pipeline in `call-processor.ts` (inside the `parse` phase) that resolves method/function calls and emits CALLS edges. Language behavior plugs in at two `LanguageProvider` hook points (stages 3–4); shared code names no languages. Scope: call resolution only — import resolution, type extraction, heritage, and symbol-table population live in other phases.
+
+### Stages
+
+```
+extract-call ──▶ classify-form ──▶ infer-receiver ──▶ select-dispatch ──▶ resolve-target ──▶ emit-edge
+     (1)              (2)            (3)  [hook]       (4)  [hook]         (5)                 (6)
+```
+
+| Stage | Produces | Location |
+|-------|----------|----------|
+| **extract-call** | `ExtractedCallSite` (name, form, receiver, argCount) | `call-extractors/` (per-language); runs in worker |
+| **classify-form** | callForm (`free`/`member`/`constructor`) + arity | `call-analysis.ts` → `inferCallForm`; shared, runs in worker |
+| **infer-receiver** | `ReceiverEnriched` (receiver type finalized) | `call-processor.ts`; shared default chain, then `inferImplicitReceiver` hook |
+| **select-dispatch** | `DispatchDecision` (primary, fallback, ancestryView) | `selectDispatch` hook, falls back to shared default |
+| **resolve-target** | `TieredCandidates` | `model/resolve.ts` → `lookupMethodByOwnerWithMRO` (MRO walk) |
+| **emit-edge** | CALLS edge in graph | `call-processor.ts`; writes edge with confidence tier |
+
+### Provider hooks
+
+Both hooks are optional on `LanguageProvider`. Ruby is the only current implementer.
+
+**`inferImplicitReceiver`** — called after shared infer-receiver defaults. Returns `ImplicitReceiverOverride | null`.
+
+| | |
+|---|---|
+| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `callNode` (AST), `filePath` |
+| Non-null fields | `callForm`, `receiverName`, `receiverTypeName` (required); `receiverSource: 'implicit-self'` (fixed); `hint?` (opaque, passed to `selectDispatch`) |
+| Null | Keep existing `ReceiverEnriched` state |
+
+**`selectDispatch`** — called after infer-receiver (including hook). Returns `DispatchDecision | null`; null uses shared default (constructor → `primary:'constructor'`; typed receiver → `primary:'owner-scoped'`; else → `primary:'free'`).
+
+| | |
+|---|---|
+| Inputs | `calledName`, `callForm`, `receiverName`, `receiverTypeName`, `receiverSource`, `hint` |
+| Non-null fields | `primary: 'owner-scoped' \| 'free' \| 'constructor'`; `fallback?: 'free-arity-narrowed'`; `ancestryView?: 'instance' \| 'singleton'`; `hint?` |
+
+**`DispatchDecision` field semantics:**
+- `primary: 'owner-scoped'` — MRO walk from receiver's type; used when receiver type is known.
+- `fallback: 'free-arity-narrowed'` — after owner-scoped miss, search free-call candidates by arity only (Ruby uses this for implicit-self calls that miss their owner's MRO).
+- `ancestryView: 'singleton'` — walk singleton/class ancestry instead of instance ancestry (Ruby `def self.foo` bodies, so `extend`-ed methods are found).
+
+### Adding language behavior
+
+1. **Implicit receivers** — implement `inferImplicitReceiver`: return null if call already has a receiver; otherwise use `findEnclosingClassInfo` (`ast-helpers.ts`) to find the enclosing context, return `ImplicitReceiverOverride` with `receiverSource: 'implicit-self'`, and optionally set `hint` for `selectDispatch`.
+2. **Custom dispatch** — implement `selectDispatch`: inspect `receiverSource` and `hint`, return `DispatchDecision` with `primary`, optional `fallback`, optional `ancestryView`; return null to keep shared defaults.
+3. **MRO strategy** — confirm `mroStrategy` is `'first-wins'`, `'c3'`, `'ruby-mixin'`, or `'none'`; consumed by `lookupMethodByOwnerWithMRO`.
+
+**Ruby example** (`languages/ruby.ts` + `utils/ruby-self-call.ts`): `inferImplicitReceiver` rewrites bare-identifier calls to `self.method` and sets `hint` to `'instance'`/`'singleton'`; `selectDispatch` uses hint for `ancestryView` and adds `fallback: 'free-arity-narrowed'` for implicit-self calls.
+
+### Code references
+
+| Module | Purpose |
+|--------|---------|
+| `core/ingestion/call-types.ts` | DAG types: `ReceiverEnriched`, `DispatchDecision`, `ImplicitReceiverOverride` |
+| `core/ingestion/language-provider.ts` | Hook signatures: `inferImplicitReceiver`, `selectDispatch` |
+| `core/ingestion/call-processor.ts` | `processCalls`: stages 3–6 |
+| `core/ingestion/model/resolve.ts` | `lookupMethodByOwnerWithMRO`: stage 5 MRO walk |
+| `core/ingestion/languages/ruby.ts` | Both hooks + `mroStrategy: 'ruby-mixin'` |
+| `core/ingestion/utils/ruby-self-call.ts` | Bare-call rewrite for `inferImplicitReceiver` |
+
+---
+
+## Language-agnostic graph feeding
+
+16 languages → single unified graph. Four abstraction layers:
+
+```
+ Unified Graph Schema (44 node types, 21 relationship types)
+           ↑
+ Unified Resolution (3-tier name lookup + MRO walk)
+           ↑
+ Language Providers (import semantics, type config, export checker, MRO strategy)
+           ↑
+ Tree-Sitter Queries (per-language S-expressions, unified capture tags)
+```
+
+### Language providers
+
+Each language implements `LanguageProvider` (`language-provider.ts`). Key fields:
+
+| Field | Purpose |
+|-------|---------|
+| `id`, `extensions` | Language identity and file matching |
+| `treeSitterQueries` | S-expression queries for AST extraction |
+| `importSemantics` | `named` / `wildcard-leaf` / `wildcard-transitive` / `namespace` |
+| `importResolver` | Language-specific path → file resolution |
+| `exportChecker` | Public/exported symbol detection |
+| `typeConfig` | Type annotation extraction rules |
+| `mroStrategy` | `first-wins` / `c3` / `none` |
+
+16 providers in `languages/index.ts` via `satisfies Record<SupportedLanguages, LanguageProvider>` — missing a language is a compile error.
+
+### Unified capture tags
+
+Per-language tree-sitter queries use different AST node names but produce the **same semantic capture tags**: `@definition.class`, `@definition.function`, `@call.name`, `@import.source`, `@heritage.extends`. Downstream extraction needs no language branching. Defined in `tree-sitter-queries.ts`.
+
+### Import resolution
+
+Per-language import resolution uses the **configs + factory** pattern (like call/method/class extractors). Each language declares an `ImportResolutionConfig` in `import-resolvers/configs/`, listing an ordered chain of `ImportResolverStrategy` functions. `createImportResolver()` (in `resolver-factory.ts`) composes them: first non-null result wins. Low-level helpers shared across strategies live alongside the configs in `import-resolvers/` (e.g. `go.ts`, `rust.ts`, `python.ts`).
+
+Unified 3-tier algorithm (`model/resolution-context.ts`), per-language `importSemantics` controls which tier activates:
+
+| Tier | Confidence | Mechanism |
+|------|-----------|-----------|
+| 1 — same-file | 0.95 | Symbol table for caller's file |
+| 2 — import-scoped | 0.9 | `NamedImportMap` chains (named) or all files in `importMap` (wildcard) |
+| 3 — global | 0.5 | O(1) index lookups: class, impl, callable. Fallback only |
+
+| Import strategy | Languages | Behavior |
+|----------------|-----------|----------|
+| `named` | TS, JS, Java, C#, Rust, PHP, Kotlin | Only explicitly imported names visible |
+| `wildcard-leaf` | Go, Ruby, Swift, Dart | Whole-package import, no transitive re-exports |
+| `wildcard-transitive` | C, C++ | `#include` closure chains through re-exports |
+| `namespace` | Python | Module aliases resolved at call site |
+
+### Chunked parse-and-resolve
+
+`parse` processes files in ~20 MB byte-budget chunks to bound memory. Per chunk:
+1. Worker pool dispatches files (or sequential fallback via `skipWorkers`)
+2. Each worker: detect language → load grammar → run queries → return unified `ParseWorkerResult`
+3. Synthesize wildcard bindings (`wildcard-synthesis.ts`)
+4. Resolve imports and heritage
+5. Collect `BindingAccumulator` entries for cross-file propagation
+
+Workers: `workers/worker-pool.ts`, `workers/parse-worker.ts`.
+
+### Heritage and MRO
+
+All languages emit unified `ExtractedHeritage` (child, parent, `EXTENDS`/`IMPLEMENTS`). MRO phase walks the heritage graph using per-language strategy:
+- **`first-wins`** — Java, C#, C++, TS, Ruby, Go
+- **`c3`** — Python (C3 linearization)
+- **`none`** — single-inheritance languages
+
+Unified walk: `lookupMethodByOwnerWithMRO()` in `model/resolve.ts`.
+
+---
+
+## Full analysis flow
+
+`runFullAnalysis` in `run-analyze.ts` orchestrates everything around the pipeline:
+
+```
+CLI (analyze.ts) → runFullAnalysis(repoPath, options, callbacks)
+  1. Early exit if lastCommit == HEAD (unless --force)     [0%]
+  2. Cache existing embeddings from prior index             [0%]
+  3. runPipelineFromRepo() → KnowledgeGraph                [0-60%]
+  4. Clean up legacy KuzuDB files                          [60%]
+  5. initLbug() → loadGraphToLbug() via CSV streaming      [60-85%]
+  6. Create FTS indexes (File, Function, Class, Method...) [85-90%]
+  7. Restore cached embeddings (batch insert)              [88%]
+  8. Generate new embeddings if --embeddings               [90-98%]
+  9. Save metadata + register repo + update .gitignore     [98-100%]
+ 10. Generate AI context files (AGENTS.md, CLAUDE.md)      [100%]
+```
+
+**Options:** `--force` (rebuild regardless), `--embeddings` (opt-in, skipped if >50k nodes), `--skipGit`, `--noStats`.
+
+## Storage
+
+```
+<repo>/.gitnexus/
+  ├── lbug           # LadybugDB database
+  ├── lbug.wal       # Write-ahead log
+  ├── lbug.lock      # Single-writer lock
+  └── meta.json      # lastCommit, indexedAt, stats
+
+~/.gitnexus/
+  └── registry.json  # Global repo registry (MCP discovery)
+```
+
+Managed by `repo-manager.ts`.
+
+## LadybugDB schema
+
+Defined in `lbug/schema.ts`. Separate node tables per type, single `CodeRelation` table.
+
+**Node tables:** File, Folder, Function, Class, Interface, Method, Constructor, CodeElement, Struct, Enum, Macro, Typedef, Union, Namespace, Trait, Impl, TypeAlias, Const, Static, Property, Record, Delegate, Annotation, Template, Module, Community, Process, Route, Tool, Section, Embedding.
+
+**Relation types** (`CodeRelation.type`): CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF.
+
+## Embeddings and search
+
+**Embeddings** (`src/core/embeddings/`): Snowflake arctic-embed-xs (384D). Embeddable: File, Function, Class, Method, Interface. Incremental via SHA1 content hash. Separate `Embedding` table.
+
+**Search** (`src/core/search/`): Hybrid BM25 + semantic vector, merged via Reciprocal Rank Fusion (K=60).
 
 ## Known limitations
 
 ### Overloaded method resolution
 
-Method and Constructor node IDs include an arity suffix (`#<paramCount>`) to
-disambiguate overloaded methods. Two overloads with different parameter counts
-produce distinct graph nodes: `Method:file:Class.method#1` vs
-`Method:file:Class.method#2`.
+Node IDs use arity suffix (`#<paramCount>`): `Method:file:Class.method#1` vs `#2`.
 
-**Same-arity overload disambiguation:** When two overloads share the same
-parameter count but differ in types (e.g. `save(int)` vs `save(String)`), a
-type-hash suffix `~type1,type2` is appended to produce distinct node IDs:
-`Method:file:Class.save#1~int` vs `Method:file:Class.save#1~String`. The suffix
-is only added when a same-arity collision is detected within a class and all
-parameters have non-null type annotations. Languages without type info (Python,
-Ruby, JS) fall back to arity-only IDs. TypeScript/JavaScript overload signatures
-are intentionally excluded from type-hashing because they are declaration-only
-contracts that should collapse to the implementation body's node ID. See issue
-\#651.
+**Same-arity disambiguation:** type-hash suffix `~type1,type2` when collision detected and type annotations present. Languages without types (Python, Ruby, JS) use arity-only. TS/JS overload signatures excluded (collapse to implementation body). See #651.
 
-**C++ const-qualified overload disambiguation:** Methods overloaded by const
-qualification (e.g. `begin()` vs `begin() const`) are disambiguated via an
-`isConst` property and a `$const` ID suffix appended to the const-qualified
-variant when a non-const collision exists. The `$const` suffix appears after the
-type-hash suffix: e.g. `Method:file:Container.begin#0$const`.
+**C++ const-qualified:** `$const` suffix after type-hash when non-const collision exists: `Method:file:Container.begin#0$const`.
 
-**Generic/template type preservation in type-hash:** The type-hash suffix uses
-`rawType` (full AST text including generic/template args) rather than the
-simplified `type` from `extractSimpleTypeName`. This means C++ template overloads
-like `process(vector<int>)` vs `process(vector<string>)` produce distinct IDs:
-`~vector<int>` vs `~vector<std::string>`. Java generic overloads like
-`process(List<String>)` vs `process(List<Integer>)` are a compile error due to
-type erasure, so this gap is theoretical for Java.
+**Generic/template types:** type-hash uses `rawType` (full AST text including generics): `~vector<int>` vs `~vector<std::string>`.
 
-**ID stability on first overload:** Type and const tags are collision-only. When
-a class has `save(int)` as its only `save` method, the ID is `save#1` (no tag).
-Adding `save(String)` changes the original to `save#1~int`. This is correct for
-fresh analysis but means IDs are not stable across overload additions. Future
-incremental re-analysis should account for this.
+**ID stability:** collision-only tags mean IDs change when overloads are added. `save#1` becomes `save#1~int` when `save(String)` is added.
 
-**Variadic method matching:** When one side is variadic (`parameterCount`
-undefined) and the other has a fixed count, `METHOD_IMPLEMENTS` edges are
-emitted with confidence 0.7 instead of 1.0. Variadic methods like
-`foo(String... args)` may superficially match `foo(String s)` by type but
-are not guaranteed to be interchangeable across all languages (Java/Kotlin
-accept this via varargs sugar; TypeScript, C#, Rust do not).
+**Variadic matching:** confidence 0.7 when one side is variadic and the other has fixed count.
 
-**Confidence tiering** for `METHOD_IMPLEMENTS` edges:
+**METHOD_IMPLEMENTS confidence tiering:**
 
-| Match quality | Confidence | When |
-|---|---|---|
-| Exact parameter types match | 1.0 | Both sides have `parameterTypes` arrays and they match |
-| Arity (count) matches | 1.0 | Both sides have `parameterCount`, types unavailable |
-| Variadic vs fixed | 0.7 | One side is variadic, other has fixed count |
-| Lenient (insufficient info) | 0.7 | One or both sides lack type and count data |
+| Match quality | Confidence |
+|---|---|
+| Exact parameter types match | 1.0 |
+| Arity match, types unavailable | 1.0 |
+| Variadic vs fixed | 0.7 |
+| Insufficient info | 0.7 |
 
 ## Related docs
 
-- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance.
-- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery.  
-- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents.  
-- [TESTING.md](TESTING.md) — how to run tests.  
-- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage expectations for **this** repo when indexed by GitNexus.
+- [MIGRATION.md](MIGRATION.md) — breaking changes and migration guidance
+- [RUNBOOK.md](RUNBOOK.md) — operational commands and recovery
+- [GUARDRAILS.md](GUARDRAILS.md) — safety boundaries for humans and agents
+- [TESTING.md](TESTING.md) — how to run tests
+- `AGENTS.md` / `CLAUDE.md` — agent workflows and tool usage
diff --git a/CLAUDE.md b/CLAUDE.md
index 8b6f74ab8..af4069fcd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -35,6 +35,7 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 ## Reference Documentation
 
 - **This repository:** [AGENTS.md](AGENTS.md) (Cursor + monorepo notes), [ARCHITECTURE.md](ARCHITECTURE.md), [CONTRIBUTING.md](CONTRIBUTING.md), [GUARDRAILS.md](GUARDRAILS.md).
+- **Call-resolution DAG:** See ARCHITECTURE.md § Call-Resolution DAG. Shared pipeline code in `gitnexus/src/core/ingestion/` must not name languages — use `LanguageProvider` hooks instead (see AGENTS.md).
 - **GitNexus:** `.claude/skills/gitnexus/`; MCP and indexed-repo rules live only in [AGENTS.md](AGENTS.md) (`gitnexus:start` … `gitnexus:end`). See **GitNexus rules** below.
 
 ## Changelog
@@ -50,206 +51,4 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 
 ## GitNexus rules
 
-GitNexus MCP rules are in the `<!-- gitnexus:start -->
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
-
-## Always Do
-
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
-
-## When Debugging
-
-1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
-2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
-3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
-4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
-
-## When Refactoring
-
-- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
-- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
-- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
-
-## Never Do
-
-- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
-- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
-
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
-| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
-| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
-| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
-| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
-| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
-## Resources
-
-| Resource | Use for |
-|----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
-| `gitnexus://repo/GitNexus/clusters` | All functional areas |
-| `gitnexus://repo/GitNexus/processes` | All execution flows |
-| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
-
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. `gitnexus_detect_changes()` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
-
-## Keeping the Index Fresh
-
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
-```bash
-npx gitnexus analyze
-```
-
-If the index previously included embeddings, preserve them by adding `--embeddings`:
-
-```bash
-npx gitnexus analyze --embeddings
-```
-
-To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
-
-> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
-
-## CLI
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
-
-<!-- gitnexus:end -->`  block in **[AGENTS.md](AGENTS.md)** — load that section when working with MCP tools or the graph index.
-
-<!-- gitnexus:start -->
-# GitNexus — Code Intelligence
-
-This project is indexed by GitNexus as **GitNexus** (3298 symbols, 7954 relationships, 185 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
-
-> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
-
-## Always Do
-
-- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
-- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
-- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
-- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
-- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
-
-## When Debugging
-
-1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
-2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
-3. `READ gitnexus://repo/GitNexus/process/{processName}` — trace the full execution flow step by step
-4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
-
-## When Refactoring
-
-- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
-- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
-- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
-
-## Never Do
-
-- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
-- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
-- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
-- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
-
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
-| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
-| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
-| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
-| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
-| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
-## Resources
-
-| Resource | Use for |
-|----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, check index freshness |
-| `gitnexus://repo/GitNexus/clusters` | All functional areas |
-| `gitnexus://repo/GitNexus/processes` | All execution flows |
-| `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace |
-
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. `gitnexus_impact` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. `gitnexus_detect_changes()` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
-
-## Keeping the Index Fresh
-
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
-```bash
-npx gitnexus analyze
-```
-
-If the index previously included embeddings, preserve them by adding `--embeddings`:
-
-```bash
-npx gitnexus analyze --embeddings
-```
-
-To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
-
-> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
-
-## CLI
-
-| Task | Read this skill file |
-|------|---------------------|
-| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
-| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
-| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
-| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
-| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
-| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
-
-<!-- gitnexus:end -->
+See the `<!-- gitnexus:start --> … <!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** for the canonical MCP tools, impact analysis rules, and index instructions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d2d48f017..7f797f9a0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -62,7 +62,7 @@ Commits within a PR may use any style — only the **merged PR title** shows up
 - [ ] Typecheck passes: `npx tsc --noEmit` in `gitnexus/` and `npx tsc -b --noEmit` in `gitnexus-web/`.
 - [ ] No secrets, tokens, or machine-specific paths committed.
 - [ ] Documentation updated if behavior or public CLI/MCP contract changes.
-- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — typecheck + unit tests for staged packages).
+- [ ] Pre-commit hook runs clean (`.husky/pre-commit` — formatting via lint-staged + typecheck for staged packages; tests run in CI only).
 
 ## Code review
 
@@ -77,7 +77,7 @@ Every workflow under `.github/workflows/` MUST declare a top-level `concurrency:
   - Per-PR scope (for `issue_comment`, `pull_request_review*`, `pull_request` meta events): `${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}`
   - `workflow_run` scope (e.g. `ci-report.yml`): `${{ github.workflow }}-${{ github.event.workflow_run.pull_requests[0].number || format('{0}/{1}', github.event.workflow_run.head_repository.full_name, github.event.workflow_run.head_branch) }}` — the fork fallback must be stable across reruns (never `workflow_run.id`, which is per-run-unique and defeats serialization).
   - Global single-slot (manual dispatch utilities): `${{ github.workflow }}`
-  - **Reusable workflows invoked via `workflow_call`:** do NOT use `${{ github.workflow }}` in the group key — in called-workflow context its evaluation is ambiguous and can resolve to the caller's name, which would deadlock against the caller's own group. Use a hardcoded literal prefix and a `github.event_name`-aware expression that falls through to `github.run_id` for reusable invocations (see `ci.yml` for the canonical form).
+  - **Reusable workflows invoked via `workflow_call`:** do NOT use `${{ github.workflow }}` in the group key — in called-workflow context its evaluation is ambiguous and can resolve to the caller's name, which would deadlock against the caller's own group. Use a hardcoded literal prefix and a `github.event_name`-aware expression that falls through to `github.run_id` for reusable invocations (see `ci.yml` for the canonical form). Approved literal prefixes: `CI-` (`ci.yml`) and `docker-build-push-` (`docker.yml`). The `check-workflow-concurrency.py` validation script must be updated whenever a new approved literal prefix is added.
   - **Merge queue (`merge_group`)**: when this event is added, use `${{ github.workflow }}-${{ github.event.merge_group.head_ref }}` with `cancel-in-progress: false` (every queue entry is a distinct ref; never cancel).
 - **`cancel-in-progress` policy:**
 
@@ -127,6 +127,11 @@ Two publish workflows ship `gitnexus` to npm:
     the cycle from `latest`.
   - `N` is auto-incremented against existing `X.Y.Z-rc.*` entries on the
     registry. First rc for a given base is `rc.1`.
+  - After the npm publish succeeds, the workflow calls `docker.yml` as a
+    reusable workflow to build and push the corresponding RC Docker images
+    (e.g. `ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1`). The images are
+    signed with Cosign; the OIDC identity is `docker.yml@refs/heads/main`
+    (the caller's ref — see README.md § Docker for the verify command).
 
   Idempotency: the workflow pushes an `rc/<HEAD_SHA>` marker tag and a
   `v<RC>` release tag **atomically, before** calling `npm publish`. The guard
@@ -140,6 +145,27 @@ Two publish workflows ship `gitnexus` to npm:
   # then redispatch the workflow with force: true
   ```
 
+  **Docker-only partial failure:** if `publish` succeeds (npm tarball + tags
+  are live) but the `docker` job subsequently fails (e.g. GHCR flakiness),
+  the npm RC is already published and the `rc/<HEAD_SHA>` marker is in place.
+  Re-running `release-candidate.yml` with `force: true` will abort at the
+  "Version already exists on npm" guard. To recover without cutting a new RC:
+
+  ```bash
+  # 1. Manually trigger only the docker workflow, passing the existing RC tag:
+  gh workflow run docker.yml --ref main -f tag=v<RC_VERSION>
+  # (requires a workflow_dispatch trigger on docker.yml — see note below)
+  ```
+
+  Because `docker.yml` intentionally has no `workflow_dispatch` (images are
+  tag-driven by design), the practical recovery options are:
+  - Wait for the next commit on `main`, which will cut a new RC that includes
+    the Docker build.
+  - Manually run `docker build` + `docker push` locally and sign with Cosign
+    against the same digest.
+  - Delete `rc/<HEAD_SHA>` and `v<RC>` tags, then redispatch with `force:
+    true` to re-run the full RC pipeline (cuts a new RC number).
+
 The rc workflow never moves `latest`. To verify after a change, inspect dist-tags:
 
 ```bash
diff --git a/Dockerfile.cli b/Dockerfile.cli
new file mode 100644
index 000000000..d1d4f45a4
--- /dev/null
+++ b/Dockerfile.cli
@@ -0,0 +1,57 @@
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM
+
+# ── Builder ────────────────────────────────────────────────────────────
+# Native modules (tree-sitter-*, onnxruntime-node, node-gyp builds for
+# tree-sitter-proto / tree-sitter-swift) require python3 + a C/C++ toolchain.
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Toolchain for node-gyp / native builds.
+RUN apk add --no-cache python3 make g++ git
+
+# Build gitnexus-shared first — gitnexus depends on it as a workspace.
+COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
+RUN npm ci --prefix gitnexus-shared
+COPY gitnexus-shared ./gitnexus-shared
+RUN npm run build --prefix gitnexus-shared
+
+# Copy the full gitnexus package before installing — `npm ci` triggers
+# `postinstall` (patches tree-sitter-swift, builds the vendored
+# tree-sitter-proto) and `prepare` (compiles TypeScript via scripts/build.js),
+# both of which need the source tree.
+COPY gitnexus ./gitnexus
+RUN npm ci --prefix gitnexus
+
+# Drop dev dependencies for a smaller runtime layer.
+RUN npm prune --omit=dev --prefix gitnexus
+
+# ── Runtime ────────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+
+# curl for the healthcheck; git so `gitnexus` can clone repos at runtime.
+RUN apk add --no-cache curl git
+
+WORKDIR /app
+
+# Pre-create the data directory and hand it to the unprivileged `node` user
+# so the bind-mounted volume is writable without root.
+RUN mkdir -p /data/gitnexus && chown -R node:node /data
+
+COPY --from=builder --chown=node:node /app/gitnexus/dist ./gitnexus/dist
+COPY --from=builder --chown=node:node /app/gitnexus/node_modules ./gitnexus/node_modules
+COPY --from=builder --chown=node:node /app/gitnexus/package.json ./gitnexus/package.json
+COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor
+
+USER node
+
+# The web UI defaults to http://localhost:4747 — keep that contract.
+ENV GITNEXUS_HOME=/data/gitnexus \
+    NODE_ENV=production \
+    PORT=4747
+
+EXPOSE 4747
+
+# Bind to 0.0.0.0 so the server is reachable from the host's mapped port.
+CMD ["node", "gitnexus/dist/cli/index.js", "serve", "--host", "0.0.0.0", "--port", "4747"]
diff --git a/Dockerfile.web b/Dockerfile.web
new file mode 100644
index 000000000..d4f342509
--- /dev/null
+++ b/Dockerfile.web
@@ -0,0 +1,35 @@
+ARG BUILDPLATFORM
+ARG TARGETPLATFORM
+
+FROM --platform=$BUILDPLATFORM node:22-alpine AS builder
+
+WORKDIR /app
+
+COPY gitnexus-shared/package.json gitnexus-shared/package-lock.json ./gitnexus-shared/
+RUN npm ci --prefix gitnexus-shared
+
+COPY gitnexus-shared ./gitnexus-shared
+RUN npm run build --prefix gitnexus-shared
+
+COPY gitnexus-web/package.json gitnexus-web/package-lock.json ./gitnexus-web/
+RUN npm ci --prefix gitnexus-web
+
+COPY gitnexus-web ./gitnexus-web
+RUN npm run build --prefix gitnexus-web
+
+FROM node:22-alpine AS runtime
+
+RUN apk add --no-cache curl
+
+WORKDIR /app
+
+COPY --from=builder /app/gitnexus-web/dist ./dist
+COPY docker-server.mjs ./docker-server.mjs
+
+RUN chown -R node:node /app
+
+USER node
+
+EXPOSE 4173
+
+CMD ["node", "docker-server.mjs"]
diff --git a/GUARDRAILS.md b/GUARDRAILS.md
index 7401c79c5..ac48ab906 100644
--- a/GUARDRAILS.md
+++ b/GUARDRAILS.md
@@ -1,72 +1,69 @@
-# Guardrails — GitNexus (repo + agents)
+# Guardrails — GitNexus
 
-Rules for **human contributors** and **AI agents** working on this codebase or publishing artifacts. These complement `AGENTS.md` / `CLAUDE.md` (which focus on GitNexus-in-GitNexus workflows).
+Rules for **human contributors** and **AI agents**. Complements `AGENTS.md` (workflows) and `CONTRIBUTING.md` (PR process).
 
-## Scope (typical agent session)
+## Scope (least privilege)
 
-When automating changes in this repository, treat scope as **least privilege**:
+- **Read:** Source, tests, docs, public config as needed.
+- **Write:** Only files required for the fix or feature; no unrelated formatting or refactors.
+- **Execute:** Tests, typecheck, documented CLI commands. No destructive commands on user data without approval.
+- **Off-limits:** Other people's machines, production deployments you don't own, credentials you lack permission to use.
 
-- **Read:** Source, tests, docs, public config as needed for the task.  
-- **Write:** Only files required for the requested fix or feature; avoid unrelated formatting or refactors.  
-- **Execute:** Tests, typecheck, and documented CLI commands; do not run destructive commands on user data outside the repo without explicit approval.  
-- **Off-limits:** Other people’s machines, production deployments you don’t own, and credentials you didn’t receive permission to use.
-
-Adjust explicitly if the maintainer defines a different scope for a task.
+Maintainer may widen scope per task.
 
 ---
 
 ## Non-negotiables
 
-1. **Never commit secrets** — API keys, tokens, `.env` with real values, private URLs, or session cookies. Use `.env.example` with placeholders only.  
-2. **Never rename symbols with blind find-and-replace** when working in a GitNexus-indexed project — use the **`rename` MCP tool** with **`dry_run: true` first**, then review `graph` vs `text_search` edits. (There is no separate `gitnexus rename` CLI; renaming goes through MCP or editor integration.)  
-3. **Run impact analysis before editing shared symbols** — use **`impact`** (upstream) for functions/classes/methods others call; do not ignore **HIGH** / **CRITICAL** risk without maintainer sign-off.  
-4. **Prefer `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.  
-5. **Preserve embeddings** — if `.gitnexus/meta.json` shows embeddings, run `npx gitnexus analyze --embeddings` when refreshing the index; plain `analyze` can drop them.
+1. **Never commit secrets** — API keys, tokens, real `.env` values, private URLs, session cookies. Use `.env.example` with placeholders.
+2. **Never rename with find-and-replace** in GitNexus-indexed projects — use `rename` MCP tool with `dry_run: true` first, review `graph` vs `text_search` edits. No separate `gitnexus rename` CLI exists.
+3. **Run impact analysis before editing shared symbols** — `impact` (upstream) for functions/classes/methods others call. Do not ignore HIGH/CRITICAL without maintainer sign-off.
+4. **Run `detect_changes` before commit** — confirm diffs map to expected symbols/processes when the graph is available.
+5. **Preserve embeddings** — if `.gitnexus/meta.json` shows embeddings, use `npx gitnexus analyze --embeddings`; plain `analyze` drops them.
 
 ---
 
 ## Signs (recurring failure patterns)
 
-Use this format: **Trigger → Instruction → Reason**.  
-Append new Signs here when the same mistake repeats (e.g. CI broken twice the same way).
+Format: **Trigger → Instruction → Reason**. Append new Signs when the same mistake repeats.
 
-### Sign: Stale graph after edits
+### Stale graph after edits
 
-- **Trigger:** MCP or resources warn the index is behind `HEAD`, or code search doesn’t match latest commit.  
-- **Instruction:** Run `npx gitnexus analyze` from the repo root (plus `--embeddings` if the project used them).  
-- **Reason:** Tools query LadybugDB built at last analyze; git changes are invisible until re-indexed.
+- **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit.
+- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used).
+- **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed.
 
-### Sign: Embeddings vanished after analyze
+### Embeddings vanished after analyze
 
-- **Trigger:** Semantic search quality drops; `stats.embeddings` in `.gitnexus/meta.json` is 0 after a refresh.  
-- **Instruction:** Re-run `npx gitnexus analyze --embeddings` and confirm `meta.json` reflects stored embeddings.  
-- **Reason:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
+- **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh.
+- **Do:** `npx gitnexus analyze --embeddings`, confirm `meta.json` reflects stored embeddings.
+- **Why:** Embedding generation is opt-in; analyze without the flag does not preserve prior vectors.
 
-### Sign: MCP lists no repos
+### MCP lists no repos
 
-- **Trigger:** MCP stderr says no indexed repos.  
-- **Instruction:** Run `npx gitnexus analyze` in the target repository; verify `npx gitnexus list` shows it.  
-- **Reason:** The MCP server discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
+- **Trigger:** MCP stderr says no indexed repos.
+- **Do:** `npx gitnexus analyze` in the target repo; verify `npx gitnexus list` shows it.
+- **Why:** MCP discovers repos via `~/.gitnexus/registry.json`, populated by analyze.
 
-### Sign: Wrong repo in multi-repo setups
+### Wrong repo in multi-repo setups
 
-- **Trigger:** Query/impact results clearly belong to another project.  
-- **Instruction:** Call `list_repos`, then pass **`repo`** on subsequent tools (or use per-workspace MCP config).  
-- **Reason:** Default target may be ambiguous when multiple repos are registered.
+- **Trigger:** Query/impact results belong to another project.
+- **Do:** Call `list_repos`, then pass `repo` on subsequent tools.
+- **Why:** Default target is ambiguous when multiple repos are registered.
 
-### Sign: LadybugDB lock / “database busy”
+### LadybugDB lock / "database busy"
 
-- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.  
-- **Instruction:** Stop overlapping processes; one writer at a time. Retry analyze or restart MCP.  
-- **Reason:** Embedded DB expects single-process ownership of the store.
+- **Trigger:** Errors opening `.gitnexus/lbug` while MCP and analyze both run.
+- **Do:** Stop overlapping processes (one writer at a time). Retry analyze or restart MCP.
+- **Why:** Embedded DB expects single-process ownership.
 
 ---
 
 ## Publishing & supply chain
 
-- **npm:** Do not publish from unreviewed automation; follow maintainer release process. Bump version intentionally; tag releases to match `package.json`.  
-- **Dependencies:** Prefer minimal, auditable changes to `package.json`; run tests and CI after lockfile updates.  
-- **License:** This project ships under **PolyForm Noncommercial 1.0.0** — do not relicense or imply a different license in docs or metadata without maintainer approval.
+- **npm:** Do not publish from unreviewed automation. Bump version intentionally; tag releases to match `package.json`.
+- **Dependencies:** Minimal, auditable `package.json` changes; run tests and CI after lockfile updates.
+- **License:** PolyForm Noncommercial 1.0.0 — do not relicense without maintainer approval.
 
 ---
 
@@ -74,15 +71,15 @@ Append new Signs here when the same mistake repeats (e.g. CI broken twice the sa
 
 Stop and ask a **human maintainer** when:
 
-- Impact analysis shows **HIGH** / **CRITICAL** risk and the task still requires the change.  
-- You need to alter **CI**, **release**, or **security-sensitive** config.  
-- Requirements conflict (e.g. “speed up analyze” vs “must keep all embeddings on huge repo”).  
+- Impact analysis shows HIGH/CRITICAL risk and the task still requires the change.
+- You need to alter CI, release, or security-sensitive config.
+- Requirements conflict (e.g. "speed up analyze" vs "must keep all embeddings on huge repo").
 - You are unsure whether data loss is acceptable (`clean`, forced migrations, schema changes).
 
 ---
 
 ## Related docs
 
-- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow.  
-- [RUNBOOK.md](RUNBOOK.md) — commands for recovery.  
-- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations.
+- [ARCHITECTURE.md](ARCHITECTURE.md) — components and data flow
+- [RUNBOOK.md](RUNBOOK.md) — commands for recovery
+- [CONTRIBUTING.md](CONTRIBUTING.md) — PR and commit expectations
diff --git a/MIGRATION.md b/MIGRATION.md
index ec9fdabc2..88488b0ae 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -1,5 +1,49 @@
 # Migration Guide
 
+## `impact` tool may now return `{ status: 'ambiguous' }` (PR #888, issue #470)
+
+Before this change the `impact` MCP tool silently picked the first match
+when the `target` name hit multiple symbols (Class → Interface → Function
+→ Method → Constructor priority UNION). This often produced analysis for
+the wrong symbol with no signal back to the caller.
+
+After this change, when the resolver finds more than one viable match
+and the caller supplied none of `target_uid` / `file_path` / `kind`,
+`impact` returns a disambiguation response shaped like:
+
+```json
+{
+  "status": "ambiguous",
+  "message": "Found N symbols matching '<target>'. Use target_uid, file_path, or kind to disambiguate.",
+  "target": { "name": "<target>" },
+  "direction": "upstream",
+  "impactedCount": 0,
+  "risk": "UNKNOWN",
+  "candidates": [
+    { "uid": "...", "name": "...", "kind": "Function", "filePath": "...", "line": 42, "score": 0.76 }
+  ]
+}
+```
+
+### Do I need to migrate?
+
+**Probably not, but check for assumptions.** Callers that unconditionally
+read `result.byDepth` / `result.summary` / `result.affected_processes`
+without first checking `result.status` will now see `undefined` in the
+ambiguous case. The fix is to branch on `result.status === 'ambiguous'`
+first and follow up with `target_uid` (preferred) or `file_path` / `kind`.
+
+The `context` tool's ambiguous response is a strict superset of the
+existing shape — every candidate gains a `score` field, no existing field
+has changed. No migration required for `context` callers.
+
+### What happens on re-index?
+
+Nothing — this is an MCP-surface change only. The graph schema, indexer,
+and stored data are untouched.
+
+---
+
 ## OVERRIDES → METHOD_OVERRIDES (PR #642)
 
 The `OVERRIDES` relationship type has been renamed to `METHOD_OVERRIDES` for
diff --git a/README.md b/README.md
index 65ac7d332..4c273ab47 100644
--- a/README.md
+++ b/README.md
@@ -335,6 +335,155 @@ cd ../gitnexus-web && npm install
 npm run dev
 ```
 
+## Docker
+
+The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`:
+
+| Image                                              | Purpose                                                                |
+| -------------------------------------------------- | ---------------------------------------------------------------------- |
+| `ghcr.io/abhigyanpatwari/gitnexus:latest`          | CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) |
+| `ghcr.io/abhigyanpatwari/gitnexus-web:latest`      | Static web UI (port `4173`)                                            |
+
+> **Heads-up — image rename.** Earlier releases published the web UI under
+> `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
+> bundled backend, that slug now hosts the CLI/server image and the UI moved
+> to `ghcr.io/abhigyanpatwari/gitnexus-web`. The previous tags remain
+> available for pulling, but new versions are only published under the new
+> slugs. Update your `docker run` / compose files accordingly (or just adopt
+> the bundled compose).
+
+### One-command setup
+
+```bash
+docker compose up -d
+```
+
+This starts the server on `http://localhost:4747` and the web UI on
+`http://localhost:4173`. The UI auto-detects the server because the browser
+runs on the host and reaches the container via the mapped port.
+
+A named volume (`gitnexus-data`) persists the global registry, indexes, and
+cloned repos at `/data/gitnexus` inside the server container. To make repos on
+your host machine indexable, set `WORKSPACE_DIR` before bringing the stack up:
+
+```bash
+WORKSPACE_DIR=$HOME/code docker compose up -d
+# Inside the server container the directory is mounted read-only at /workspace.
+docker compose exec gitnexus-server gitnexus index /workspace/my-repo
+```
+
+### Direct `docker run`
+
+```bash
+# Server
+docker run --rm -d \
+  --name gitnexus-server \
+  -p 4747:4747 \
+  -v gitnexus-data:/data/gitnexus \
+  ghcr.io/abhigyanpatwari/gitnexus:latest
+
+# Web UI
+docker run --rm -d \
+  --name gitnexus-web \
+  -p 4173:4173 \
+  ghcr.io/abhigyanpatwari/gitnexus-web:latest
+```
+
+Optional env file (override image tags, container names, ports, workspace dir):
+
+```bash
+cp .env.example .env
+docker compose --env-file .env up -d
+```
+
+### Versioning & supply-chain protection
+
+The Docker images are version-locked to the npm package:
+
+- Stable images are **only published from `vX.Y.Z` git tags** (via `docker.yml`
+  triggered directly by the tag push), and the workflow refuses to build unless
+  the tag exactly matches `gitnexus/package.json`'s version. So
+  `ghcr.io/abhigyanpatwari/gitnexus:1.6.2` is byte-for-byte the same release
+  as `npm install gitnexus@1.6.2` — no drift, no floating builds from `main`.
+- Release-candidate images (e.g. `:1.7.0-rc.1`) are published alongside each
+  RC npm release. They are built by `release-candidate.yml` calling `docker.yml`
+  as a reusable workflow after the RC tag is created and pushed.
+- `:latest` is auto-promoted only from non-prerelease tags by the Docker
+  metadata action, so it always points at a real, npm-published version.
+
+Both images are signed with [Cosign keyless signing][cosign-keyless] using the
+workflow's GitHub OIDC identity, and shipped with build provenance and SBOM
+attestations. **This is your protection against supply-chain attacks**: even if
+an attacker republishes a same-named image elsewhere (or somehow pushes to a
+typo-squatted registry), they cannot forge a Cosign signature tied to
+`abhigyanpatwari/GitNexus`'s `docker.yml`. Always verify before pulling into
+sensitive environments:
+
+**Stable releases** — signed from the `v*` tag ref:
+
+```bash
+cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
+  --certificate-identity-regexp '^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+The regex pins the certificate identity to this repo's `docker.yml` workflow
+**run from a `v*` tag** — rejecting unsigned images, images signed by other
+workflows, and images signed from unprotected refs.
+
+**Release candidates** — signed from `refs/heads/main` (the caller's ref when
+`release-candidate.yml` invokes `docker.yml` as a reusable workflow):
+
+```bash
+cosign verify ghcr.io/abhigyanpatwari/gitnexus:1.7.0-rc.1 \
+  --certificate-identity 'https://github.com/abhigyanpatwari/GitNexus/.github/workflows/docker.yml@refs/heads/main' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+You can also inspect the build provenance and SBOM:
+
+```bash
+cosign download attestation ghcr.io/abhigyanpatwari/gitnexus:1.6.2 \
+  --predicate-type https://slsa.dev/provenance/v1
+```
+
+#### Kubernetes: enforce signatures at admission
+
+For Kubernetes deployments, ship the bundled
+[`ClusterImagePolicy`](deploy/kubernetes/cluster-image-policy.yaml) so the
+[Sigstore policy-controller][policy-controller] rejects any GitNexus pod whose
+image is not signed by this repo's `docker.yml` running from a `vX.Y.Z` tag —
+the same identity the `cosign verify` snippet above pins.
+
+```bash
+# 1. Install the controller (one-time, cluster-wide)
+helm repo add sigstore https://sigstore.github.io/helm-charts && helm repo update
+helm install policy-controller -n cosign-system --create-namespace \
+  sigstore/policy-controller
+
+# 2. Opt your namespace in
+kubectl label namespace <your-ns> policy.sigstore.dev/include=true
+
+# 3. Apply the policy
+kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml
+```
+
+After this, attempting to deploy an unsigned image — or one signed by anything
+other than `abhigyanpatwari/GitNexus`'s `docker.yml` at a `v*` tag — fails the
+admission webhook before a pod is ever created. This turns the verifiable
+signature into an enforced policy, which is the supply-chain control most
+clusters actually need.
+
+[cosign-keyless]: https://docs.sigstore.dev/cosign/signing/overview/
+[policy-controller]: https://docs.sigstore.dev/policy-controller/overview/
+
+### Files
+
+- [Dockerfile.web](Dockerfile.web) — builds `gitnexus-shared` and `gitnexus-web`, then serves the production frontend.
+- [Dockerfile.cli](Dockerfile.cli) — builds the CLI/server (with its native deps) and runs `gitnexus serve --host 0.0.0.0`.
+- [docker-compose.yaml](docker-compose.yaml) — starts both signed images side by side.
+- [.env.example](.env.example) — overrides for image names, container names, ports, and the workspace mount.
+
 The web UI uses the same indexing pipeline as the CLI but runs entirely in WebAssembly (Tree-sitter WASM, LadybugDB WASM, in-browser embeddings). It's great for quick exploration but limited by browser memory for larger repos.
 
 **Local Backend Mode:** Run `gitnexus serve` and open the web UI locally — it auto-detects the server and shows all your indexed repos, with full AI chat support. No need to re-upload or re-index. The agent's tools (Cypher queries, search, code navigation) route through the backend HTTP API automatically.
diff --git a/TESTING.md b/TESTING.md
index 8d267983a..cf481d32b 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -20,9 +20,9 @@ From repository root, unless noted:
 cd gitnexus
 npm install
 npm run build
-npm test                    # unit: vitest run test/unit
+npm test                    # full suite: vitest run
+npm run test:unit           # unit only: vitest run test/unit
 npm run test:integration    # integration suite
-npm run test:all
 npm run test:coverage
 npx tsc --noEmit            # typecheck (matches CI)
 ```
@@ -42,8 +42,11 @@ npm run test:e2e            # Playwright (requires gitnexus serve + npm run dev)
 
 A husky pre-commit hook (`.husky/pre-commit`) runs automatically on every `git commit`:
 
-- **`gitnexus-web/` files staged** → `tsc -b --noEmit` + `vitest run`
-- **`gitnexus/` files staged** → `tsc --noEmit` + `vitest run --project default`
+1. **Formatting** — `lint-staged` runs prettier on staged files
+2. **`gitnexus-web/` files staged** → `tsc -b --noEmit`
+3. **`gitnexus/` files staged** → `tsc --noEmit`
+
+Tests do **not** run in the pre-commit hook — they run in CI (`ci-tests.yml`) only.
 
 Skip with `git commit --no-verify` (use sparingly).
 
@@ -77,7 +80,7 @@ Re-run the full relevant suite when:
 
 GitHub Actions (`.github/workflows/ci.yml`) orchestrate:
 
-- **`ci-quality.yml`** — `tsc --noEmit` for `gitnexus/` + `tsc -b --noEmit` for `gitnexus-web/`
+- **`ci-quality.yml`** — prettier format check, eslint lint, `tsc --noEmit` for `gitnexus/`, `tsc -b --noEmit` for `gitnexus-web/`
 - **`ci-tests.yml`** — `vitest run` with coverage (ubuntu) + cross-platform (macOS, Windows)
 - **`ci-e2e.yml`** — Playwright E2E tests, gated on `gitnexus-web/**` changes
 
diff --git a/deploy/kubernetes/cluster-image-policy.yaml b/deploy/kubernetes/cluster-image-policy.yaml
new file mode 100644
index 000000000..9287a3c45
--- /dev/null
+++ b/deploy/kubernetes/cluster-image-policy.yaml
@@ -0,0 +1,64 @@
+# Sigstore policy-controller ClusterImagePolicy for GitNexus container images.
+#
+# This enforces — at admission time — that every Pod pulling a
+# `ghcr.io/abhigyanpatwari/gitnexus` or `gitnexus-web` image is using a build
+# that was Cosign-keyless-signed by this repository's `docker.yml` workflow
+# running from a `vX.Y.Z` git tag. Unsigned images, images signed by other
+# workflows, and images signed from unprotected refs (e.g. `main`, PR branches)
+# are rejected.
+#
+# Prerequisites
+# -------------
+# 1. Install the Sigstore policy-controller in your cluster (Helm):
+#
+#      helm repo add sigstore https://sigstore.github.io/helm-charts
+#      helm repo update
+#      helm install policy-controller -n cosign-system --create-namespace \
+#        sigstore/policy-controller
+#
+# 2. Opt namespaces in to verification:
+#
+#      kubectl label namespace <your-ns> policy.sigstore.dev/include=true
+#
+# 3. Apply this policy:
+#
+#      kubectl apply -f deploy/kubernetes/cluster-image-policy.yaml
+#
+# After this, `kubectl run --image=ghcr.io/abhigyanpatwari/gitnexus:<tag>` in
+# any opted-in namespace will only succeed if the image carries a valid
+# Sigstore signature with the pinned identity.
+#
+# References
+# - https://docs.sigstore.dev/policy-controller/overview/
+# - https://github.com/sigstore/policy-controller
+apiVersion: policy.sigstore.dev/v1beta1
+kind: ClusterImagePolicy
+metadata:
+  name: gitnexus-signed-images
+spec:
+  # Apply to both published GitNexus images on GHCR. Image references always
+  # carry a tag or digest at admission time, so these two globs cover every
+  # `gitnexus:<tag>`, `gitnexus@sha256:...`, `gitnexus-web:<tag>`, and
+  # `gitnexus-web@sha256:...` reference.
+  images:
+    - glob: 'ghcr.io/abhigyanpatwari/gitnexus*'
+  authorities:
+    - name: gitnexus-cosign-keyless
+      keyless:
+        # Public-good Sigstore Fulcio root.
+        url: https://fulcio.sigstore.dev
+        identities:
+          # Pin both the OIDC issuer (GitHub Actions) AND the exact workflow
+          # path running from a `vX.Y.Z` (or `vX.Y.Z-prerelease`) tag. Same
+          # regex the README's `cosign verify` example uses; it rejects:
+          #   * unsigned images
+          #   * signatures from any other repo / workflow
+          #   * signatures from non-tag refs (main, PRs, release branches)
+          #   * signatures from arbitrary non-semver tags
+          - issuer: https://token.actions.githubusercontent.com
+            subjectRegExp: ^https://github\.com/abhigyanpatwari/GitNexus/\.github/workflows/docker\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$
+      # Cross-check the signature against the public Rekor transparency log,
+      # so an attacker who briefly compromised Fulcio cannot retroactively
+      # mint a signature without leaving a public, append-only audit record.
+      ctlog:
+        url: https://rekor.sigstore.dev
diff --git a/docker-compose.yaml b/docker-compose.yaml
new file mode 100644
index 000000000..d17f012db
--- /dev/null
+++ b/docker-compose.yaml
@@ -0,0 +1,45 @@
+services:
+  gitnexus-server:
+    image: ${SERVER_IMAGE:-ghcr.io/abhigyanpatwari/gitnexus:latest}
+    container_name: ${SERVER_CONTAINER_NAME:-gitnexus-server}
+    # Map the server to the same host port the web UI expects by default
+    # (http://localhost:4747). The browser runs on the host, so the UI's
+    # built-in default works without any reconfiguration.
+    ports:
+      - '${SERVER_HOST_PORT:-4747}:4747'
+    volumes:
+      # Persist the global registry, indexes, and cloned repos across runs.
+      - gitnexus-data:/data/gitnexus
+      # Optional: mount a host workspace so `gitnexus index <path>` can see
+      # repos you already have on disk. The default points at an empty
+      # `./workspace/` sibling that compose will create on first start —
+      # it intentionally does NOT bind-mount the repo root, which would
+      # expose `.git`, `.env`, and CI secrets to the container.
+      # Override with `WORKSPACE_DIR=/abs/path/to/your/repos`.
+      - ${WORKSPACE_DIR:-./workspace}:/workspace:ro
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'curl', '-fsS', 'http://localhost:4747/api/heartbeat']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 15s
+
+  gitnexus-web:
+    image: ${WEB_IMAGE:-ghcr.io/abhigyanpatwari/gitnexus-web:latest}
+    container_name: ${WEB_CONTAINER_NAME:-gitnexus-web}
+    ports:
+      - '${WEB_HOST_PORT:-4173}:4173'
+    depends_on:
+      gitnexus-server:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'curl', '-f', 'http://localhost:4173/']
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  gitnexus-data:
diff --git a/docker-server.mjs b/docker-server.mjs
new file mode 100644
index 000000000..adf84a07b
--- /dev/null
+++ b/docker-server.mjs
@@ -0,0 +1,81 @@
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, normalize, sep } from 'node:path';
+
+const host = '0.0.0.0';
+const port = Number(process.env.PORT || '4173');
+const root = join(process.cwd(), 'dist');
+
+const contentTypes = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+function resolvePath(urlPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(urlPath);
+  } catch {
+    return null;
+  }
+  if (decoded.includes('\0')) return null;
+  const cleanPath = normalize(decoded.replace(/^\/+/, ''));
+  const candidate = join(root, cleanPath);
+  if (candidate !== root && !candidate.startsWith(root + sep)) return null;
+  return candidate;
+}
+
+const server = createServer(async (req, res) => {
+  const requestPath = req.url?.split('?')[0] || '/';
+  let filePath = resolvePath(requestPath);
+
+  if (!filePath) {
+    res.writeHead(400);
+    res.end('Bad request');
+    return;
+  }
+
+  try {
+    const fileStat = await stat(filePath).catch(() => null);
+    if (fileStat?.isDirectory()) {
+      filePath = join(filePath, 'index.html');
+    } else if (!fileStat?.isFile()) {
+      filePath = join(root, 'index.html');
+    }
+
+    const finalStat = await stat(filePath).catch(() => null);
+    if (!finalStat?.isFile()) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    res.writeHead(200, {
+      'Cache-Control': filePath.includes('/assets/')
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache',
+      'Content-Type': contentTypes[extname(filePath)] || 'application/octet-stream',
+      'Cross-Origin-Opener-Policy': 'same-origin',
+      'Cross-Origin-Embedder-Policy': 'require-corp',
+    });
+    const stream = createReadStream(filePath);
+    stream.on('error', () => res.destroy());
+    stream.pipe(res);
+  } catch (error) {
+    res.writeHead(500);
+    res.end(error instanceof Error ? error.message : 'Internal server error');
+  }
+});
+
+server.listen(port, host, () => {
+  console.log(`gitnexus-web listening on http://${host}:${port}`);
+});
diff --git a/docker-server.test.mjs b/docker-server.test.mjs
new file mode 100644
index 000000000..a1005b0e4
--- /dev/null
+++ b/docker-server.test.mjs
@@ -0,0 +1,107 @@
+import { mkdir, mkdtemp, rm, unlink, writeFile } from 'node:fs/promises';
+import http, { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { after, before, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverScript = join(__dirname, 'docker-server.mjs');
+
+function getFreePort() {
+  return new Promise((resolve) => {
+    const s = createServer();
+    s.listen(0, '127.0.0.1', () => {
+      const { port } = s.address();
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+function rawGet(port, path) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        body += chunk;
+      });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function waitForServer(port, retries = 30) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await rawGet(port, '/');
+      return;
+    } catch {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  throw new Error('Server did not start in time');
+}
+
+let tmpDir, serverPort, child;
+
+before(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gitnexus-docker-test-'));
+  const distDir = join(tmpDir, 'dist');
+  const assetsDir = join(distDir, 'assets');
+  await mkdir(assetsDir, { recursive: true });
+  await writeFile(join(distDir, 'index.html'), '<html><body>spa</body></html>');
+  await writeFile(join(assetsDir, 'app.abc123.js'), 'console.log("app")');
+
+  serverPort = await getFreePort();
+  child = spawn(process.execPath, [serverScript], {
+    cwd: tmpDir,
+    env: { ...process.env, PORT: String(serverPort) },
+    stdio: 'pipe',
+  });
+  child.on('error', (err) => {
+    throw err;
+  });
+
+  await waitForServer(serverPort);
+});
+
+after(async () => {
+  child?.kill();
+  if (tmpDir) await rm(tmpDir, { recursive: true, force: true });
+});
+
+it('serves a valid asset with immutable cache header', async () => {
+  const res = await rawGet(serverPort, '/assets/app.abc123.js');
+  assert.equal(res.status, 200);
+  assert.match(res.headers['cache-control'], /immutable/);
+  assert.equal(res.headers['cross-origin-opener-policy'], 'same-origin');
+  assert.equal(res.headers['cross-origin-embedder-policy'], 'require-corp');
+});
+
+it('serves SPA fallback for unknown routes', async () => {
+  const res = await rawGet(serverPort, '/some/unknown/route');
+  assert.equal(res.status, 200);
+  assert.match(res.body, /spa/);
+  assert.match(res.headers['cache-control'], /no-cache/);
+});
+
+it('rejects path traversal with 400', async () => {
+  const res = await rawGet(serverPort, '/../../../etc/passwd');
+  assert.equal(res.status, 400);
+});
+
+it('rejects percent-encoded null bytes with 400', async () => {
+  const res = await rawGet(serverPort, '/foo%00bar');
+  assert.equal(res.status, 400);
+});
+
+it('returns 404 when dist/index.html is missing', async () => {
+  await unlink(join(tmpDir, 'dist', 'index.html'));
+  const res = await rawGet(serverPort, '/nonexistent-page');
+  assert.equal(res.status, 404);
+});
diff --git a/gitnexus-shared/src/graph/types.ts b/gitnexus-shared/src/graph/types.ts
index 49762d145..d3dc81625 100644
--- a/gitnexus-shared/src/graph/types.ts
+++ b/gitnexus-shared/src/graph/types.ts
@@ -131,4 +131,20 @@ export interface GraphRelationship {
   confidence: number;
   reason: string;
   step?: number;
+  /**
+   * Per-signal evidence trace for edges emitted by the scope-based
+   * resolution pipeline (RFC #909 Ring 2 PKG #925). Populated by
+   * `emit-references.ts` when draining `ReferenceIndex` into the graph
+   * so downstream query / audit tools can inspect *why* a given edge
+   * was emitted with its confidence value.
+   *
+   * Optional and additive — every existing edge emitter ignores this
+   * field, and every existing query continues to work whether or not
+   * an edge carries it.
+   */
+  evidence?: readonly {
+    readonly kind: string;
+    readonly weight: number;
+    readonly note?: string;
+  }[];
 }
diff --git a/gitnexus-shared/src/index.ts b/gitnexus-shared/src/index.ts
index 4024bf070..d4efe8a89 100644
--- a/gitnexus-shared/src/index.ts
+++ b/gitnexus-shared/src/index.ts
@@ -23,3 +23,128 @@ export type { MroStrategy } from './mro-strategy.js';
 
 // Pipeline progress
 export type { PipelinePhase, PipelineProgress } from './pipeline.js';
+
+// ─── Scope-based resolution — RFC #909 (Ring 1 #910) ────────────────────────
+// Data model (RFC §2)
+export type { SymbolDefinition } from './scope-resolution/symbol-definition.js';
+export type {
+  ScopeId,
+  DefId,
+  ScopeKind,
+  Range,
+  Capture,
+  CaptureMatch,
+  BindingRef,
+  ImportEdge,
+  TypeRef,
+  Scope,
+  ResolutionEvidence,
+  Resolution,
+  Reference,
+  ReferenceIndex,
+  LookupParams,
+  RegistryContributor,
+  ParsedImport,
+  ParsedTypeBinding,
+  WorkspaceIndex,
+  Callsite,
+  ScopeLookup,
+} from './scope-resolution/types.js';
+
+// Evidence + tie-break constants (RFC Appendix A, Appendix B)
+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';
+
+// Language classification (RFC §6.1 Ring 3/4 governance)
+export {
+  LanguageClassifications,
+  isProductionLanguage,
+} from './scope-resolution/language-classification.js';
+export type { LanguageClassification } from './scope-resolution/language-classification.js';
+
+// Core indexes over per-file artifacts (RFC §3.1; Ring 2 SHARED #913)
+export { buildDefIndex } from './scope-resolution/def-index.js';
+export type { DefIndex } from './scope-resolution/def-index.js';
+export { buildModuleScopeIndex } from './scope-resolution/module-scope-index.js';
+export type { ModuleScopeIndex, ModuleScopeEntry } from './scope-resolution/module-scope-index.js';
+export { buildQualifiedNameIndex } from './scope-resolution/qualified-name-index.js';
+export type { QualifiedNameIndex } from './scope-resolution/qualified-name-index.js';
+
+// Strict type-reference resolver (RFC §4.6; Ring 2 SHARED #916)
+// `ScopeLookup` is defined in `./scope-resolution/types.js` and exported
+// from the type-export block above — not from this module.
+export { resolveTypeRef } from './scope-resolution/resolve-type-ref.js';
+export type { ResolveTypeRefContext } from './scope-resolution/resolve-type-ref.js';
+
+// ScopeExtractor output contracts (RFC §3.2 Phase 1; Ring 2 PKG #919)
+export type { ParsedFile } from './scope-resolution/parsed-file.js';
+export type { ReferenceSite, ReferenceKind, CallForm } from './scope-resolution/reference-site.js';
+
+// Method-dispatch materialized view over HeritageMap (RFC §3.1; Ring 2 SHARED #914)
+export { buildMethodDispatchIndex } from './scope-resolution/method-dispatch-index.js';
+export type {
+  MethodDispatchIndex,
+  MethodDispatchInput,
+} from './scope-resolution/method-dispatch-index.js';
+
+// SCC-aware cross-file finalize (RFC §3.2 Phase 2; Ring 2 SHARED #915)
+export { finalize } from './scope-resolution/finalize-algorithm.js';
+export type {
+  FinalizeInput,
+  FinalizeFile,
+  FinalizeHooks,
+  FinalizeOutput,
+  FinalizedScc,
+  FinalizeStats,
+} from './scope-resolution/finalize-algorithm.js';
+
+// Scope-aware registries + 7-step lookup (RFC §4; Ring 2 SHARED #917)
+export { buildClassRegistry } from './scope-resolution/registries/class-registry.js';
+export type { ClassRegistry } from './scope-resolution/registries/class-registry.js';
+export { buildMethodRegistry } from './scope-resolution/registries/method-registry.js';
+export type {
+  MethodRegistry,
+  MethodLookupOptions,
+} from './scope-resolution/registries/method-registry.js';
+export { buildFieldRegistry } from './scope-resolution/registries/field-registry.js';
+export type {
+  FieldRegistry,
+  FieldLookupOptions,
+} from './scope-resolution/registries/field-registry.js';
+export { lookupCore } from './scope-resolution/registries/lookup-core.js';
+export type { CoreLookupParams } from './scope-resolution/registries/lookup-core.js';
+export { lookupQualified } from './scope-resolution/registries/lookup-qualified.js';
+export type { LookupQualifiedParams } from './scope-resolution/registries/lookup-qualified.js';
+export { composeEvidence, confidenceFromEvidence } from './scope-resolution/registries/evidence.js';
+export type { RawSignals } from './scope-resolution/registries/evidence.js';
+export {
+  compareByConfidenceWithTiebreaks,
+  CONFIDENCE_EPSILON,
+} from './scope-resolution/registries/tie-breaks.js';
+export type { TieBreakKey } from './scope-resolution/registries/tie-breaks.js';
+export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/registries/context.js';
+export type {
+  RegistryContext,
+  RegistryProviders,
+  OwnerScopedContributor,
+  ArityVerdict,
+} from './scope-resolution/registries/context.js';
+
+// Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)
+export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
+export type { ScopeIdInput } from './scope-resolution/scope-id.js';
+export { buildScopeTree, ScopeTreeInvariantError } from './scope-resolution/scope-tree.js';
+export type { ScopeTree } from './scope-resolution/scope-tree.js';
+export { buildPositionIndex } from './scope-resolution/position-index.js';
+export type { PositionIndex } from './scope-resolution/position-index.js';
+
+// Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
+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';
diff --git a/gitnexus-shared/src/lbug/schema-constants.ts b/gitnexus-shared/src/lbug/schema-constants.ts
index 0eca57286..656ffe552 100644
--- a/gitnexus-shared/src/lbug/schema-constants.ts
+++ b/gitnexus-shared/src/lbug/schema-constants.ts
@@ -30,6 +30,7 @@ export const NODE_TABLES = [
   'TypeAlias',
   'Const',
   'Static',
+  'Variable',
   'Property',
   'Record',
   'Delegate',
diff --git a/gitnexus-shared/src/mro-strategy.ts b/gitnexus-shared/src/mro-strategy.ts
index 6168c67c0..7ace9306f 100644
--- a/gitnexus-shared/src/mro-strategy.ts
+++ b/gitnexus-shared/src/mro-strategy.ts
@@ -1,23 +1,46 @@
 /**
- * MRO (Method Resolution Order) strategy — shared between CLI and any
- * future consumer that reasons about multiple-inheritance semantics.
+ * MRO (Method Resolution Order) strategy — shared canonical definition.
  *
- * Lives in `gitnexus-shared` so the low-level resolution module
- * (`core/ingestion/model/resolve.ts`) does not need to import from
- * `languages/` — keeping the `model/` layer free of language-registry
- * coupling.
+ * Lives in `gitnexus-shared` so `model/resolve.ts` and `mro-processor.ts` share
+ * the type without importing the language registry (avoids circular coupling).
  *
- * Strategy semantics:
- * - `first-wins`:       BFS ancestor walk, first match wins (default).
- * - `leftmost-base`:    BFS ancestor walk, leftmost base wins (C++).
- * - `c3`:               C3-linearized ancestor order, first match wins (Python).
- * - `implements-split`: BFS walk, first match wins (Java/C#/Kotlin) — full
- *                       interface-default ambiguity is handled at graph level.
- * - `qualified-syntax`: No auto-resolution (Rust — requires `<T as Trait>::m`).
+ * `first-wins` (default, Java/C#/Kotlin/Go/Swift/Dart):
+ *   BFS ancestor walk in declaration order; first match wins.
+ *
+ * `leftmost-base` (C++):
+ *   BFS walk; HeritageMap preserves source insertion order, so BFS naturally
+ *   picks the leftmost base in diamond inheritance.
+ *
+ * `c3` (Python):
+ *   C3-linearization; falls back to BFS on cyclic/inconsistent hierarchy.
+ *   See model/resolve.ts § c3Linearize.
+ *
+ * `implements-split` (Java/C#/Kotlin):
+ *   Low-level lookup is BFS; graph-level mro-processor detects and warns on
+ *   interface-default method ambiguity.
+ *
+ * `qualified-syntax` (Rust):
+ *   No auto-resolution — `lookupMethodByOwnerWithMRO` returns undefined immediately.
+ *   Rust requires explicit `<Type as Trait>::method` syntax.
+ *
+ * `ruby-mixin` (Ruby):
+ *   Kind-aware walk that does NOT short-circuit on direct owner first (`prepend`
+ *   must beat the class's own method). Walk order:
+ *     1. Prepend providers (reverse declaration — last-prepended wins)
+ *     2. Direct owner's own methods
+ *     3. Include providers (reverse declaration)
+ *     4. Transitive ancestors (BFS fallback)
+ *   Singleton dispatch: caller passes `ancestryOverride` (extend providers only);
+ *   becomes a simple left-to-right scan. Miss NEVER falls through to file-scoped
+ *   lookup — null-routes or honors `fallback`.
+ *
+ * @see model/resolve.ts § lookupMethodByOwnerWithMRO
+ * @see languages/ruby.ts § selectDispatch
  */
 export type MroStrategy =
   | 'first-wins'
   | 'c3'
   | 'leftmost-base'
   | 'implements-split'
-  | 'qualified-syntax';
+  | 'qualified-syntax'
+  | 'ruby-mixin';
diff --git a/gitnexus-shared/src/scope-resolution/def-index.ts b/gitnexus-shared/src/scope-resolution/def-index.ts
new file mode 100644
index 000000000..a34eab961
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/def-index.ts
@@ -0,0 +1,62 @@
+/**
+ * `DefIndex` — O(1) `DefId → SymbolDefinition` materialization.
+ *
+ * The global "what is this id?" lookup. Every per-kind registry (ClassRegistry,
+ * MethodRegistry, FieldRegistry) returns `DefId[]` and resolves them back to
+ * full `SymbolDefinition` records through this index — one central hash map,
+ * one allocation per def.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #913.
+ *
+ * Consumed by: #917 (`Registry.lookup` implementations), #915 (SCC finalize).
+ */
+
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { DefId } from './types.js';
+
+export interface DefIndex {
+  readonly byId: ReadonlyMap<DefId, SymbolDefinition>;
+  readonly size: number;
+  get(id: DefId): SymbolDefinition | undefined;
+  has(id: DefId): boolean;
+}
+
+/**
+ * Build a `DefIndex` from a flat list of `SymbolDefinition` records.
+ *
+ * **Collision policy: first-write-wins.** `DefId` is meant to be unique
+ * (`nodeId` is the stable graph identifier), so a collision indicates an
+ * upstream bug — most likely the same symbol parsed twice or a duplicate
+ * commit into the pipeline. Rather than silently overwriting with a later
+ * definition that may be partial or wrong, the first record wins and
+ * subsequent records for the same id are dropped. Pipeline bugs surface
+ * later as `has(id) === true` but the def looking older than expected,
+ * which is easier to debug than a silent overwrite.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+export function buildDefIndex(defs: readonly SymbolDefinition[]): DefIndex {
+  const byId = new Map<DefId, SymbolDefinition>();
+  for (const def of defs) {
+    if (byId.has(def.nodeId)) continue; // first-write-wins
+    byId.set(def.nodeId, def);
+  }
+  return wrapIndex(byId);
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+function wrapIndex(byId: Map<DefId, SymbolDefinition>): DefIndex {
+  return {
+    byId,
+    get size() {
+      return byId.size;
+    },
+    get(id: DefId): SymbolDefinition | undefined {
+      return byId.get(id);
+    },
+    has(id: DefId): boolean {
+      return byId.has(id);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/evidence-weights.ts b/gitnexus-shared/src/scope-resolution/evidence-weights.ts
new file mode 100644
index 000000000..d1f46dabb
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/evidence-weights.ts
@@ -0,0 +1,90 @@
+/**
+ * `EvidenceWeights` — RFC Appendix A (authoritative values).
+ *
+ * Starting calibration for scope-based resolution. Shadow-first rollout
+ * tunes these against legacy DAG parity. Every `ResolutionEvidence.weight`
+ * value in the codebase MUST reference this map; inline magic numbers are a
+ * lint violation. Extends issue #429 (centralize hardcoded confidence values).
+ *
+ * Evidence composes additively inside `composeEvidence`; the sum is capped
+ * at 1.0 in `Resolution.confidence`.
+ */
+
+/**
+ * Authoritative weight map. Keys are a mix of `ResolutionEvidence.kind`
+ * values and special modifiers (scope-chain depth, MRO depth decay,
+ * unlinked-import multiplicative cap).
+ */
+export const EvidenceWeights = {
+  // ─── Where-found signals (visibility) ─────────────────────────────────────
+  /** `BindingRef.origin === 'local'` */
+  local: 0.55,
+  /** `BindingRef.origin === 'import'` */
+  import: 0.45,
+  /** `BindingRef.origin === 'reexport'` */
+  reexport: 0.4,
+  /** `BindingRef.origin === 'namespace'` */
+  namespace: 0.4,
+  /** `BindingRef.origin === 'wildcard'` */
+  wildcard: 0.3,
+
+  // ─── Scope-chain deduction (per-hop) ──────────────────────────────────────
+  /** Deducted per parent-hop taken (depth-0 = 0, depth-1 = −0.02, …). */
+  scopeChainPerDepth: -0.02,
+
+  // ─── Receiver-type-binding signal (decays by MRO depth) ───────────────────
+  /**
+   * Weight applied when the receiver's type binding resolves to a class that
+   * declares the candidate as a method/field. Decays by MRO depth: direct
+   * class = index 0; 1 parent hop = index 1; etc. Falls back to the last
+   * value for depths beyond the table.
+   */
+  typeBindingByMroDepth: [0.5, 0.42, 0.36, 0.32, 0.3] as const,
+
+  // ─── Corroborating signals ────────────────────────────────────────────────
+  /** `def.ownerId === resolvedReceiver.def.id` (exact owner match). */
+  ownerMatch: 0.2,
+  /** Explanatory only — retained for debuggability. Never discriminates
+   *  because surviving candidates already passed `acceptedKinds`. */
+  kindMatch: 0.0,
+
+  // ─── Arity compatibility (from `provider.arityCompatibility`) ─────────────
+  /** `provider.arityCompatibility(...) === 'compatible'` */
+  arityMatchCompatible: 0.1,
+  /** `provider.arityCompatibility(...) === 'unknown'` */
+  arityMatchUnknown: 0.0,
+  /** `provider.arityCompatibility(...) === 'incompatible'` — penalizes;
+   *  candidates filtered only when a compatible candidate exists. */
+  arityMatchIncompatible: -0.15,
+
+  // ─── Global fallback (only when nothing lexically visible) ────────────────
+  /** Hit via `QualifiedNameIndex.byQualifiedName`. */
+  globalQualified: 0.35,
+  /** Fallback hit in a `byName` index (and nothing was lexically visible). */
+  globalName: 0.1,
+
+  // ─── Degraded signals ─────────────────────────────────────────────────────
+  /** Call/reference flowing through a `dynamic-unresolved` edge. */
+  dynamicImportUnresolved: 0.02,
+
+  // ─── Unresolved-import cap (multiplicative, applied per-signal) ───────────
+  /**
+   * Multiplicative cap on the edge-derived evidence signal
+   * (`import`/`wildcard`/`reexport`/`namespace`) when
+   * `ImportEdge.linkStatus === 'unresolved'`. Independent corroborating
+   * signals on the same candidate (`owner-match`, `arity-match`,
+   * `type-binding`) are NOT penalized.
+   */
+  unlinkedImportMultiplier: 0.5,
+} as const;
+
+/**
+ * Look up the `type-binding` signal weight for a given MRO depth, falling
+ * back to the last tabulated value for depths beyond the table.
+ */
+export function typeBindingWeightAtDepth(mroDepth: number): number {
+  const table = EvidenceWeights.typeBindingByMroDepth;
+  if (mroDepth < 0) return table[0];
+  if (mroDepth >= table.length) return table[table.length - 1];
+  return table[mroDepth];
+}
diff --git a/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts b/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts
new file mode 100644
index 000000000..6f6de8ba6
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts
@@ -0,0 +1,663 @@
+/**
+ * `finalize` — cross-file finalize algorithm for the SemanticModel
+ * (RFC §3.2 Phase 2; Ring 2 SHARED #915).
+ *
+ * Pure logic that takes per-file parse output (`ParsedImport[]` +
+ * `SymbolDefinition[]`) and returns:
+ *
+ *   - Linked `ImportEdge[]` per module scope, with `targetModuleScope` and
+ *     `targetDefId` filled where resolvable; edges that could not be
+ *     resolved within the hard fixpoint cap are marked
+ *     `linkStatus: 'unresolved'`.
+ *   - Materialized `bindings` per module scope — local defs merged with
+ *     imported / wildcard-expanded / re-exported names via the provider's
+ *     `mergeBindings` precedence.
+ *   - The SCC condensation of the import graph, exposed so disjoint SCCs
+ *     can be processed in parallel by callers that want that.
+ *
+ * The algorithm is **SCC-aware**: it runs Tarjan SCC over the file-level
+ * import graph, processes SCCs in reverse-topological order (leaves
+ * first), and within each SCC runs a bounded fixpoint link pass capped at
+ * `N = |edges in SCC|`. Cyclic imports finalize without hanging; malformed
+ * inputs are bounded by the cap.
+ *
+ * **No language-specific logic.** Target resolution, wildcard expansion,
+ * and binding precedence all go through caller-supplied hooks
+ * (`resolveImportTarget`, `expandsWildcardTo`, `mergeBindings`) that
+ * match the LanguageProvider surface from #911.
+ *
+ * **Dynamic imports rule.** `kind === 'dynamic-unresolved'` passes through
+ * as an `ImportEdge { kind: 'dynamic-unresolved', targetFile: null }`
+ * with no `BindingRef`. They are parse-time signals, not linkable targets.
+ */
+
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { BindingRef, ImportEdge, ParsedImport, ScopeId, WorkspaceIndex } from './types.js';
+
+// ─── Public contracts ───────────────────────────────────────────────────────
+
+/** Per-file input for the finalize pass. */
+export interface FinalizeFile {
+  readonly filePath: string;
+  /** The module scope id for this file; owns the finalized imports + bindings. */
+  readonly moduleScope: ScopeId;
+  readonly parsedImports: readonly ParsedImport[];
+  /**
+   * Defs exported from this file — the "what other files can import by name"
+   * surface. Typically those with `isExported: true` (the module's own
+   * declarations) plus, for multi-hop re-export chains, the re-exported
+   * names the parser chose to surface here.
+   *
+   * **Multi-hop re-export contract.** `finalize` resolves an edge
+   * `A → B (importedName: 'X')` by looking up `X` in `B.localDefs`. If B
+   * only has `export { X } from './C'` and the parser *does not* include
+   * `X` in `B.localDefs`, A's edge hits the fixpoint cap and is marked
+   * `linkStatus: 'unresolved'`. The fixpoint does NOT mutate `localDefs`
+   * across iterations — it is static input.
+   *
+   * Parsers that want multi-hop re-export chains to settle end-to-end must
+   * include re-exported names in the intermediate file's `localDefs` (with
+   * the original `DefId` of the source symbol). This keeps the algorithm
+   * O(1) per lookup and avoids graph-crawl during finalize.
+   */
+  readonly localDefs: readonly SymbolDefinition[];
+}
+
+/** Input to `finalize`. */
+export interface FinalizeInput {
+  readonly files: readonly FinalizeFile[];
+  /** Opaque workspace context forwarded to provider hooks. */
+  readonly workspaceIndex: WorkspaceIndex;
+}
+
+/**
+ * Provider-supplied hooks. Mirror the optional LanguageProvider scope-
+ * resolution hooks declared in #911; `finalize` calls them pure-ly and
+ * expects pure answers.
+ */
+export interface FinalizeHooks {
+  /**
+   * Resolve a raw import target to the concrete file path that owns it.
+   * Return `null` when no target file is resolvable (e.g., `np.foo` when
+   * `numpy` is external to the workspace).
+   */
+  resolveImportTarget(
+    targetRaw: string,
+    fromFile: string,
+    workspaceIndex: WorkspaceIndex,
+  ): string | null;
+
+  /**
+   * For a wildcard `import * from M`, return the names visible in the
+   * exporting module scope `M`. The finalize pass looks each name up in
+   * `M`'s local defs to produce a concrete `BindingRef`; names with no
+   * matching export are dropped.
+   */
+  expandsWildcardTo(targetModuleScope: ScopeId, workspaceIndex: WorkspaceIndex): readonly string[];
+
+  /**
+   * Merge `incoming` bindings into `existing` for a given name. Called
+   * once per name at each scope. Typical rules:
+   *   - Python: local > imported > wildcard (last-write-wins within tier).
+   *   - Rust: explicit `use` > glob; `pub use` overrides.
+   * Return value replaces the bucket entirely — no implicit append.
+   */
+  mergeBindings(
+    existing: readonly BindingRef[],
+    incoming: readonly BindingRef[],
+    scope: ScopeId,
+  ): readonly BindingRef[];
+}
+
+/** One SCC in the file-level import graph. */
+export interface FinalizedScc {
+  readonly files: readonly string[];
+  /** True iff this SCC has ≥ 2 files OR a single file that self-imports. */
+  readonly isCycle: boolean;
+}
+
+/**
+ * Counters reported by `finalize`.
+ *
+ * **Counting granularity** — all edge counters are **per-`ParsedImport`**,
+ * not per-materialized-`ImportEdge`. A single `wildcard` ParsedImport that
+ * expands to N exports counts as one linked edge in these stats; the
+ * materialized output (`FinalizeOutput.imports`) will have N edges for
+ * that input. `dynamic-unresolved` ParsedImports count as linked (they
+ * pass through with no `linkStatus`), so `linkedEdges` ≠ "has a
+ * BindingRef" — use the `bindings` map for that.
+ *
+ * In other words: `totalEdges === input.parsedImports.length` summed
+ * across files, and `linkedEdges + unresolvedEdges === totalEdges`.
+ */
+export interface FinalizeStats {
+  readonly totalFiles: number;
+  /** Total `ParsedImport` records seen across all files. */
+  readonly totalEdges: number;
+  /**
+   * `ParsedImport`s whose finalized edge does NOT carry
+   * `linkStatus: 'unresolved'`. Includes `dynamic-unresolved` pass-throughs.
+   */
+  readonly linkedEdges: number;
+  /** `ParsedImport`s whose finalized edge carries `linkStatus: 'unresolved'`. */
+  readonly unresolvedEdges: number;
+  readonly sccCount: number;
+  readonly largestSccSize: number;
+}
+
+export interface FinalizeOutput {
+  /** Linked `ImportEdge[]` per module scope, in original input order. */
+  readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>;
+  /** Materialized bindings per module scope. */
+  readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+  /** SCCs in reverse-topological order (leaves first). */
+  readonly sccs: readonly FinalizedScc[];
+  readonly stats: FinalizeStats;
+}
+
+// ─── Entry point ───────────────────────────────────────────────────────────
+
+export function finalize(input: FinalizeInput, hooks: FinalizeHooks): FinalizeOutput {
+  const byFilePath = new Map<string, FinalizeFile>();
+  for (const f of input.files) byFilePath.set(f.filePath, f);
+
+  // ── Phase 0: pre-resolve raw import targets (one syscall-equivalent per
+  // (file, parsedImport)). Edges with no resolvable target become
+  // `linkStatus: 'unresolved'` or, for dynamic-unresolved, pass through
+  // with `targetFile: null`.
+  const edgeIndex = new Map<string, ImportEdgeDraft[]>(); // filePath → drafts
+  let totalEdges = 0;
+
+  for (const file of input.files) {
+    const drafts: ImportEdgeDraft[] = [];
+    for (const parsed of file.parsedImports) {
+      const draft = makeEdgeDraft(parsed, file, hooks, input.workspaceIndex);
+      drafts.push(draft);
+      totalEdges++;
+    }
+    edgeIndex.set(file.filePath, drafts);
+  }
+
+  // ── Phase 1: build file-level import graph (only resolvable edges form
+  // graph edges; unresolvable ones are terminal and contribute no
+  // fixpoint obligation).
+  const graph = new Map<string, Set<string>>();
+  for (const file of input.files) {
+    graph.set(file.filePath, new Set());
+  }
+  for (const [fromFile, drafts] of edgeIndex) {
+    const edges = graph.get(fromFile)!;
+    for (const d of drafts) {
+      if (d.targetFile !== null && byFilePath.has(d.targetFile)) {
+        edges.add(d.targetFile);
+      }
+    }
+  }
+
+  // ── Phase 2: Tarjan SCC → reverse-topological list of SCCs.
+  const sccs = tarjanSccs(graph);
+
+  // ── Phase 3: process SCCs in reverse-topological order (leaves first).
+  // Within each SCC, run a bounded fixpoint that resolves intra-SCC edges.
+  // Edges leaving the SCC are already resolved (their target SCC is
+  // already finalized); edges inside the SCC may need multiple passes.
+  const linkedByScope = new Map<ScopeId, readonly ImportEdge[]>();
+  let linkedEdges = 0;
+
+  for (const scc of sccs) {
+    const sccFiles = new Set(scc.files);
+    const capacity = countEdgesWithin(edgeIndex, sccFiles);
+
+    // Run the fixpoint up to `capacity` iterations. Each iteration tries to
+    // resolve every still-unlinked edge in the SCC; stops early if a pass
+    // makes no progress.
+    let progressed = true;
+    let iterations = 0;
+    while (progressed && iterations < capacity) {
+      progressed = false;
+      iterations++;
+      for (const filePath of scc.files) {
+        const drafts = edgeIndex.get(filePath)!;
+        for (const draft of drafts) {
+          if (draft.finalized !== null) continue;
+          const finalized = tryFinalize(draft, byFilePath);
+          if (finalized !== null) {
+            draft.finalized = finalized;
+            progressed = true;
+          }
+        }
+      }
+    }
+
+    // Any drafts still not finalized within this SCC hit the cap → unresolved.
+    for (const filePath of scc.files) {
+      const drafts = edgeIndex.get(filePath)!;
+      for (const draft of drafts) {
+        if (draft.finalized !== null) continue;
+        draft.finalized = {
+          ...draft.base,
+          linkStatus: 'unresolved' as const,
+        };
+      }
+    }
+  }
+
+  // ── Phase 4: collect finalized `ImportEdge[]` per module scope, preserving
+  // input order within each file, and wildcard-expand where applicable.
+  for (const file of input.files) {
+    const drafts = edgeIndex.get(file.filePath)!;
+    const finalized: ImportEdge[] = [];
+    for (const d of drafts) {
+      const edge = d.finalized!;
+      if (d.source.kind === 'wildcard' && edge.linkStatus !== 'unresolved') {
+        // Produce one `wildcard-expanded` ImportEdge per exported name.
+        const expanded = expandWildcard(edge, byFilePath, hooks, input.workspaceIndex);
+        for (const e of expanded) finalized.push(e);
+      } else {
+        finalized.push(edge);
+      }
+      if (edge.linkStatus !== 'unresolved') linkedEdges++;
+    }
+    linkedByScope.set(file.moduleScope, Object.freeze(finalized));
+  }
+
+  // ── Phase 5: materialize module-scope bindings (local + imports + wildcards),
+  // delegating precedence to `provider.mergeBindings`.
+  const bindingsByScope = materializeBindings(input.files, linkedByScope, hooks);
+
+  // ── Stats.
+  const sccCount = sccs.length;
+  let largestSccSize = 0;
+  for (const scc of sccs) {
+    if (scc.files.length > largestSccSize) largestSccSize = scc.files.length;
+  }
+  const stats: FinalizeStats = {
+    totalFiles: input.files.length,
+    totalEdges,
+    linkedEdges,
+    unresolvedEdges: totalEdges - linkedEdges,
+    sccCount,
+    largestSccSize,
+  };
+
+  return Object.freeze({
+    imports: linkedByScope,
+    bindings: bindingsByScope,
+    sccs,
+    stats,
+  });
+}
+
+// ─── Internal: edge drafting (phase 0) ──────────────────────────────────────
+
+interface ImportEdgeDraft {
+  readonly source: ParsedImport;
+  readonly fromFile: string;
+  readonly fromScope: ScopeId;
+  readonly targetFile: string | null;
+  readonly base: ImportEdge;
+  finalized: ImportEdge | null;
+}
+
+function makeEdgeDraft(
+  parsed: ParsedImport,
+  file: FinalizeFile,
+  hooks: FinalizeHooks,
+  workspace: WorkspaceIndex,
+): ImportEdgeDraft {
+  // Dynamic-unresolved passes through — no `BindingRef`, no target file.
+  if (parsed.kind === 'dynamic-unresolved') {
+    const base: ImportEdge = {
+      localName: parsed.localName,
+      targetFile: null,
+      targetExportedName: '',
+      kind: 'dynamic-unresolved',
+    };
+    return {
+      source: parsed,
+      fromFile: file.filePath,
+      fromScope: file.moduleScope,
+      targetFile: null,
+      base,
+      finalized: base, // already fully finalized
+    };
+  }
+
+  const targetFile = hooks.resolveImportTarget(parsed.targetRaw ?? '', file.filePath, workspace);
+
+  // Edge is unresolvable at the file level — mark unresolved now.
+  if (targetFile === null) {
+    const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
+    const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
+    const targetExportedName = extractExportedName(parsed);
+    const base: ImportEdge = {
+      localName,
+      targetFile: null,
+      targetExportedName,
+      kind: edgeKind,
+      linkStatus: 'unresolved',
+    };
+    return {
+      source: parsed,
+      fromFile: file.filePath,
+      fromScope: file.moduleScope,
+      targetFile: null,
+      base,
+      finalized: base,
+    };
+  }
+
+  // Resolvable at the file level; intra-SCC fixpoint may still fail to fill
+  // in `targetDefId` (e.g., symbol not exported from target).
+  const edgeKind = parsed.kind === 'wildcard' ? 'wildcard-expanded' : parsed.kind;
+  const localName = parsed.kind === 'wildcard' ? '' : parsed.localName;
+  const targetExportedName = extractExportedName(parsed);
+  const base: ImportEdge = {
+    localName,
+    targetFile,
+    targetExportedName,
+    kind: edgeKind,
+  };
+  return {
+    source: parsed,
+    fromFile: file.filePath,
+    fromScope: file.moduleScope,
+    targetFile,
+    base,
+    finalized: null,
+  };
+}
+
+function extractExportedName(parsed: ParsedImport): string {
+  switch (parsed.kind) {
+    case 'named':
+    case 'alias':
+    case 'namespace':
+    case 'reexport':
+      return parsed.importedName;
+    case 'wildcard':
+    case 'dynamic-unresolved':
+      return '';
+  }
+}
+
+// ─── Internal: per-edge finalization (phase 3) ─────────────────────────────
+
+function tryFinalize(
+  draft: ImportEdgeDraft,
+  byFilePath: Map<string, FinalizeFile>,
+): ImportEdge | null {
+  const targetFile = draft.targetFile;
+  if (targetFile === null) return draft.base; // already terminal
+
+  const targetModule = byFilePath.get(targetFile);
+  if (targetModule === undefined) return draft.base; // external target — leave as-is
+
+  // Wildcards finalize at the file level; their per-name expansion happens
+  // in phase 4. At this stage we just record the target module scope.
+  if (draft.source.kind === 'wildcard') {
+    return {
+      ...draft.base,
+      targetModuleScope: targetModule.moduleScope,
+    };
+  }
+
+  // Namespace imports alias the target *module*; they don't name a
+  // specific export. Link the module scope unconditionally. If the target
+  // also exposes a def whose simple name matches `importedName` (some
+  // languages emit a synthetic module-def), pick it up as the `targetDefId`
+  // so consumers can reach the module as a symbol — but its absence is not
+  // a failure.
+  if (draft.source.kind === 'namespace') {
+    const moduleDef = findExportByName(targetModule.localDefs, extractExportedName(draft.source));
+    return {
+      ...draft.base,
+      targetModuleScope: targetModule.moduleScope,
+      ...(moduleDef !== undefined ? { targetDefId: moduleDef.nodeId } : {}),
+    };
+  }
+
+  // named / alias / reexport: look up the imported name in the target's
+  // local defs. Multi-hop re-export chains settle iteratively — each hop
+  // resolves once its prior hop is finalized.
+  const importedName = extractExportedName(draft.source);
+  const exported = findExportByName(targetModule.localDefs, importedName);
+
+  if (exported === undefined) {
+    // Target resolvable but the name isn't exported — keep trying in case a
+    // re-export inside the target's SCC surfaces it in a later iteration.
+    return null;
+  }
+
+  const transitiveVia = draft.source.kind === 'reexport' ? Object.freeze([targetFile]) : undefined;
+
+  return {
+    ...draft.base,
+    targetModuleScope: targetModule.moduleScope,
+    targetDefId: exported.nodeId,
+    ...(transitiveVia !== undefined ? { transitiveVia } : {}),
+  };
+}
+
+/**
+ * The "simple" (unqualified) name of a def, for import-name matching.
+ *
+ * Canonical source: `def.qualifiedName` — the tail after the last `.` (or
+ * the whole string if no dot). Defs without a qualifiedName can't be
+ * resolved by name here and return `null`; callers treat that as "name
+ * not exported" and either retry in a later fixpoint iteration or mark
+ * the edge unresolved.
+ */
+function deriveSimpleName(def: SymbolDefinition): string | null {
+  const q = def.qualifiedName;
+  if (q === undefined || q.length === 0) return null;
+  const dot = q.lastIndexOf('.');
+  return dot === -1 ? q : q.slice(dot + 1);
+}
+
+function findExportByName(
+  defs: readonly SymbolDefinition[],
+  name: string,
+): SymbolDefinition | undefined {
+  for (const d of defs) {
+    if (deriveSimpleName(d) === name) return d;
+  }
+  return undefined;
+}
+
+function countEdgesWithin(edgeIndex: Map<string, ImportEdgeDraft[]>, files: Set<string>): number {
+  let n = 0;
+  for (const filePath of files) {
+    const drafts = edgeIndex.get(filePath);
+    if (drafts === undefined) continue;
+    for (const d of drafts) {
+      if (d.targetFile !== null && files.has(d.targetFile)) n++;
+    }
+  }
+  // Guarantee at least one pass even for a trivial SCC (ensures deterministic
+  // fixpoint termination even when a single-file SCC has zero intra-SCC edges
+  // but still needs one settle pass).
+  return Math.max(n, 1);
+}
+
+// ─── Internal: wildcard expansion (phase 4) ────────────────────────────────
+
+function expandWildcard(
+  edge: ImportEdge,
+  byFilePath: Map<string, FinalizeFile>,
+  hooks: FinalizeHooks,
+  workspace: WorkspaceIndex,
+): readonly ImportEdge[] {
+  if (edge.targetModuleScope === undefined || edge.targetFile === null) {
+    return [edge]; // unresolvable wildcard survives as a single unlinked edge
+  }
+  const target = byFilePath.get(edge.targetFile);
+  if (target === undefined) return [edge];
+
+  const names = hooks.expandsWildcardTo(edge.targetModuleScope, workspace);
+  if (names.length === 0) return [];
+
+  const expanded: ImportEdge[] = [];
+  for (const name of names) {
+    const def = findExportByName(target.localDefs, name);
+    if (def === undefined) continue;
+    expanded.push({
+      localName: name,
+      targetFile: edge.targetFile,
+      targetExportedName: name,
+      kind: 'wildcard-expanded',
+      targetModuleScope: edge.targetModuleScope,
+      targetDefId: def.nodeId,
+    });
+  }
+  return expanded;
+}
+
+// ─── Internal: bindings materialization (phase 5) ───────────────────────────
+
+function materializeBindings(
+  files: readonly FinalizeFile[],
+  linkedByScope: ReadonlyMap<ScopeId, readonly ImportEdge[]>,
+  hooks: FinalizeHooks,
+): ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>> {
+  const out = new Map<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>();
+
+  for (const file of files) {
+    const scopeBindings = new Map<string, readonly BindingRef[]>();
+
+    // Start with local defs as `origin: 'local'` bindings.
+    for (const def of file.localDefs) {
+      const name = deriveSimpleName(def);
+      if (name === null) continue;
+      const incoming: BindingRef[] = [{ def, origin: 'local' }];
+      const existing = scopeBindings.get(name) ?? [];
+      scopeBindings.set(name, hooks.mergeBindings(existing, incoming, file.moduleScope));
+    }
+
+    // Layer in finalized imports.
+    const imports = linkedByScope.get(file.moduleScope) ?? [];
+    for (const edge of imports) {
+      if (edge.targetDefId === undefined || edge.linkStatus === 'unresolved') continue;
+      // Every def the importing file needs to reach is in some other file's
+      // `localDefs`; walk all files to find it. In practice we could index
+      // this, but at finalize-time N(files) is small per workspace pass.
+      const def = findDefById(files, edge.targetDefId);
+      if (def === undefined) continue;
+
+      const origin: BindingRef['origin'] =
+        edge.kind === 'namespace'
+          ? 'namespace'
+          : edge.kind === 'wildcard-expanded'
+            ? 'wildcard'
+            : edge.kind === 'reexport'
+              ? 'reexport'
+              : 'import';
+      const fallback = deriveSimpleName(def);
+      const name = edge.localName.length > 0 ? edge.localName : fallback;
+      if (name === null) continue;
+      const incoming: BindingRef[] = [{ def, origin, via: edge }];
+      const existing = scopeBindings.get(name) ?? [];
+      scopeBindings.set(name, hooks.mergeBindings(existing, incoming, file.moduleScope));
+    }
+
+    // Freeze nested buckets for immutability.
+    const frozen = new Map<string, readonly BindingRef[]>();
+    for (const [name, refs] of scopeBindings) {
+      frozen.set(name, Object.freeze(refs.slice()));
+    }
+    out.set(file.moduleScope, frozen);
+  }
+
+  return out;
+}
+
+function findDefById(files: readonly FinalizeFile[], defId: string): SymbolDefinition | undefined {
+  for (const f of files) {
+    for (const d of f.localDefs) {
+      if (d.nodeId === defId) return d;
+    }
+  }
+  return undefined;
+}
+
+// ─── Internal: Tarjan SCC ──────────────────────────────────────────────────
+
+/**
+ * Iterative Tarjan SCC. Returns SCCs in **reverse-topological** order
+ * (leaves first — a property Tarjan gives for free, and the order
+ * `finalize` wants so leaves are fully resolved before their dependents).
+ */
+function tarjanSccs(graph: ReadonlyMap<string, ReadonlySet<string>>): FinalizedScc[] {
+  const index = new Map<string, number>();
+  const lowlink = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const sccs: FinalizedScc[] = [];
+  let idx = 0;
+
+  // Iterative DFS to avoid stack overflow on deep import chains.
+  const allNodes = Array.from(graph.keys()).sort(); // deterministic order
+  const iterStack: Array<{ node: string; children: Iterator<string>; entered: boolean }> = [];
+
+  for (const root of allNodes) {
+    if (index.has(root)) continue;
+    iterStack.push({
+      node: root,
+      children: (graph.get(root) ?? new Set<string>()).values(),
+      entered: false,
+    });
+    while (iterStack.length > 0) {
+      const frame = iterStack[iterStack.length - 1]!;
+
+      if (!frame.entered) {
+        frame.entered = true;
+        index.set(frame.node, idx);
+        lowlink.set(frame.node, idx);
+        idx++;
+        stack.push(frame.node);
+        onStack.add(frame.node);
+      }
+
+      const nextChild = frame.children.next();
+      if (nextChild.done) {
+        // Post-visit: compute SCC membership if frame.node is a root.
+        if (lowlink.get(frame.node) === index.get(frame.node)) {
+          const scc: string[] = [];
+          let selfInCycle = false;
+          while (true) {
+            const w = stack.pop()!;
+            onStack.delete(w);
+            scc.push(w);
+            // A single-file self-loop counts as a cycle.
+            if (w === frame.node) {
+              selfInCycle = (graph.get(w) ?? new Set()).has(w);
+              break;
+            }
+          }
+          const isCycle = scc.length > 1 || selfInCycle;
+          sccs.push({ files: Object.freeze(scc), isCycle });
+        }
+        iterStack.pop();
+        // Propagate lowlink to parent.
+        if (iterStack.length > 0) {
+          const parent = iterStack[iterStack.length - 1]!;
+          lowlink.set(parent.node, Math.min(lowlink.get(parent.node)!, lowlink.get(frame.node)!));
+        }
+        continue;
+      }
+
+      const child = nextChild.value;
+      if (!index.has(child)) {
+        iterStack.push({
+          node: child,
+          children: (graph.get(child) ?? new Set<string>()).values(),
+          entered: false,
+        });
+      } else if (onStack.has(child)) {
+        lowlink.set(frame.node, Math.min(lowlink.get(frame.node)!, index.get(child)!));
+      }
+    }
+  }
+
+  return sccs;
+}
diff --git a/gitnexus-shared/src/scope-resolution/language-classification.ts b/gitnexus-shared/src/scope-resolution/language-classification.ts
new file mode 100644
index 000000000..10c556cda
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/language-classification.ts
@@ -0,0 +1,49 @@
+/**
+ * `LanguageClassification` — RFC §6.1 Ring 3 / Ring 4 governance.
+ *
+ * Classifies each `SupportedLanguages` member for the rollout. Ring 4 (DAG
+ * retirement) is gated on *all production languages* being registry-primary
+ * and stable for one release cycle; `experimental` and `quarantined`
+ * languages do not block.
+ *
+ * Initial classification (locked in Ring 1 #910):
+ *   - production: javascript, typescript, python, java, c, cpp, csharp, go,
+ *                 ruby, rust, php, kotlin, swift, dart
+ *   - experimental: vue (embedded-language / SFC complexity),
+ *                   cobol (regex-provider path)
+ *   - quarantined: (none)
+ */
+
+import { SupportedLanguages } from '../languages.js';
+
+export type LanguageClassification = 'production' | 'experimental' | 'quarantined';
+
+/**
+ * The canonical classification for each supported language. Governance
+ * changes (promote `experimental` → `production`, quarantine a language, …)
+ * update this map in a dedicated PR.
+ */
+export const LanguageClassifications: Readonly<Record<SupportedLanguages, LanguageClassification>> =
+  {
+    [SupportedLanguages.JavaScript]: 'production',
+    [SupportedLanguages.TypeScript]: 'production',
+    [SupportedLanguages.Python]: 'production',
+    [SupportedLanguages.Java]: 'production',
+    [SupportedLanguages.C]: 'production',
+    [SupportedLanguages.CPlusPlus]: 'production',
+    [SupportedLanguages.CSharp]: 'production',
+    [SupportedLanguages.Go]: 'production',
+    [SupportedLanguages.Ruby]: 'production',
+    [SupportedLanguages.Rust]: 'production',
+    [SupportedLanguages.PHP]: 'production',
+    [SupportedLanguages.Kotlin]: 'production',
+    [SupportedLanguages.Swift]: 'production',
+    [SupportedLanguages.Dart]: 'production',
+    [SupportedLanguages.Vue]: 'experimental',
+    [SupportedLanguages.Cobol]: 'experimental',
+  };
+
+/** Convenience predicate: is this language gating Ring 4 retirement? */
+export function isProductionLanguage(lang: SupportedLanguages): boolean {
+  return LanguageClassifications[lang] === 'production';
+}
diff --git a/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts b/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts
new file mode 100644
index 000000000..d09e8fa89
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts
@@ -0,0 +1,145 @@
+/**
+ * `MethodDispatchIndex` — materialized view of class hierarchies keyed by
+ * `DefId` (RFC §3.1; Ring 2 SHARED #914).
+ *
+ * Two O(1)-access maps used by `Registry.lookupMethod` and interface-
+ * dispatch callers:
+ *
+ *   - `mroByOwnerDefId`       : owner class → full MRO ancestor chain
+ *                               (excludes the owner itself, in per-language
+ *                               strategy order).
+ *   - `implsByInterfaceDefId` : interface/trait → classes that implement it.
+ *
+ * **Not an MRO implementation.** The build function is a pure aggregator: it
+ * asks the caller (via `computeMro` and `implementsOf` callbacks) for the
+ * per-language answers and materializes the two-way index. MRO strategies
+ * live where they already do today (`model/resolve.ts § c3Linearize`,
+ * `languages/ruby.ts § selectDispatch`, etc.) — this index does not
+ * reimplement them.
+ *
+ * Why callbacks and not a shared strategy registry: the five strategies
+ * (Python C3, Ruby kind-aware, Java/Kotlin linear, Rust qualified-syntax,
+ * COBOL none) already exist in the CLI package and depend on the CLI's
+ * `HeritageMap` + `SemanticModel`. Pulling them into `gitnexus-shared` would
+ * require migrating both — out of scope for #914. Callbacks let the shared
+ * build stay pure while honoring existing strategies verbatim.
+ *
+ * Consumed by: #917 (`Registry.lookupMethod` MRO fast path, interface
+ * dispatch resolver).
+ */
+
+import type { DefId } from './types.js';
+
+// ─── Public contracts ───────────────────────────────────────────────────────
+
+export interface MethodDispatchIndex {
+  /**
+   * Full MRO ancestor chain per owner class (excludes the owner itself).
+   * Order reflects the per-language strategy used by `computeMro`.
+   */
+  readonly mroByOwnerDefId: ReadonlyMap<DefId, readonly DefId[]>;
+  /** Interfaces / traits → classes that implement them. */
+  readonly implsByInterfaceDefId: ReadonlyMap<DefId, readonly DefId[]>;
+
+  /** `mroByOwnerDefId.get`, with an empty frozen array on miss. */
+  mroFor(ownerDefId: DefId): readonly DefId[];
+  /** `implsByInterfaceDefId.get`, with an empty frozen array on miss. */
+  implementorsOf(interfaceDefId: DefId): readonly DefId[];
+}
+
+export interface MethodDispatchInput {
+  /**
+   * Owner defs to index (classes, structs, traits, interfaces — any kind
+   * that can appear on the owner side of a method-dispatch graph).
+   */
+  readonly owners: readonly DefId[];
+  /**
+   * Return the full MRO ancestor chain for `ownerDefId`, **excluding the
+   * owner itself**, in the order dictated by the owner's language-specific
+   * MRO strategy.
+   *
+   * Contract:
+   *   - Pure (no side effects).
+   *   - Deterministic per input.
+   *   - `undefined` not allowed — return `[]` when the owner has no parents.
+   */
+  readonly computeMro: (ownerDefId: DefId) => readonly DefId[];
+  /**
+   * Return the set of interface/trait defs that `ownerDefId` implements.
+   * Transitive inclusion (e.g., `implements` on a parent class) is the
+   * caller's choice — the build function simply inverts whatever is
+   * returned.
+   *
+   * Repeated IDs in the output are deduplicated automatically.
+   *
+   * **Call-count contract.** `implementsOf` is invoked **once per
+   * occurrence** of an owner in `input.owners`, not once per unique
+   * owner. Duplicate owners therefore re-invoke it; dedup happens at
+   * the bucket layer (after the callback returns). Callers with
+   * expensive `implementsOf` implementations should pass a deduplicated
+   * `owners` list. `computeMro`, by contrast, is memoized by the first-
+   * write-wins policy and fires at most once per unique owner.
+   */
+  readonly implementsOf: (ownerDefId: DefId) => readonly DefId[];
+}
+
+// ─── Builder ────────────────────────────────────────────────────────────────
+
+export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDispatchIndex {
+  const mroByOwnerDefId = new Map<DefId, readonly DefId[]>();
+  const implsBuilding = new Map<DefId, DefId[]>();
+  const implsSeen = new Map<DefId, Set<DefId>>();
+
+  for (const ownerId of input.owners) {
+    // First-write-wins on duplicate owner ids: a stable policy consistent
+    // with sibling indexes (#913 DefIndex / ModuleScopeIndex).
+    if (!mroByOwnerDefId.has(ownerId)) {
+      const chain = input.computeMro(ownerId);
+      mroByOwnerDefId.set(ownerId, Object.freeze(chain.slice()));
+    }
+
+    for (const ifaceId of input.implementsOf(ownerId)) {
+      let seen = implsSeen.get(ifaceId);
+      if (seen === undefined) {
+        seen = new Set<DefId>();
+        implsSeen.set(ifaceId, seen);
+      }
+      if (seen.has(ownerId)) continue;
+      seen.add(ownerId);
+
+      let bucket = implsBuilding.get(ifaceId);
+      if (bucket === undefined) {
+        bucket = [];
+        implsBuilding.set(ifaceId, bucket);
+      }
+      bucket.push(ownerId);
+    }
+  }
+
+  const implsByInterfaceDefId = new Map<DefId, readonly DefId[]>();
+  for (const [ifaceId, owners] of implsBuilding) {
+    implsByInterfaceDefId.set(ifaceId, Object.freeze(owners.slice()));
+  }
+
+  return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId);
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+const EMPTY: readonly DefId[] = Object.freeze([]);
+
+function wrapIndex(
+  mroByOwnerDefId: Map<DefId, readonly DefId[]>,
+  implsByInterfaceDefId: Map<DefId, readonly DefId[]>,
+): MethodDispatchIndex {
+  return {
+    mroByOwnerDefId,
+    implsByInterfaceDefId,
+    mroFor(ownerDefId: DefId): readonly DefId[] {
+      return mroByOwnerDefId.get(ownerDefId) ?? EMPTY;
+    },
+    implementorsOf(interfaceDefId: DefId): readonly DefId[] {
+      return implsByInterfaceDefId.get(interfaceDefId) ?? EMPTY;
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/module-scope-index.ts b/gitnexus-shared/src/scope-resolution/module-scope-index.ts
new file mode 100644
index 000000000..a57c02d27
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/module-scope-index.ts
@@ -0,0 +1,73 @@
+/**
+ * `ModuleScopeIndex` — O(1) `filePath → moduleScopeId` lookup.
+ *
+ * Every file parsed produces exactly one `Module` scope at its root. The
+ * finalize algorithm needs to resolve `ImportEdge.targetFile` to a concrete
+ * module scope id in constant time during the link pass; this index is that
+ * mapping.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #913.
+ *
+ * Consumed by: #915 (SCC finalize link pass), #923 (shadow harness when
+ * resolving callsite file → enclosing module).
+ */
+
+import type { ScopeId } from './types.js';
+
+export interface ModuleScopeIndex {
+  readonly byFilePath: ReadonlyMap<string, ScopeId>;
+  readonly size: number;
+  get(filePath: string): ScopeId | undefined;
+  has(filePath: string): boolean;
+}
+
+export interface ModuleScopeEntry {
+  readonly filePath: string;
+  readonly moduleScopeId: ScopeId;
+}
+
+/**
+ * Build a `ModuleScopeIndex` from a flat list of `{ filePath, moduleScopeId }`
+ * pairs.
+ *
+ * **Collision policy: first-write-wins.** A file should appear exactly once
+ * in a single ingestion run; collisions indicate the same file was parsed
+ * twice or a `filePath` normalization bug upstream. Dropping the later
+ * entry preserves the first-stable id the rest of the pipeline may already
+ * have registered against.
+ *
+ * **Caller contract: filePath keys must be pre-normalized.** This index
+ * keys on the raw `filePath` string and does NOT canonicalize separators,
+ * case, or trailing slashes. Callers upstream of this function must agree
+ * on a canonical form (typically repo-root-relative, POSIX separators,
+ * no trailing slash) before constructing entries — otherwise `C:\foo\bar.ts`,
+ * `C:/foo/bar.ts`, and `foo/bar.ts` will all hash to distinct buckets and
+ * `get()` will miss.
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+export function buildModuleScopeIndex(entries: readonly ModuleScopeEntry[]): ModuleScopeIndex {
+  const byFilePath = new Map<string, ScopeId>();
+  for (const { filePath, moduleScopeId } of entries) {
+    if (byFilePath.has(filePath)) continue; // first-write-wins
+    byFilePath.set(filePath, moduleScopeId);
+  }
+  return wrapIndex(byFilePath);
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+function wrapIndex(byFilePath: Map<string, ScopeId>): ModuleScopeIndex {
+  return {
+    byFilePath,
+    get size() {
+      return byFilePath.size;
+    },
+    get(filePath: string): ScopeId | undefined {
+      return byFilePath.get(filePath);
+    },
+    has(filePath: string): boolean {
+      return byFilePath.has(filePath);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/origin-priority.ts b/gitnexus-shared/src/scope-resolution/origin-priority.ts
new file mode 100644
index 000000000..c5068c274
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/origin-priority.ts
@@ -0,0 +1,30 @@
+/**
+ * `ORIGIN_PRIORITY` — RFC Appendix B (authoritative values).
+ *
+ * Tie-break ordering applied inside `Registry.lookup` Step 7 when
+ * `|Δconfidence| < 0.001` between two `Resolution` candidates. Lower number
+ * = stronger (wins the tie).
+ *
+ * Full tie-break order (§4.2 Step 7):
+ *   confidence DESC → scope depth ASC → MRO depth ASC → ORIGIN_PRIORITY ASC
+ *   → DefId.localeCompare
+ */
+
+export type OriginForTieBreak =
+  | 'local'
+  | 'import'
+  | 'reexport'
+  | 'namespace'
+  | 'wildcard'
+  | 'global-qualified'
+  | 'global-name';
+
+export const ORIGIN_PRIORITY: Readonly<Record<OriginForTieBreak, number>> = {
+  local: 0,
+  import: 1,
+  reexport: 2,
+  namespace: 3,
+  wildcard: 4,
+  'global-qualified': 5,
+  'global-name': 6,
+};
diff --git a/gitnexus-shared/src/scope-resolution/parsed-file.ts b/gitnexus-shared/src/scope-resolution/parsed-file.ts
new file mode 100644
index 000000000..ddd8afccd
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/parsed-file.ts
@@ -0,0 +1,65 @@
+/**
+ * `ParsedFile` — the per-file artifact produced by `ScopeExtractor`
+ * (RFC §3.2 Phase 1; Ring 2 PKG #919).
+ *
+ * The boundary between Phase 1 (extraction, per-file, parallelizable) and
+ * Phase 2 (finalize, cross-file). One `ParsedFile` is emitted per source
+ * file; the finalize orchestrator (#921) collects them into a workspace-
+ * wide set and feeds them to the shared `finalize` algorithm (#915).
+ *
+ * ## Shape
+ *
+ *   - `scopes`           — every `Scope` created for this file, in tree-
+ *                          topological order (module first, then children).
+ *                          `Scope.bindings` carry **local-only** bindings at
+ *                          this stage; finalize merges imports/wildcards on top.
+ *   - `parsedImports`    — raw `ParsedImport[]` for this file; finalize
+ *                          resolves each to a concrete `ImportEdge`.
+ *   - `localDefs`        — defs structurally declared in this file. A
+ *                          superset of every `Scope.ownedDefs` union.
+ *                          Listed separately so `finalize` can dedup-index
+ *                          without re-walking scopes.
+ *   - `referenceSites`   — pre-resolution usage facts; populated by the
+ *                          resolution phase into `ReferenceIndex`.
+ *
+ * ## What `ParsedFile` deliberately does NOT carry
+ *
+ *   - Linked `ImportEdge`s. Those are finalize output.
+ *   - A `ScopeTree` instance. Callers build one from `scopes` (cheap —
+ *     `buildScopeTree(parsedFile.scopes)`). Keeping the ParsedFile flat
+ *     makes IPC serialization from worker threads straightforward.
+ *   - Merged module-scope bindings. Finalize owns that materialization.
+ *
+ * ## Compatibility with `FinalizeFile`
+ *
+ * `FinalizeFile` (defined in `./finalize-algorithm.ts`) is a structural
+ * subset of `ParsedFile` — `filePath`, `moduleScope`, `parsedImports`,
+ * `localDefs`. A `ParsedFile` is trivially convertible to a `FinalizeFile`
+ * by picking those four fields, so the finalize orchestrator threads
+ * ParsedFile through to the shared algorithm without shape-shifting.
+ */
+
+import type { Scope, ScopeId } from './types.js';
+import type { ParsedImport } from './types.js';
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { ReferenceSite } from './reference-site.js';
+
+export interface ParsedFile {
+  readonly filePath: string;
+  /** `Scope.id` of the file's root `Module` scope. */
+  readonly moduleScope: ScopeId;
+  /**
+   * All scopes in this file, typically emitted in tree-topological order.
+   * Caller reconstructs a `ScopeTree` via `buildScopeTree(scopes)` when
+   * navigation or invariant re-validation is needed.
+   */
+  readonly scopes: readonly Scope[];
+  readonly parsedImports: readonly ParsedImport[];
+  /**
+   * All defs structurally declared in this file (classes, methods, fields,
+   * variables). Mirrors the union of `Scope.ownedDefs` across `scopes`,
+   * pre-flattened for O(N) consumption by finalize.
+   */
+  readonly localDefs: readonly SymbolDefinition[];
+  readonly referenceSites: readonly ReferenceSite[];
+}
diff --git a/gitnexus-shared/src/scope-resolution/position-index.ts b/gitnexus-shared/src/scope-resolution/position-index.ts
new file mode 100644
index 000000000..a2fd80828
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/position-index.ts
@@ -0,0 +1,166 @@
+/**
+ * `PositionIndex` — O(log N_file) scope-at-position lookup
+ * (RFC §3.1; Ring 2 SHARED #912).
+ *
+ * Per-file sorted array of `(range, scopeId)` entries, sorted by start
+ * position ASC (`startLine`, then `startCol`). `atPosition(filePath, line,
+ * col)` binary-searches for the last entry whose start ≤ (line, col), then
+ * scans backward through the sorted prefix and returns the first entry
+ * whose range contains the query position.
+ *
+ * **Why this works.** `ScopeTree`'s invariants (parent strictly contains
+ * child; siblings don't overlap) guarantee that the scopes containing a
+ * given point form an **ancestor chain**. When scanning backward through
+ * entries sorted by start position ASC, the first scope we find that
+ * contains the query is the innermost one — any deeper-starting scope
+ * that also contained the query would appear *later* in the sorted array,
+ * but we're only scanning entries with start ≤ query, so anything later
+ * necessarily starts after the query and can't contain it.
+ *
+ * Expected complexity: `O(log N_file + D)` where `D` is the lexical depth
+ * at the query position (typically ≤ 10). Worst-case degrades to `O(N_file)`
+ * only under pathological inputs (many scopes starting at the same line).
+ *
+ * **Line/column conventions.** Matches `Range` in `types.ts`: lines are
+ * 1-based, columns are 0-based. Ranges are **inclusive on both ends** —
+ * a scope whose `endLine:endCol` equals the query position still contains
+ * it. That matches how tree-sitter captures bodies (closing brace
+ * included) and how closed PR #902's `enclosingFunctions` behaved.
+ */
+
+import type { Range, Scope, ScopeId } from './types.js';
+
+export interface PositionIndex {
+  /** Total scope entries indexed across all files. */
+  readonly size: number;
+  /**
+   * Innermost scope containing `(line, col)` in `filePath`, or `undefined`
+   * when nothing contains it (position before file start, after file end,
+   * or filePath not indexed).
+   *
+   * **Touching-boundary semantics.** Ranges are inclusive on both ends.
+   * When two sibling scopes share a boundary point — e.g.
+   * `[5:0, 10:0]` and `[10:0, 15:0]`, which is legal under `ScopeTree`'s
+   * non-overlap invariant — a query at the shared point `(10, 0)` is
+   * contained by **both**. The innermost-wins tie-break rule applies as
+   * usual: since neither is nested inside the other, the one that
+   * **starts latest** wins, i.e. the **right** sibling. The mechanism
+   * is the backward scan through the start-position-sorted array (see
+   * `findLastStartLteIndex` below) — both siblings land before the
+   * upper-bound cursor, and the right sibling is scanned first. Queries at non-boundary positions between them naturally
+   * fall to the unique containing scope.
+   */
+  atPosition(filePath: string, line: number, col: number): ScopeId | undefined;
+}
+
+/**
+ * Build a `PositionIndex` from a flat list of `Scope` records.
+ *
+ * Duplicate `id`s are tolerated and deduplicated — the caller's
+ * `ScopeTree.buildScopeTree` is the authoritative validator of scope
+ * identity, and the position index does not need to re-check that
+ * invariant.
+ */
+export function buildPositionIndex(scopes: readonly Scope[]): PositionIndex {
+  const entriesByFile = new Map<string, Entry[]>();
+  const seen = new Set<ScopeId>();
+
+  for (const scope of scopes) {
+    if (seen.has(scope.id)) continue;
+    seen.add(scope.id);
+
+    let bucket = entriesByFile.get(scope.filePath);
+    if (bucket === undefined) {
+      bucket = [];
+      entriesByFile.set(scope.filePath, bucket);
+    }
+    bucket.push({ id: scope.id, range: scope.range });
+  }
+
+  for (const bucket of entriesByFile.values()) {
+    bucket.sort(compareEntry);
+  }
+
+  return wrapIndex(entriesByFile, seen.size);
+}
+
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+interface Entry {
+  readonly id: ScopeId;
+  readonly range: Range;
+}
+
+/**
+ * Sort by start position ASC, breaking ties by end position DESC so that
+ * larger (outer) scopes appear before their smaller (inner) co-starting
+ * siblings in the array. Makes the backward-scan contract crisp: the
+ * first containing hit from the end of the scanned prefix is the
+ * innermost scope.
+ */
+function compareEntry(a: Entry, b: Entry): number {
+  if (a.range.startLine !== b.range.startLine) return a.range.startLine - b.range.startLine;
+  if (a.range.startCol !== b.range.startCol) return a.range.startCol - b.range.startCol;
+  if (a.range.endLine !== b.range.endLine) return b.range.endLine - a.range.endLine;
+  return b.range.endCol - a.range.endCol;
+}
+
+/** Whether `(line, col)` is at or after `range`'s start. */
+function startIsAtOrBefore(range: Range, line: number, col: number): boolean {
+  if (range.startLine < line) return true;
+  if (range.startLine > line) return false;
+  return range.startCol <= col;
+}
+
+/** Whether `(line, col)` is at or before `range`'s end (inclusive). */
+function endIsAtOrAfter(range: Range, line: number, col: number): boolean {
+  if (range.endLine > line) return true;
+  if (range.endLine < line) return false;
+  return range.endCol >= col;
+}
+
+/**
+ * Return the largest index `i` in `arr` where `arr[i].range` starts at or
+ * before `(line, col)`. Returns `-1` if no entry starts ≤ the query.
+ *
+ * Classic "upper bound - 1" binary search: find the first entry that
+ * starts *after* the query, then step back one.
+ */
+function findLastStartLteIndex(arr: readonly Entry[], line: number, col: number): number {
+  let lo = 0;
+  let hi = arr.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (startIsAtOrBefore(arr[mid]!.range, line, col)) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+  return lo - 1;
+}
+
+function wrapIndex(entriesByFile: Map<string, Entry[]>, size: number): PositionIndex {
+  return {
+    get size() {
+      return size;
+    },
+    atPosition(filePath: string, line: number, col: number): ScopeId | undefined {
+      const bucket = entriesByFile.get(filePath);
+      if (bucket === undefined || bucket.length === 0) return undefined;
+
+      const endIdx = findLastStartLteIndex(bucket, line, col);
+      if (endIdx < 0) return undefined;
+
+      // Scan backward; first containing hit is innermost (see file header).
+      for (let i = endIdx; i >= 0; i--) {
+        const entry = bucket[i]!;
+        if (endIsAtOrAfter(entry.range, line, col)) {
+          // `startIsAtOrBefore` is guaranteed true by the binary search.
+          return entry.id;
+        }
+      }
+      return undefined;
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/qualified-name-index.ts b/gitnexus-shared/src/scope-resolution/qualified-name-index.ts
new file mode 100644
index 000000000..e231b01d5
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/qualified-name-index.ts
@@ -0,0 +1,92 @@
+/**
+ * `QualifiedNameIndex` — O(1) `qualifiedName → DefId[]` lookup across all kinds.
+ *
+ * Cross-kind fast path for qualified-name resolution
+ * (`lookupQualified(qname, scope, params)` in RFC §4.5). Class, method,
+ * field, and namespace defs all contribute to a single index here; consumers
+ * filter the returned `DefId[]` by `p.acceptedKinds` at the call site.
+ *
+ * Returns `DefId[]` (not a single `DefId`) because multiple defs can legally
+ * share a qualified name — partial classes in C#, method overloads, or
+ * accidental cross-kind collisions. The lookup caller filters to the expected
+ * kind(s) and ranks the survivors.
+ *
+ * Part of RFC #909 Ring 2 SHARED — #913.
+ *
+ * Consumed by: #917 (`Registry.lookup` qualified fast path, `resolveTypeRef`
+ * dotted fallback via #916).
+ */
+
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { DefId } from './types.js';
+
+export interface QualifiedNameIndex {
+  readonly byQualifiedName: ReadonlyMap<string, readonly DefId[]>;
+  readonly size: number;
+  /** Returns all `DefId`s registered under this qualified name; empty frozen
+   *  array on miss so callers can iterate without null checks. */
+  get(qualifiedName: string): readonly DefId[];
+  has(qualifiedName: string): boolean;
+}
+
+/**
+ * Build a `QualifiedNameIndex` from a flat list of `SymbolDefinition` records.
+ *
+ * Only defs with a non-empty `qualifiedName` contribute; defs without one are
+ * silently skipped (not every kind carries a qualified name — anonymous or
+ * top-level symbols, dynamic-unresolved imports, etc.).
+ *
+ * **Duplicate policy: appended in input order.** Each unique `(qname, DefId)`
+ * pair contributes at most once — repeated entries for the same pair are
+ * deduplicated. Distinct `DefId`s sharing a `qname` accumulate in insertion
+ * order (stable output for deterministic lookup ranking at the call site).
+ *
+ * Pure function — safe to call repeatedly; no side effects.
+ */
+export function buildQualifiedNameIndex(defs: readonly SymbolDefinition[]): QualifiedNameIndex {
+  const byQualifiedName = new Map<string, DefId[]>();
+  const seenPairs = new Set<string>();
+
+  for (const def of defs) {
+    const qname = def.qualifiedName;
+    if (qname === undefined || qname.length === 0) continue;
+
+    const pairKey = `${qname}\0${def.nodeId}`;
+    if (seenPairs.has(pairKey)) continue;
+    seenPairs.add(pairKey);
+
+    const bucket = byQualifiedName.get(qname);
+    if (bucket === undefined) {
+      byQualifiedName.set(qname, [def.nodeId]);
+    } else {
+      bucket.push(def.nodeId);
+    }
+  }
+
+  // Freeze bucket arrays so consumers can't mutate the index.
+  const frozen = new Map<string, readonly DefId[]>();
+  for (const [k, v] of byQualifiedName) {
+    frozen.set(k, Object.freeze(v.slice()));
+  }
+
+  return wrapIndex(frozen);
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+const EMPTY: readonly DefId[] = Object.freeze([]);
+
+function wrapIndex(byQualifiedName: Map<string, readonly DefId[]>): QualifiedNameIndex {
+  return {
+    byQualifiedName,
+    get size() {
+      return byQualifiedName.size;
+    },
+    get(qualifiedName: string): readonly DefId[] {
+      return byQualifiedName.get(qualifiedName) ?? EMPTY;
+    },
+    has(qualifiedName: string): boolean {
+      return byQualifiedName.has(qualifiedName);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/reference-site.ts b/gitnexus-shared/src/scope-resolution/reference-site.ts
new file mode 100644
index 000000000..c9abdef7e
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/reference-site.ts
@@ -0,0 +1,74 @@
+/**
+ * `ReferenceSite` — a pre-resolution usage fact collected by `ScopeExtractor`
+ * (RFC §3.2 Phase 1; Ring 2 PKG #919).
+ *
+ * One record per `@reference.*` capture. The extractor records:
+ *   - the name being referenced (method/field/class name),
+ *   - the source range,
+ *   - the innermost lexical scope containing the reference,
+ *   - the reference kind (call, read, write, inherits, etc.),
+ *   - optional call-form classification from `provider.classifyCallForm`,
+ *   - optional explicit-receiver hint for dotted calls (`user.save()`),
+ *   - optional arity for call sites.
+ *
+ * Reference sites are consumed by the resolution phase (RFC §3.2 Phase 4)
+ * which routes each through `Registry.lookup` / `resolveTypeRef` and
+ * emits the final `Reference` record into `ReferenceIndex`.
+ *
+ * **Pre-resolution only.** `ReferenceSite` intentionally carries no
+ * `toDef`, `confidence`, or `evidence`. Those are populated by the
+ * resolution step that reads this record and produces a `Reference`
+ * (defined in `./types.ts`).
+ */
+
+import type { Range, ScopeId } from './types.js';
+
+/**
+ * What kind of usage this reference represents — the graph-edge kind
+ * emitted after resolution (`CALLS`, `READS`, `WRITES`, etc.).
+ *
+ * Matches the `kind` field on `Reference` in `./types.ts` so the
+ * resolution phase can pass it through without re-classification.
+ */
+export type ReferenceKind =
+  | 'call'
+  | 'read'
+  | 'write'
+  | 'type-reference'
+  | 'inherits'
+  | 'import-use';
+
+/**
+ * How a call site binds its target. Informs `Registry.lookup` Step 2
+ * (type-binding path):
+ *   - `'free'`   — bare call (no receiver); resolution via lexical chain.
+ *   - `'member'` — dotted call (`x.foo()`); resolution via receiver type.
+ *   - `'constructor'` — `new Foo()`; receiver is the class itself.
+ *   - `'index'`  — index expression (`arr[0]`); rare as a dispatch site.
+ *
+ * Only meaningful for `kind === 'call'`; ignored for reads/writes.
+ */
+export type CallForm = 'free' | 'member' | 'constructor' | 'index';
+
+export interface ReferenceSite {
+  /** The name being referenced (e.g., `'save'`, `'User'`, `'count'`). */
+  readonly name: string;
+  /** Source-text range of this reference. */
+  readonly atRange: Range;
+  /**
+   * Innermost lexical scope that contains `atRange`. Resolved by the
+   * extractor via position lookup and frozen here so the resolution
+   * phase doesn't re-compute it per call.
+   */
+  readonly inScope: ScopeId;
+  readonly kind: ReferenceKind;
+  /** Set when `kind === 'call'`. */
+  readonly callForm?: CallForm;
+  /**
+   * Explicit receiver for dotted calls (`user.save()` → `{ name: 'user' }`).
+   * Passed through to `Registry.lookup.explicitReceiver`.
+   */
+  readonly explicitReceiver?: { readonly name: string };
+  /** Argument count at the call site; used by `provider.arityCompatibility`. */
+  readonly arity?: number;
+}
diff --git a/gitnexus-shared/src/scope-resolution/registries/class-registry.ts b/gitnexus-shared/src/scope-resolution/registries/class-registry.ts
new file mode 100644
index 000000000..20a08e2b8
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/class-registry.ts
@@ -0,0 +1,41 @@
+/**
+ * `ClassRegistry` — scope-aware lookup for class-like symbols
+ * (RFC §4.4; Ring 2 SHARED #917).
+ *
+ * Thin wrapper over `lookupCore`, specialized for class kinds:
+ *
+ *   - `acceptedKinds` = Class / Interface / Enum / Struct / Union /
+ *     Trait / TypeAlias / Typedef / Record / Delegate / Annotation /
+ *     Template / Namespace.
+ *   - `useReceiverTypeBinding` is **false** — classes are resolved by
+ *     name through the lexical chain + global qualified fallback, not
+ *     via a receiver type.
+ *   - Arity filter is not applicable (classes are not called with
+ *     argument counts at lookup time).
+ */
+
+import type { Resolution, ScopeId } from '../types.js';
+import { lookupCore, type CoreLookupParams } from './lookup-core.js';
+import { CLASS_KINDS, type RegistryContext } from './context.js';
+
+export interface ClassRegistry {
+  /**
+   * Look up a class-like symbol by simple or dotted name anchored at
+   * `scope`. Returns a confidence-ranked `Resolution[]`; consume `[0]`
+   * for the best answer.
+   */
+  lookup(name: string, scope: ScopeId): readonly Resolution[];
+}
+
+export function buildClassRegistry(ctx: RegistryContext): ClassRegistry {
+  const params: CoreLookupParams = {
+    acceptedKinds: CLASS_KINDS,
+    useReceiverTypeBinding: false,
+    ownerScopedContributor: null,
+  };
+  return {
+    lookup(name: string, scope: ScopeId) {
+      return lookupCore(name, scope, params, ctx);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/registries/context.ts b/gitnexus-shared/src/scope-resolution/registries/context.ts
new file mode 100644
index 000000000..9adbbda2e
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/context.ts
@@ -0,0 +1,110 @@
+/**
+ * `RegistryContext` — the injected state required by the scope-aware
+ * registry lookups (RFC §4; Ring 2 SHARED #917).
+ *
+ * Bundles every Ring 2 index + every provider hook the 7-step algorithm
+ * might consult. Threaded through `lookupCore` and the three public
+ * registries unchanged; construction is the caller's responsibility
+ * (typically once per workspace-indexing pass in Ring 2 PKG).
+ *
+ * The design intent is **pure-logic in `gitnexus-shared`, data + hooks
+ * supplied by the caller**. Nothing here loads files, parses AST, or
+ * reaches into the CLI package.
+ */
+
+import type { NodeLabel } from '../../graph/types.js';
+import type { SymbolDefinition } from '../symbol-definition.js';
+import type { Callsite, DefId } from '../types.js';
+import type { DefIndex } from '../def-index.js';
+import type { QualifiedNameIndex } from '../qualified-name-index.js';
+import type { ModuleScopeIndex } from '../module-scope-index.js';
+import type { ScopeTree } from '../scope-tree.js';
+import type { MethodDispatchIndex } from '../method-dispatch-index.js';
+
+// ─── Provider hooks consumed by the registries ─────────────────────────────
+
+export interface RegistryProviders {
+  /**
+   * Language-specific arity compatibility between a callsite and a candidate
+   * `def`. Mirrors `LanguageProvider.arityCompatibility` from #911. Optional:
+   * when absent, every candidate receives `'unknown'` (neutral signal).
+   */
+  arityCompatibility?(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
+}
+
+export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
+
+// ─── Owner-scoped contributor (concrete shape for `RegistryContributor`) ────
+
+/**
+ * Per-owner membership view plugged into `LookupParams.ownerScopedContributor`.
+ *
+ * When the caller knows a receiver is of type `Owner` (e.g., after
+ * resolving an explicit receiver or via `self`), it can supply the
+ * `Owner`'s own member bucket here. `lookupCore` treats hits from this
+ * contributor as `origin: 'local'` inside the owner's body scope —
+ * strongest-visibility evidence, unaffected by the scope-chain hop
+ * deduction that punishes outer-scope hits.
+ *
+ * Ring 1's `RegistryContributor = unknown` opaque placeholder is narrowed
+ * to this concrete shape here in Ring 2 SHARED (#917).
+ */
+export interface OwnerScopedContributor {
+  /** The owner (class/struct/trait/interface) that bounds this view. */
+  readonly ownerDefId: DefId;
+  /**
+   * Methods / fields directly declared on the owner, keyed by simple name.
+   * Return empty array on miss; implementations should NOT walk the MRO —
+   * that's `MethodDispatchIndex`'s job, handled in the type-binding step.
+   */
+  byName(name: string): readonly SymbolDefinition[];
+}
+
+// ─── Top-level context threaded through every lookup ───────────────────────
+
+export interface RegistryContext {
+  readonly scopes: ScopeTree;
+  readonly defs: DefIndex;
+  readonly qualifiedNames: QualifiedNameIndex;
+  readonly moduleScopes: ModuleScopeIndex;
+  /**
+   * Method-dispatch index; required for method/field registries that
+   * honor `useReceiverTypeBinding`. Omit for class-only lookups.
+   */
+  readonly methodDispatch?: MethodDispatchIndex;
+  readonly providers: RegistryProviders;
+}
+
+// ─── Per-kind default `acceptedKinds` sets ─────────────────────────────────
+//
+// Exported so the three public registries stay declarative (each one just
+// points at the right constant + passes it to `lookupCore`).
+
+export const CLASS_KINDS: readonly NodeLabel[] = Object.freeze([
+  'Class',
+  'Interface',
+  'Enum',
+  'Struct',
+  'Union',
+  'Trait',
+  'TypeAlias',
+  'Typedef',
+  'Record',
+  'Delegate',
+  'Annotation',
+  'Template',
+  'Namespace',
+]);
+
+export const METHOD_KINDS: readonly NodeLabel[] = Object.freeze([
+  'Method',
+  'Function',
+  'Constructor',
+]);
+
+export const FIELD_KINDS: readonly NodeLabel[] = Object.freeze([
+  'Variable',
+  'Property',
+  'Const',
+  'Static',
+]);
diff --git a/gitnexus-shared/src/scope-resolution/registries/evidence.ts b/gitnexus-shared/src/scope-resolution/registries/evidence.ts
new file mode 100644
index 000000000..cabeb6a95
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/evidence.ts
@@ -0,0 +1,196 @@
+/**
+ * `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.
+ */
+
+import type { BindingRef, ResolutionEvidence } from '../types.js';
+import { EvidenceWeights, typeBindingWeightAtDepth } from '../evidence-weights.js';
+
+/**
+ * Raw signals observed for a single candidate during the 7-step walk.
+ * Optional fields encode "this signal did not fire"; presence encodes
+ * "emit an evidence record".
+ */
+export interface RawSignals {
+  // ── Where-found ────────────────────────────────────────────────────────
+  /** Visibility origin of the binding that produced this candidate. */
+  readonly origin?: BindingRef['origin'] | 'global-qualified' | 'global-name';
+  /** Depth at which the binding was found (hops up from start scope). */
+  readonly scopeChainDepth?: number;
+  /** `ImportEdge` that brought the name in; present when origin is a non-local. */
+  readonly viaUnlinkedImport?: boolean;
+
+  // ── Type-binding path ──────────────────────────────────────────────────
+  /** Set when the candidate came via the receiver's type-binding MRO walk. */
+  readonly typeBindingMroDepth?: number;
+
+  // ── Corroborators ──────────────────────────────────────────────────────
+  /** `def.ownerId === resolvedReceiver.def.nodeId`. */
+  readonly ownerMatch?: boolean;
+  /** Always fires for candidates that pass `acceptedKinds`; weight 0. */
+  readonly kindMatch: true;
+
+  // ── Arity ──────────────────────────────────────────────────────────────
+  readonly arityVerdict?: 'compatible' | 'unknown' | 'incompatible';
+
+  // ── Dynamic-unresolved passthrough ─────────────────────────────────────
+  /** Candidate flows through a `kind: 'dynamic-unresolved'` ImportEdge. */
+  readonly dynamicUnresolved?: boolean;
+}
+
+/**
+ * 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 and in the
+ * shadow-mode parity dashboard.
+ */
+export function composeEvidence(signals: RawSignals): readonly ResolutionEvidence[] {
+  const out: ResolutionEvidence[] = [];
+
+  // ── Where-found visibility ─────────────────────────────────────────────
+  if (signals.origin !== undefined) {
+    const baseWeight = getOriginWeight(signals.origin);
+    const capped = signals.viaUnlinkedImport
+      ? baseWeight * EvidenceWeights.unlinkedImportMultiplier
+      : baseWeight;
+    const evidenceKind = whereFoundEvidenceKind(signals.origin);
+    out.push({
+      kind: evidenceKind,
+      weight: capped,
+      ...(signals.viaUnlinkedImport
+        ? { note: `via unresolved import (${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: EvidenceWeights.scopeChainPerDepth * signals.scopeChainDepth,
+      note: `depth=${signals.scopeChainDepth}`,
+    });
+  }
+
+  // ── Type-binding / MRO path ────────────────────────────────────────────
+  if (signals.typeBindingMroDepth !== undefined) {
+    out.push({
+      kind: 'type-binding',
+      weight: typeBindingWeightAtDepth(signals.typeBindingMroDepth),
+      note: `mroDepth=${signals.typeBindingMroDepth}`,
+    });
+  }
+
+  // ── Owner match (explanatory for debug) ────────────────────────────────
+  if (signals.ownerMatch === true) {
+    out.push({
+      kind: 'owner-match',
+      weight: EvidenceWeights.ownerMatch,
+    });
+  }
+
+  // ── Kind match (always present; weight 0; retained for debuggability) ──
+  out.push({
+    kind: 'kind-match',
+    weight: EvidenceWeights.kindMatch,
+  });
+
+  // ── Arity ──────────────────────────────────────────────────────────────
+  if (signals.arityVerdict !== undefined) {
+    const weight =
+      signals.arityVerdict === 'compatible'
+        ? EvidenceWeights.arityMatchCompatible
+        : signals.arityVerdict === 'incompatible'
+          ? EvidenceWeights.arityMatchIncompatible
+          : 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: EvidenceWeights.dynamicImportUnresolved,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Sum evidence weights and clamp to `[0, 1]`. Separate from `composeEvidence`
+ * so tests and the parity dashboard can inspect the raw evidence list.
+ */
+export function confidenceFromEvidence(evidence: readonly ResolutionEvidence[]): number {
+  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: NonNullable<RawSignals['origin']>): number {
+  switch (origin) {
+    case 'local':
+      return EvidenceWeights.local;
+    case 'import':
+      return EvidenceWeights.import;
+    case 'reexport':
+      return EvidenceWeights.reexport;
+    case 'namespace':
+      return EvidenceWeights.namespace;
+    case 'wildcard':
+      return EvidenceWeights.wildcard;
+    case 'global-qualified':
+      return 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 EvidenceWeights.globalName;
+  }
+}
+
+function whereFoundEvidenceKind(
+  origin: NonNullable<RawSignals['origin']>,
+): ResolutionEvidence['kind'] {
+  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';
+  }
+}
diff --git a/gitnexus-shared/src/scope-resolution/registries/field-registry.ts b/gitnexus-shared/src/scope-resolution/registries/field-registry.ts
new file mode 100644
index 000000000..9e6a7aa0f
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/field-registry.ts
@@ -0,0 +1,43 @@
+/**
+ * `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.
+ */
+
+import type { Resolution, ScopeId } from '../types.js';
+import { lookupCore, type CoreLookupParams } from './lookup-core.js';
+import type { OwnerScopedContributor, RegistryContext } from './context.js';
+import { FIELD_KINDS } from './context.js';
+
+export interface FieldLookupOptions {
+  readonly explicitReceiver?: { readonly name: string };
+  readonly ownerScopedContributor?: OwnerScopedContributor;
+}
+
+export interface FieldRegistry {
+  lookup(name: string, scope: ScopeId, options?: FieldLookupOptions): readonly Resolution[];
+}
+
+export function buildFieldRegistry(ctx: RegistryContext): FieldRegistry {
+  return {
+    lookup(name: string, scope: ScopeId, options: FieldLookupOptions = {}) {
+      const params: CoreLookupParams = {
+        acceptedKinds: FIELD_KINDS,
+        useReceiverTypeBinding: true,
+        ownerScopedContributor: options.ownerScopedContributor ?? null,
+        ...(options.explicitReceiver !== undefined
+          ? { explicitReceiver: options.explicitReceiver }
+          : {}),
+      };
+      return lookupCore(name, scope, params, ctx);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts b/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts
new file mode 100644
index 000000000..a18ad4930
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts
@@ -0,0 +1,461 @@
+/**
+ * `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 `RegistryContext.methodDispatch` + owner lookups into
+ *   `scope.ownedDefs`; 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 `gitnexus/` 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.
+ */
+
+import type { NodeLabel } from '../../graph/types.js';
+import type { SymbolDefinition } from '../symbol-definition.js';
+import type {
+  BindingRef,
+  Callsite,
+  DefId,
+  LookupParams,
+  Resolution,
+  Scope,
+  ScopeId,
+} from '../types.js';
+import type { OriginForTieBreak } from '../origin-priority.js';
+import { composeEvidence, confidenceFromEvidence, type RawSignals } from './evidence.js';
+import { compareByConfidenceWithTiebreaks, type TieBreakKey } from './tie-breaks.js';
+import { lookupQualified } from './lookup-qualified.js';
+import type { ArityVerdict, OwnerScopedContributor, RegistryContext } from './context.js';
+
+// ─── Public entry point ─────────────────────────────────────────────────────
+
+/** Extended `LookupParams` narrowing `ownerScopedContributor` to the concrete shape. */
+export interface CoreLookupParams extends Omit<LookupParams, 'ownerScopedContributor'> {
+  readonly ownerScopedContributor: OwnerScopedContributor | null;
+  /** Call-site description forwarded to `arityCompatibility`. Optional — for non-call lookups. */
+  readonly callsite?: Callsite;
+}
+
+/**
+ * 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.
+ */
+export function lookupCore(
+  name: string,
+  startScope: ScopeId,
+  params: CoreLookupParams,
+  ctx: RegistryContext,
+): readonly Resolution[] {
+  const acceptedKinds = new Set<NodeLabel>(params.acceptedKinds);
+  const perCandidate = new Map<DefId, CandidateState>();
+
+  // ── Step 1: lexical scope-chain walk ──────────────────────────────────
+  const lexicalShadowed = 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 = 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);
+}
+
+// ─── Internal state ────────────────────────────────────────────────────────
+
+interface CandidateState {
+  readonly def: SymbolDefinition;
+  readonly signals: MutableRawSignals;
+  readonly tieBreakKey: MutableTieBreakKey;
+}
+
+interface MutableRawSignals {
+  origin?: BindingRef['origin'] | 'global-qualified' | 'global-name';
+  scopeChainDepth?: number;
+  viaUnlinkedImport?: boolean;
+  typeBindingMroDepth?: number;
+  ownerMatch?: boolean;
+  kindMatch: true;
+  arityVerdict?: ArityVerdict;
+  dynamicUnresolved?: boolean;
+}
+
+interface MutableTieBreakKey {
+  scopeDepth: number;
+  mroDepth: number;
+  origin: OriginForTieBreak;
+}
+
+function ensureCandidate(
+  perCandidate: Map<DefId, CandidateState>,
+  def: SymbolDefinition,
+): CandidateState {
+  const existing = perCandidate.get(def.nodeId);
+  if (existing !== undefined) return existing;
+  const fresh: CandidateState = {
+    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: string,
+  startScope: ScopeId,
+  acceptedKinds: ReadonlySet<NodeLabel>,
+  ctx: RegistryContext,
+  perCandidate: Map<DefId, CandidateState>,
+): boolean {
+  let currentId: ScopeId | null = startScope;
+  let depth = 0;
+  const visited = new Set<ScopeId>();
+
+  while (currentId !== null) {
+    if (visited.has(currentId)) return false;
+    visited.add(currentId);
+
+    const scope: Scope | undefined = 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: Map<DefId, CandidateState>,
+  binding: BindingRef,
+  scopeChainDepth: number,
+): void {
+  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 as OriginForTieBreak;
+}
+
+// ─── Step 2 implementation ─────────────────────────────────────────────────
+
+function walkReceiverTypeBinding(
+  name: string,
+  startScope: ScopeId,
+  acceptedKinds: ReadonlySet<NodeLabel>,
+  params: CoreLookupParams,
+  ctx: RegistryContext,
+  perCandidate: Map<DefId, CandidateState>,
+): void {
+  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: DefId[] = [ownerDefId, ...ctx.methodDispatch.mroFor(ownerDefId)];
+
+  for (let mroDepth = 0; mroDepth < walk.length; mroDepth++) {
+    const currentOwnerId = walk[mroDepth]!;
+    const members = collectOwnedMembers(currentOwnerId, name, ctx);
+    for (const def of members) {
+      if (!acceptedKinds.has(def.type)) continue;
+      recordTypeBindingHit(perCandidate, def, mroDepth, ownerDefId);
+    }
+  }
+}
+
+function resolveReceiverOwner(
+  startScope: ScopeId,
+  params: CoreLookupParams,
+  ctx: RegistryContext,
+): DefId | undefined {
+  // 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;
+}
+
+const IMPLICIT_RECEIVERS: readonly string[] = Object.freeze(['self', 'this']);
+
+function lookupReceiverType(
+  startScope: ScopeId,
+  receiverName: string,
+  ctx: RegistryContext,
+): DefId | undefined {
+  let currentId: ScopeId | null = startScope;
+  const visited = new Set<ScopeId>();
+  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;
+    }
+    currentId = scope.parent;
+  }
+  return undefined;
+}
+
+function collectOwnedMembers(
+  ownerDefId: DefId,
+  memberName: string,
+  ctx: RegistryContext,
+): readonly SymbolDefinition[] {
+  // An owner's members are defs whose `ownerId === ownerDefId` and whose
+  // simple name matches `memberName`. We iterate `defs.byId` — O(D) per
+  // call today. A future by-owner index would make this O(K); tracked as
+  // a follow-up optimization before Ring 3 flips go production.
+  const out: SymbolDefinition[] = [];
+  for (const def of ctx.defs.byId.values()) {
+    if (def.ownerId !== ownerDefId) continue;
+    if (simpleNameOf(def) !== memberName) continue;
+    out.push(def);
+  }
+  return out;
+}
+
+function simpleNameOf(def: SymbolDefinition): string | undefined {
+  if (def.qualifiedName === undefined || def.qualifiedName.length === 0) return undefined;
+  const dot = def.qualifiedName.lastIndexOf('.');
+  return dot === -1 ? def.qualifiedName : def.qualifiedName.slice(dot + 1);
+}
+
+function recordTypeBindingHit(
+  perCandidate: Map<DefId, CandidateState>,
+  def: SymbolDefinition,
+  mroDepth: number,
+  receiverOwner: DefId,
+): void {
+  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: string,
+  contributor: OwnerScopedContributor,
+  acceptedKinds: ReadonlySet<NodeLabel>,
+  perCandidate: Map<DefId, CandidateState>,
+): void {
+  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: Callsite,
+  perCandidate: Map<DefId, CandidateState>,
+  ctx: RegistryContext,
+): void {
+  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;
+  for (const state of perCandidate.values()) {
+    const verdict = arityFn(callsite, state.def);
+    state.signals.arityVerdict = verdict;
+    if (verdict === 'compatible') anyCompatible = true;
+  }
+
+  if (!anyCompatible) 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: Map<DefId, CandidateState>): readonly Resolution[] {
+  const resolutions: Resolution[] = [];
+  const tieKeys = new Map<string, TieBreakKey>();
+
+  for (const state of perCandidate.values()) {
+    const evidence = composeEvidence(state.signals as RawSignals);
+    const confidence = confidenceFromEvidence(evidence);
+    resolutions.push({ def: state.def, confidence, evidence });
+    tieKeys.set(state.def.nodeId, { ...state.tieBreakKey });
+  }
+
+  resolutions.sort((a, b) => compareByConfidenceWithTiebreaks(a, b, tieKeys));
+  return Object.freeze(resolutions);
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const EMPTY: readonly Resolution[] = Object.freeze([]);
diff --git a/gitnexus-shared/src/scope-resolution/registries/lookup-qualified.ts b/gitnexus-shared/src/scope-resolution/registries/lookup-qualified.ts
new file mode 100644
index 000000000..21b630486
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/lookup-qualified.ts
@@ -0,0 +1,71 @@
+/**
+ * `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 { composeEvidence, confidenceFromEvidence } from './evidence.js';
+import { compareByConfidenceWithTiebreaks, type TieBreakKey } from './tie-breaks.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 function lookupQualified(
+  qualifiedName: string,
+  params: LookupQualifiedParams,
+  ctx: RegistryContext,
+): readonly Resolution[] {
+  const defIds = ctx.qualifiedNames.get(qualifiedName);
+  if (defIds.length === 0) return EMPTY;
+
+  const acceptedKinds = new Set<NodeLabel>(params.acceptedKinds);
+
+  const resolutions: Resolution[] = [];
+  const tieKeys = new Map<string, TieBreakKey>();
+
+  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: readonly Resolution[] = Object.freeze([]);
diff --git a/gitnexus-shared/src/scope-resolution/registries/method-registry.ts b/gitnexus-shared/src/scope-resolution/registries/method-registry.ts
new file mode 100644
index 000000000..ed206d164
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/method-registry.ts
@@ -0,0 +1,54 @@
+/**
+ * `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 { lookupCore, type CoreLookupParams } from './lookup-core.js';
+import type { OwnerScopedContributor, RegistryContext } from './context.js';
+import { METHOD_KINDS } 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 function buildMethodRegistry(ctx: RegistryContext): MethodRegistry {
+  return {
+    lookup(name: string, scope: ScopeId, options: MethodLookupOptions = {}) {
+      const params: CoreLookupParams = {
+        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);
+    },
+  };
+}
diff --git a/gitnexus-shared/src/scope-resolution/registries/tie-breaks.ts b/gitnexus-shared/src/scope-resolution/registries/tie-breaks.ts
new file mode 100644
index 000000000..9d6f0dee9
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/registries/tie-breaks.ts
@@ -0,0 +1,76 @@
+/**
+ * `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, type OriginForTieBreak } from '../origin-priority.js';
+import type { Resolution } from '../types.js';
+
+export 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 function compareByConfidenceWithTiebreaks(
+  a: Resolution,
+  b: Resolution,
+  keys: ReadonlyMap<string, TieBreakKey>,
+): number {
+  // 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: TieBreakKey = Object.freeze({
+  scopeDepth: 0,
+  mroDepth: 0,
+  origin: 'local',
+});
diff --git a/gitnexus-shared/src/scope-resolution/resolve-type-ref.ts b/gitnexus-shared/src/scope-resolution/resolve-type-ref.ts
new file mode 100644
index 000000000..2f8ba7bd5
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/resolve-type-ref.ts
@@ -0,0 +1,148 @@
+/**
+ * `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 { NodeLabel } from '../graph/types.js';
+import type { SymbolDefinition } from './symbol-definition.js';
+import type { BindingRef, ScopeId, ScopeLookup, TypeRef } from './types.js';
+import type { DefIndex } from './def-index.js';
+import type { QualifiedNameIndex } from './qualified-name-index.js';
+
+// ─── Public contracts ───────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── Strict policy constants ────────────────────────────────────────────────
+
+/** `'wildcard'` is deliberately absent. See file header. */
+const STRICT_ORIGINS: ReadonlySet<BindingRef['origin']> = new Set<BindingRef['origin']>([
+  '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 `gitnexus/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: ReadonlySet<NodeLabel> = new Set<NodeLabel>([
+  'Class',
+  'Interface',
+  'Enum',
+  'Struct',
+  'Union',
+  'Trait',
+  'TypeAlias',
+  'Typedef',
+  'Record',
+  'Delegate',
+  'Annotation',
+  'Template',
+]);
+
+// ─── Main entry point ──────────────────────────────────────────────────────
+
+export function resolveTypeRef(ref: TypeRef, ctx: ResolveTypeRefContext): SymbolDefinition | null {
+  // Phase 1: scope-chain walk anchored at the declaration site.
+  let currentId: ScopeId | null = ref.declaredAtScope;
+  const visited = new Set<ScopeId>();
+
+  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: SymbolDefinition | null = 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;
+}
diff --git a/gitnexus-shared/src/scope-resolution/scope-id.ts b/gitnexus-shared/src/scope-resolution/scope-id.ts
new file mode 100644
index 000000000..b682468cc
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/scope-id.ts
@@ -0,0 +1,57 @@
+/**
+ * `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 function makeScopeId(input: ScopeIdInput): ScopeId {
+  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(): void {
+  INTERN_POOL.clear();
+}
+
+/** Internal: shared intern pool (process-local). */
+const INTERN_POOL = new Map<string, string>();
diff --git a/gitnexus-shared/src/scope-resolution/scope-tree.ts b/gitnexus-shared/src/scope-resolution/scope-tree.ts
new file mode 100644
index 000000000..7f2b54684
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/scope-tree.ts
@@ -0,0 +1,254 @@
+/**
+ * `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, Range } from './types.js';
+
+// ─── Public contract ────────────────────────────────────────────────────────
+
+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;
+}
+
+// ─── Build errors ───────────────────────────────────────────────────────────
+
+/**
+ * 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 class ScopeTreeInvariantError extends Error {
+  constructor(
+    readonly invariant:
+      | 'non-module-requires-parent'
+      | 'parent-not-found'
+      | 'parent-must-contain-child'
+      | 'sibling-ranges-overlap'
+      | 'parent-must-share-filepath'
+      | 'duplicate-scope-id',
+    message: string,
+  ) {
+    super(message);
+    this.name = 'ScopeTreeInvariantError';
+  }
+}
+
+// ─── Builder ───────────────────────────────────────────────────────────────
+
+/**
+ * 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 function buildScopeTree(scopes: readonly Scope[]): ScopeTree {
+  const byId = new Map<ScopeId, Scope>();
+  const childrenById = new Map<ScopeId, ScopeId[]>();
+
+  // ── Pass 1: collect by id + duplicate check ───────────────────────────
+  for (const scope of scopes) {
+    if (byId.has(scope.id)) {
+      throw new ScopeTreeInvariantError(
+        'duplicate-scope-id',
+        `Two scopes share id '${scope.id}'. Scope ids must be unique per tree.`,
+      );
+    }
+    byId.set(scope.id, scope);
+  }
+
+  // ── Pass 2: validate parent pointers + build children buckets ─────────
+  for (const scope of scopes) {
+    if (scope.parent === null) {
+      if (scope.kind !== 'Module') {
+        throw new ScopeTreeInvariantError(
+          'non-module-requires-parent',
+          `Scope '${scope.id}' has kind '${scope.kind}' but no parent. Only 'Module' scopes may be root-level.`,
+        );
+      }
+      continue;
+    }
+
+    const parent = byId.get(scope.parent);
+    if (parent === undefined) {
+      throw new ScopeTreeInvariantError(
+        'parent-not-found',
+        `Scope '${scope.id}' references parent '${scope.parent}' which is not part of this tree.`,
+      );
+    }
+    if (parent.filePath !== scope.filePath) {
+      throw new ScopeTreeInvariantError(
+        'parent-must-share-filepath',
+        `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`,
+      );
+    }
+    if (!rangeStrictlyContains(parent.range, scope.range)) {
+      throw new ScopeTreeInvariantError(
+        'parent-must-contain-child',
+        `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not strictly contain child '${scope.id}' at ${formatRange(scope.range)}.`,
+      );
+    }
+
+    let bucket = childrenById.get(parent.id);
+    if (bucket === undefined) {
+      bucket = [];
+      childrenById.set(parent.id, bucket);
+    }
+    bucket.push(scope.id);
+  }
+
+  // ── Pass 3: sibling-overlap check ─────────────────────────────────────
+  for (const [parentId, childIds] of childrenById) {
+    if (childIds.length < 2) continue;
+    // Sort siblings by (startLine, startCol) for an O(n log n) pairwise
+    // scan instead of O(n²) all-pairs.
+    const children = childIds.map((id) => byId.get(id)!).slice();
+    children.sort((a, b) => comparePosition(a.range, b.range));
+    for (let i = 1; i < children.length; i++) {
+      const prev = children[i - 1]!;
+      const curr = children[i]!;
+      if (rangesOverlap(prev.range, curr.range)) {
+        throw new ScopeTreeInvariantError(
+          'sibling-ranges-overlap',
+          `Sibling scopes under parent '${parentId}' overlap: '${prev.id}' ${formatRange(prev.range)} and '${curr.id}' ${formatRange(curr.range)}.`,
+        );
+      }
+    }
+  }
+
+  // Freeze children arrays so the surface is truly read-only.
+  const frozenChildren = new Map<ScopeId, readonly ScopeId[]>();
+  for (const [parentId, childIds] of childrenById) {
+    frozenChildren.set(parentId, Object.freeze(childIds.slice()));
+  }
+
+  return freezeTree(byId, frozenChildren);
+}
+
+// ─── Internals ──────────────────────────────────────────────────────────────
+
+const EMPTY_CHILDREN: readonly ScopeId[] = Object.freeze([]);
+
+function freezeTree(
+  byId: Map<ScopeId, Scope>,
+  childrenById: Map<ScopeId, readonly ScopeId[]>,
+): ScopeTree {
+  return {
+    byId,
+    get size() {
+      return byId.size;
+    },
+    getScope(id: ScopeId): Scope | undefined {
+      return byId.get(id);
+    },
+    getParent(id: ScopeId): Scope | undefined {
+      const scope = byId.get(id);
+      if (scope === undefined || scope.parent === null) return undefined;
+      return byId.get(scope.parent);
+    },
+    getChildren(id: ScopeId): readonly ScopeId[] {
+      return childrenById.get(id) ?? EMPTY_CHILDREN;
+    },
+    getAncestors(id: ScopeId): readonly ScopeId[] {
+      const start = byId.get(id);
+      if (start === undefined || start.parent === null) return EMPTY_CHILDREN;
+      const out: ScopeId[] = [];
+      const visited = new Set<ScopeId>([id]);
+      let cursor: ScopeId | null = start.parent;
+      while (cursor !== null && !visited.has(cursor)) {
+        visited.add(cursor);
+        out.push(cursor);
+        const next = byId.get(cursor);
+        cursor = next === undefined ? null : next.parent;
+      }
+      return Object.freeze(out);
+    },
+    has(id: ScopeId): boolean {
+      return byId.has(id);
+    },
+  };
+}
+
+/**
+ * `outer` strictly contains `inner` when `outer`'s start is at or before
+ * `inner`'s start, `outer`'s end is at or after `inner`'s end, and they are
+ * not the exact same range. Equal ranges are rejected — a child cannot
+ * occupy the exact same span as its parent.
+ */
+function rangeStrictlyContains(outer: Range, inner: Range): boolean {
+  if (
+    outer.startLine === inner.startLine &&
+    outer.startCol === inner.startCol &&
+    outer.endLine === inner.endLine &&
+    outer.endCol === inner.endCol
+  ) {
+    return false;
+  }
+  const outerStartsAtOrBefore =
+    outer.startLine < inner.startLine ||
+    (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
+  const outerEndsAtOrAfter =
+    outer.endLine > inner.endLine ||
+    (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
+  return outerStartsAtOrBefore && outerEndsAtOrAfter;
+}
+
+/**
+ * Two ranges overlap when neither finishes before the other begins. Ranges
+ * that merely touch at a single boundary point (`a.end === b.start`) do
+ * NOT overlap — this matches tree-sitter's half-open-like range semantics
+ * and the typical "sibling blocks meet but don't overlap" pattern.
+ */
+function rangesOverlap(a: Range, b: Range): boolean {
+  const aEndsBeforeB =
+    a.endLine < b.startLine || (a.endLine === b.startLine && a.endCol <= b.startCol);
+  const bEndsBeforeA =
+    b.endLine < a.startLine || (b.endLine === a.startLine && b.endCol <= a.startCol);
+  return !(aEndsBeforeB || bEndsBeforeA);
+}
+
+function comparePosition(a: Range, b: Range): number {
+  if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+  return a.startCol - b.startCol;
+}
+
+function formatRange(r: Range): string {
+  return `${r.startLine}:${r.startCol}-${r.endLine}:${r.endCol}`;
+}
diff --git a/gitnexus-shared/src/scope-resolution/shadow/aggregate.ts b/gitnexus-shared/src/scope-resolution/shadow/aggregate.ts
new file mode 100644
index 000000000..27c24ff92
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/shadow/aggregate.ts
@@ -0,0 +1,188 @@
+/**
+ * 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.
+ *
+ * Related types — `ShadowAgreement`, `ShadowCallsite`, `ShadowDiff` — are
+ * defined alongside `diffResolutions` in `./diff.ts` and re-exported
+ * through the top-level `gitnexus-shared` barrel. Consumers import all
+ * three from `gitnexus-shared`, not from this module.
+ *
+ * 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';
+
+// ─── Aggregated report shape ────────────────────────────────────────────────
+
+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; // ISO 8601
+  readonly perLanguage: readonly LanguageParityRow[];
+  readonly overall: Omit<LanguageParityRow, 'language' | 'evidenceBreakdown'>;
+}
+
+// ─── 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: readonly { readonly language: SupportedLanguages; readonly diff: ShadowDiff }[],
+  now: Date = new Date(),
+): ShadowParityReport {
+  const perLanguageMap = new Map<SupportedLanguages, MutableCounts>();
+
+  for (const { language, diff } of diffs) {
+    let counts = perLanguageMap.get(language);
+    if (!counts) {
+      counts = makeEmptyCounts();
+      perLanguageMap.set(language, counts);
+    }
+    tallyDiff(counts, diff);
+  }
+
+  const perLanguage: LanguageParityRow[] = 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,
+  };
+}
+
+// ─── Internal helpers ───────────────────────────────────────────────────────
+
+interface MutableCounts {
+  totalCalls: number;
+  bothAgree: number;
+  onlyLegacy: number;
+  onlyNew: number;
+  bothDisagree: number;
+  bothEmpty: number;
+  evidenceBreakdown: Map<ResolutionEvidence['kind'], number>;
+}
+
+function makeEmptyCounts(): MutableCounts {
+  return {
+    totalCalls: 0,
+    bothAgree: 0,
+    onlyLegacy: 0,
+    onlyNew: 0,
+    bothDisagree: 0,
+    bothEmpty: 0,
+    evidenceBreakdown: new Map(),
+  };
+}
+
+function tallyDiff(counts: MutableCounts, diff: ShadowDiff): void {
+  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: MutableCounts, agreement: ShadowAgreement): void {
+  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: SupportedLanguages, counts: MutableCounts): LanguageParityRow {
+  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: readonly LanguageParityRow[],
+): Omit<LanguageParityRow, 'language' | 'evidenceBreakdown'> {
+  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 };
+}
diff --git a/gitnexus-shared/src/scope-resolution/shadow/diff.ts b/gitnexus-shared/src/scope-resolution/shadow/diff.ts
new file mode 100644
index 000000000..a1c8755c6
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/shadow/diff.ts
@@ -0,0 +1,126 @@
+/**
+ * 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';
+
+// ─── Diff record shape ──────────────────────────────────────────────────────
+
+export type ShadowAgreement =
+  | 'both-agree' // top match identical (same DefId)
+  | 'only-legacy' // legacy resolved; new did not
+  | 'only-new' // new resolved; legacy did not
+  | 'both-disagree' // both resolved, but to different targets
+  | 'both-empty'; // both returned 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;
+}
+
+// ─── 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: ShadowCallsite,
+  legacy: readonly Resolution[],
+  newResult: readonly Resolution[],
+): ShadowDiff {
+  const legacyTop: Resolution | null = legacy.length > 0 ? legacy[0] : null;
+  const newTop: Resolution | null = newResult.length > 0 ? newResult[0] : null;
+
+  const agreement: ShadowAgreement = (() => {
+    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: Resolution | null,
+  newResult: Resolution | null,
+  agreement: ShadowAgreement,
+): readonly ResolutionEvidence[] {
+  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];
+}
diff --git a/gitnexus-shared/src/scope-resolution/symbol-definition.ts b/gitnexus-shared/src/scope-resolution/symbol-definition.ts
new file mode 100644
index 000000000..d07dbf38b
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/symbol-definition.ts
@@ -0,0 +1,35 @@
+/**
+ * `SymbolDefinition` — the canonical shape of an indexed symbol record.
+ *
+ * Historically defined in `gitnexus/src/core/ingestion/model/symbol-table.ts`;
+ * moved into `gitnexus-shared` as part of RFC #909 Ring 1 (#910) so the
+ * scope-resolution types that reference it can live in the shared package
+ * alongside their consumers (`gitnexus/` and `gitnexus-web/`).
+ *
+ * Shape is unchanged from the prior local definition.
+ */
+
+import type { NodeLabel } from '../graph/types.js';
+
+export interface SymbolDefinition {
+  nodeId: string;
+  filePath: string;
+  type: NodeLabel;
+  /** Canonical dot-separated qualified type name for class-like symbols
+   *  (e.g. `App.Models.User`). Falls back to the simple symbol name when no
+   *  package/namespace/module scope exists or no explicit qualified metadata is provided. */
+  qualifiedName?: string;
+  parameterCount?: number;
+  /** Number of required (non-optional, non-default) parameters.
+   *  Enables range-based arity filtering: argCount >= requiredParameterCount && argCount <= parameterCount. */
+  requiredParameterCount?: number;
+  /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
+   *  Populated when parameter types are resolvable from AST (any typed language). */
+  parameterTypes?: string[];
+  /** Raw return type text extracted from AST (e.g. 'User', 'Promise<User>') */
+  returnType?: string;
+  /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
+  declaredType?: string;
+  /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
+  ownerId?: string;
+}
diff --git a/gitnexus-shared/src/scope-resolution/types.ts b/gitnexus-shared/src/scope-resolution/types.ts
new file mode 100644
index 000000000..3e1611593
--- /dev/null
+++ b/gitnexus-shared/src/scope-resolution/types.ts
@@ -0,0 +1,432 @@
+/**
+ * Scope-resolution type definitions — RFC §2 data model (authoritative source).
+ *
+ * See: https://www.notion.so/346dc50b6ed281cfaacbe480bf231d50
+ *
+ * Anti-drift rule: every type, interface, and enum defined here is the single
+ * source of truth. Later code that references these names must import them
+ * from `gitnexus-shared`; it must not re-define them locally.
+ *
+ * Lifecycle contract (RFC §2.8): scopes are **constructed during extraction,
+ * linked during finalize, immutable after finalize**. All fields are
+ * `readonly` at the type level; `Object.freeze` is applied at runtime in dev
+ * builds. `ReferenceIndex` is the sole structure populated after freeze — by
+ * resolution, before emission.
+ */
+
+import type { NodeLabel } from '../graph/types.js';
+import type { SymbolDefinition } from './symbol-definition.js';
+
+// ─── §2.1 Type aliases ──────────────────────────────────────────────────────
+
+/** Stable per-(file, range, kind) scope identifier; interned for identity-fast equality. */
+export type ScopeId = string;
+
+/** Stable symbol-definition identifier (graph nodeId). */
+export type DefId = string;
+
+/** Kinds of lexical scope a `Scope` node can represent. */
+export type ScopeKind =
+  | 'Module' // file root
+  | 'Namespace' // C++ namespace, C# namespace, Kotlin package-object, Rust mod
+  | 'Class' // class/struct/trait/interface body
+  | 'Function' // function/method/closure/lambda body
+  | 'Block' // { ... }, if-body, for-body, with-body, match arms
+  | 'Expression'; // comprehensions, for-init, pattern bindings, lambda param lists
+
+// ─── Range + Capture (parser-agnostic) ──────────────────────────────────────
+
+/** Source-text range. 1-based `startLine`/`endLine`; 0-based `startCol`/`endCol`. */
+export interface Range {
+  readonly startLine: number;
+  readonly startCol: number;
+  readonly endLine: number;
+  readonly endCol: number;
+}
+
+/**
+ * Tagged capture emitted by a LanguageProvider's `emitScopeCaptures` hook.
+ *
+ * Parser-agnostic: tree-sitter queries and COBOL's regex tagger both produce
+ * `Capture[]`. The central `ScopeExtractor` consumes captures without
+ * knowing which parser produced them.
+ */
+export interface Capture {
+  /** Capture name, including leading `@` (e.g., `'@scope.module'`, `'@declaration.class'`). */
+  readonly name: string;
+  readonly range: Range;
+  /** 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>>;
+
+// ─── Hook input/output types (RFC §5.2) ─────────────────────────────────────
+
+/**
+ * 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;
+    }
+  /**
+   * Wildcard import — brings every exported name from the target module into
+   * the importing scope. The finalize algorithm expands this into one
+   * `BindingRef` per exported name via the provider's `expandsWildcardTo`
+   * hook, producing the finalize-only `ImportEdge` kind `'wildcard-expanded'`.
+   *
+   * Examples:
+   *   - Python `from foo import *`   → `{ kind: 'wildcard', targetRaw: 'foo' }`
+   *   - JS `export * from './foo'`   → `{ kind: 'wildcard', targetRaw: './foo' }`
+   *   - Rust `pub use foo::*`         → `{ kind: 'wildcard', targetRaw: 'foo' }`
+   */
+  | {
+      readonly kind: 'wildcard';
+      readonly targetRaw: 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;
+
+// `ScopeTree` is exported from `./scope-tree.js` as of Ring 2 SHARED (#912).
+// The former opaque placeholder lived here during Ring 1; removed now that
+// the concrete type exists. Consumers import from `gitnexus-shared` directly.
+
+/**
+ * Minimal scope-lookup contract: map a `ScopeId` back to its `Scope` record.
+ *
+ * Lives in the data-model layer so both `ScopeTree` (§3.1) and
+ * `resolveTypeRef` / `Registry.lookup` (§4) can depend on it without
+ * inverting each other. `ScopeTree` is the canonical implementation;
+ * tests and future alternative containers may supply their own.
+ */
+export interface ScopeLookup {
+  getScope(id: ScopeId): Scope | undefined;
+}
+
+/** Call-site description passed to `arityCompatibility`. */
+export interface Callsite {
+  /** Number of arguments at the call site. */
+  readonly arity: number;
+}
+
+// ─── §2.4 ImportEdge ────────────────────────────────────────────────────────
+
+/**
+ * A cross-file import edge attached to a module/namespace scope.
+ *
+ * Raw (unlinked) edges are emitted during parse (Phase 1); `targetModuleScope`
+ * and `targetDefId` are filled in during finalize (Phase 2) via SCC-aware
+ * bounded-fixpoint linking (RFC §3.2).
+ */
+export interface ImportEdge {
+  /** How this scope sees the imported name (after alias). */
+  readonly localName: string;
+  /** Exporting file; `null` only when `kind === 'dynamic-unresolved'`. */
+  readonly targetFile: string | null;
+  /** The name under which the target exports this symbol. */
+  readonly targetExportedName: string;
+  /** Pre-resolved at finalize: the module scope of the exporting file. */
+  readonly targetModuleScope?: ScopeId;
+  /** Pre-resolved at finalize: the exported symbol's `DefId`. */
+  readonly targetDefId?: DefId;
+  readonly kind:
+    | 'named'
+    | 'alias'
+    | 'namespace'
+    | 'wildcard-expanded'
+    | 'reexport'
+    | 'dynamic-unresolved';
+  /** Re-export chain, for provenance (e.g., `['./y']` when re-exported via `./y`). */
+  readonly transitiveVia?: readonly string[];
+  /** Set to `'unresolved'` when the SCC fixpoint could not link this edge. */
+  readonly linkStatus?: 'unresolved';
+}
+
+// ─── §2.3 BindingRef ────────────────────────────────────────────────────────
+
+/**
+ * A name binding visible at a scope, with provenance.
+ *
+ * Provenance stays at the visibility layer — a name being visible because it
+ * is local vs imported vs wildcard-expanded vs re-exported is a property of
+ * the binding itself. This keeps evidence emission and `import-use` reference
+ * stamping first-class instead of reconstructing provenance from a side table.
+ */
+export interface BindingRef {
+  readonly def: SymbolDefinition;
+  readonly origin: 'local' | 'import' | 'namespace' | 'wildcard' | 'reexport';
+  /** Non-null for non-local origins; carries the `ImportEdge` that brought the name into this scope. */
+  readonly via?: ImportEdge;
+}
+
+// ─── §2.5 TypeRef ───────────────────────────────────────────────────────────
+
+/**
+ * A reference to a named type, anchored at its declaration site.
+ *
+ * Design choice: raw name + declaration-site scope, resolved at lookup time.
+ * Pre-resolution would invert the extraction/resolution wall. Deferred thunks
+ * add no capability. Structured type systems are months of work per language.
+ * This shape keeps V1 tractable while preserving correctness for aliases,
+ * re-exports, and nested modules. Generics deferred to V2 via `typeArgs`.
+ */
+export interface TypeRef {
+  /** The name as written in source (e.g., `'User'`, `'models.User'`, `'List'`). */
+  readonly rawName: string;
+  /** Anchor for resolving `rawName` — the scope where the annotation/inference was written. */
+  readonly declaredAtScope: ScopeId;
+  readonly source:
+    | 'annotation'
+    | 'parameter-annotation'
+    | 'return-annotation'
+    | 'self'
+    | 'assignment-inferred'
+    | 'constructor-inferred'
+    | 'receiver-propagated';
+  /** Reserved for V2+: generic type arguments (`List<User>` → `[TypeRef('User')]`). V1 ignores. */
+  readonly typeArgs?: readonly TypeRef[];
+}
+
+// ─── §2.2 Scope ─────────────────────────────────────────────────────────────
+
+/**
+ * The canonical lexical-scope node. Forms the spine of the SemanticModel.
+ *
+ * ScopeId shape (RFC §2.2): `scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}`
+ * — deterministic, stable across reparses of the same source, interned.
+ */
+export interface Scope {
+  readonly id: ScopeId;
+  readonly parent: ScopeId | null;
+  readonly kind: ScopeKind;
+  readonly range: Range;
+  readonly filePath: string;
+
+  /** Names visible from this scope. Provenance preserved via `BindingRef.origin`. */
+  readonly bindings: ReadonlyMap<string, readonly BindingRef[]>;
+
+  /** Defs structurally owned by this scope (e.g., methods owned by a class body scope). */
+  readonly ownedDefs: readonly SymbolDefinition[];
+
+  /** Import edges attached to this scope. Mostly module/namespace scopes, but some
+   *  languages allow local imports (Python `def f(): from x import Y`, Rust
+   *  fn-local `use`, TS dynamic `import()`). */
+  readonly imports: readonly ImportEdge[];
+
+  /** Local type facts visible from this scope (parameter annotations, `self` binding, etc.). */
+  readonly typeBindings: ReadonlyMap<string, TypeRef>;
+}
+
+// ─── §2.6 Resolution + ResolutionEvidence ───────────────────────────────────
+
+/**
+ * One piece of evidence for a `Resolution`. Multiple signals corroborate a
+ * single match; their weights compose additively to produce `confidence`.
+ *
+ * Weights come from `EvidenceWeights` (see `./evidence-weights.ts`).
+ */
+export interface ResolutionEvidence {
+  readonly kind:
+    | 'local'
+    | 'scope-chain'
+    | 'import'
+    | 'type-binding'
+    | 'owner-match'
+    | 'kind-match'
+    | 'arity-match'
+    | 'global-name'
+    | 'global-qualified'
+    | 'dynamic-import-unresolved';
+  /** Signal weight, sourced from `EvidenceWeights`. Additive; sum capped at 1.0. */
+  readonly weight: number;
+  /** Optional debug annotation (e.g., `'matched via self: User'`). */
+  readonly note?: string;
+}
+
+/**
+ * A ranked resolution candidate returned by `ClassRegistry.lookup` /
+ * `MethodRegistry.lookup` / `FieldRegistry.lookup`. Evidence composes
+ * additively; callers read `[0]` for the one-shot answer or inspect the
+ * evidence trace for debugging.
+ */
+export interface Resolution {
+  readonly def: SymbolDefinition;
+  /** Σ of `evidence[].weight`, capped at 1.0. */
+  readonly confidence: number;
+  readonly evidence: readonly ResolutionEvidence[];
+  /** Optional debug trace: scopes walked to reach `def`. */
+  readonly path?: readonly ScopeId[];
+}
+
+// ─── §2.7 Reference + ReferenceIndex ────────────────────────────────────────
+
+/**
+ * A post-resolution usage fact: some code at `atRange` inside `fromScope`
+ * references `toDef` with the given confidence/evidence. Materialized by the
+ * resolution phase; emitted as graph edges (`CALLS`/`READS`/`WRITES`/etc.)
+ * during the emit phase.
+ */
+export interface Reference {
+  /** Innermost lexical scope containing `atRange`. */
+  readonly fromScope: ScopeId;
+  readonly toDef: DefId;
+  /** Location of the reference in source. */
+  readonly atRange: Range;
+  readonly kind: 'call' | 'read' | 'write' | 'type-reference' | 'inherits' | 'import-use';
+  readonly confidence: number;
+  readonly evidence: readonly ResolutionEvidence[];
+}
+
+/**
+ * Two-way index over `Reference` records, populated during the resolution
+ * phase. Scopes stay immutable after finalize; references accumulate here.
+ */
+export interface ReferenceIndex {
+  readonly bySourceScope: ReadonlyMap<ScopeId, readonly Reference[]>;
+  readonly byTargetDef: ReadonlyMap<DefId, readonly Reference[]>;
+}
+
+// ─── §4.1 LookupParams ──────────────────────────────────────────────────────
+
+/**
+ * Opaque placeholder for the per-kind registry passed as the owner-scoped
+ * contributor. Typed concretely in Ring 2 SHARED (#917); kept as `unknown`
+ * here so Ring 1 can ship without pulling in the registry implementation.
+ */
+export type RegistryContributor = unknown;
+
+/**
+ * Parameters accepted by `Registry.lookup`. Three registries (Class/Method/
+ * Field) run the same 7-step algorithm with different parameter tuples; see
+ * RFC §4.4 for per-registry specializations.
+ */
+export interface LookupParams {
+  readonly acceptedKinds: readonly NodeLabel[];
+  /** Class lookups: false. Method/Field lookups: true. */
+  readonly useReceiverTypeBinding: boolean;
+  readonly ownerScopedContributor: RegistryContributor | null;
+  /** Optional arity hint fed to `provider.arityCompatibility`. */
+  readonly arityHint?: number;
+  /** Explicit receiver name (e.g., `'user'` in `user.save()`). When present,
+   *  the receiver's type binding at the callsite scope is used; otherwise
+   *  the enclosing method's implicit `self`/`this` is consulted. See §4.1. */
+  readonly explicitReceiver?: { readonly name: string };
+}
diff --git a/gitnexus-web/e2e/multi-repo-scoping.spec.ts b/gitnexus-web/e2e/multi-repo-scoping.spec.ts
index 67ee06b08..a60c847d2 100644
--- a/gitnexus-web/e2e/multi-repo-scoping.spec.ts
+++ b/gitnexus-web/e2e/multi-repo-scoping.spec.ts
@@ -61,13 +61,22 @@ test.beforeAll(async () => {
   }
 });
 
+// Auto-connect downloads the full graph from the backend; under parallel
+// workers in CI the same backend serves multiple downloads concurrently, so
+// reaching the "Ready" state can take noticeably longer than a single-worker
+// run. Match the 45s budget used by waitForGraphLoaded() in
+// server-connect.spec.ts which has been stable on the same backend.
+const READY_TIMEOUT_MS = 45_000;
+
 test.describe('Multi-Repo Scoping', () => {
   test('auto-connect via ?server= sets ?project= in URL', async ({ page }) => {
     // Navigate with ?server= param (the bookmarkable shortcut)
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
 
     // Wait for graph to load
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // URL should now contain ?project= with the repo name
     const url = new URL(page.url());
@@ -77,8 +86,14 @@ test.describe('Multi-Repo Scoping', () => {
   });
 
   test('?server= is preserved in URL for F5 recovery', async ({ page }) => {
+    // Two sequential auto-connects (initial + reload), each up to READY_TIMEOUT_MS,
+    // can exceed the default 60s test timeout under parallel workers.
+    test.slow();
+
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // URL should still have ?server=
     const url = new URL(page.url());
@@ -86,12 +101,16 @@ test.describe('Multi-Repo Scoping', () => {
 
     // F5 should reconnect (not show onboarding)
     await page.reload();
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
   });
 
   test('node count in status bar matches backend data', async ({ page }) => {
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // Fetch expected node count from backend
     const res = await fetch(`${BACKEND_URL}/api/repo?repo=${encodeURIComponent(firstRepoName)}`);
diff --git a/gitnexus-web/e2e/onboarding.spec.ts b/gitnexus-web/e2e/onboarding.spec.ts
index da92ffb70..5b70899c6 100644
--- a/gitnexus-web/e2e/onboarding.spec.ts
+++ b/gitnexus-web/e2e/onboarding.spec.ts
@@ -26,7 +26,10 @@ async function enterExploringView(page: import('@playwright/test').Page) {
     // Landing screen may not appear (e.g. ?server auto-connect)
   }
 
-  await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+  // Match the 45s budget used by waitForGraphLoaded() in
+  // server-connect.spec.ts; under parallel CI workers, downloading the full
+  // graph can occasionally exceed 30s.
+  await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 45_000 });
 }
 
 // ── Flow 1: Onboarding (no server running) ─────────────────────────────────
@@ -244,6 +247,10 @@ test.describe('Flow 3: Analyze form', () => {
 test.describe('Flow 4: Repo dropdown in exploring view', () => {
   const SKIP_MSG = 'Requires running gitnexus server with indexed repos';
 
+  // enterExploringView() can take up to ~45s under parallel CI workers; combined
+  // with the dropdown interactions this can exceed the default 60s test budget.
+  test.slow();
+
   test.beforeAll(async () => {
     if (process.env.E2E) return;
     try {
diff --git a/gitnexus-web/e2e/repo-switching.spec.ts b/gitnexus-web/e2e/repo-switching.spec.ts
index 4cf6bf8c8..802f44e78 100644
--- a/gitnexus-web/e2e/repo-switching.spec.ts
+++ b/gitnexus-web/e2e/repo-switching.spec.ts
@@ -84,11 +84,20 @@ test.describe('Hold-queue timeout error', () => {
 
 // ── 2. ?project= URL persistence ─────────────────────────────────────────────
 
+// Auto-connect downloads the full graph from the backend; under parallel
+// workers in CI the same backend serves multiple downloads concurrently, so
+// reaching the "Ready" state can take noticeably longer than a single-worker
+// run. Match the 45s budget used by waitForGraphLoaded() in
+// server-connect.spec.ts which has been stable on the same backend.
+const READY_TIMEOUT_MS = 45_000;
+
 test.describe('?project= URL persistence', () => {
   test('?project= is set in URL after connecting via ?server=', async ({ page }) => {
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
 
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     const url = new URL(page.url());
     const project = url.searchParams.get('project');
@@ -98,12 +107,20 @@ test.describe('?project= URL persistence', () => {
   });
 
   test('?project= is still present after F5 reload', async ({ page }) => {
+    // Two sequential auto-connects (initial + reload), each up to READY_TIMEOUT_MS,
+    // can exceed the default 60s test timeout under parallel workers.
+    test.slow();
+
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // After connect, URL has ?server=&project= — F5 re-uses both params
     await page.reload();
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     const url = new URL(page.url());
     expect(url.searchParams.get('project')).toBeTruthy();
@@ -122,7 +139,9 @@ test.describe('?project= auto-connect', () => {
       `/?server=${encodeURIComponent(BACKEND_URL)}&project=${encodeURIComponent(firstRepoName)}`,
     );
 
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // ?project= in URL should match what we passed in
     const url = new URL(page.url());
@@ -155,7 +174,9 @@ test.describe('Windows path normalization', () => {
 
     await page.goto(`/?server=${encodeURIComponent(BACKEND_URL)}`);
 
-    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({ timeout: 30_000 });
+    await expect(page.locator('[data-testid="status-ready"]')).toBeVisible({
+      timeout: READY_TIMEOUT_MS,
+    });
 
     // URL ?project= must be the short basename, NOT the full Windows path
     const url = new URL(page.url());
diff --git a/gitnexus-web/package-lock.json b/gitnexus-web/package-lock.json
index 2190e27a6..b62d3eddc 100644
--- a/gitnexus-web/package-lock.json
+++ b/gitnexus-web/package-lock.json
@@ -29,7 +29,7 @@
         "langchain": "^1.2.10",
         "lru-cache": "^11.2.4",
         "lucide-react": "^0.562.0",
-        "mermaid": "^11.12.2",
+        "mermaid": "^11.14.0",
         "mnemonist": "^0.39.0",
         "pandemonium": "^2.4.0",
         "react": "^18.3.1",
@@ -39,7 +39,7 @@
         "react-zoom-pan-pinch": "^3.7.0",
         "remark-gfm": "^4.0.1",
         "sigma": "^3.0.2",
-        "tailwindcss": "^4.1.18",
+        "tailwindcss": "^4.2.2",
         "uuid": "^13.0.0",
         "zod": "^3.25.76"
       },
@@ -57,12 +57,12 @@
         "@vercel/node": "^5.5.16",
         "@vitejs/plugin-react": "^5.1.0",
         "@vitest/coverage-v8": "^3.2.4",
-        "jsdom": "^29.0.0",
+        "jsdom": "^29.0.2",
         "tree-sitter-wasms": "^0.1.13",
         "typescript": "^5.4.5",
         "vite": "^5.2.0",
         "vitest": "^3.2.4",
-        "wait-on": "^8.0.5"
+        "wait-on": "^9.0.5"
       },
       "engines": {
         "node": ">=20.0.0"
@@ -129,39 +129,49 @@
       }
     },
     "node_modules/@asamuzakjp/css-color": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.0.1.tgz",
-      "integrity": "sha512-2SZFvqMyvboVV1d15lMf7XiI3m7SDqXUuKaTymJYLN6dSGadqp+fVojqJlVoMlbZnlTmu3S0TLwLTJpvBMO1Aw==",
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+      "integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@csstools/css-calc": "^3.1.1",
-        "@csstools/css-color-parser": "^4.0.2",
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@csstools/css-calc": "^3.2.0",
+        "@csstools/css-color-parser": "^4.1.0",
         "@csstools/css-parser-algorithms": "^4.0.0",
-        "@csstools/css-tokenizer": "^4.0.0",
-        "lru-cache": "^11.2.6"
+        "@csstools/css-tokenizer": "^4.0.0"
       },
       "engines": {
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
       }
     },
     "node_modules/@asamuzakjp/dom-selector": {
-      "version": "7.0.3",
-      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.0.3.tgz",
-      "integrity": "sha512-Q6mU0Z6bfj6YvnX2k9n0JxiIwrCFN59x/nWmYQnAqP000ruX/yV+5bp/GRcF5T8ncvfwJQ7fgfP74DlpKExILA==",
+      "version": "7.0.10",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.0.10.tgz",
+      "integrity": "sha512-KyOb19eytNSELkmdqzZZUXWCU25byIlOld5qVFg0RYdS0T3tt7jeDByxk9hIAC73frclD8GKrHttr0SUjKCCdQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
         "@asamuzakjp/nwsapi": "^2.3.9",
         "bidi-js": "^1.0.3",
         "css-tree": "^3.2.1",
-        "is-potential-custom-element-name": "^1.0.1",
-        "lru-cache": "^11.2.7"
+        "is-potential-custom-element-name": "^1.0.1"
       },
       "engines": {
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
       }
     },
+    "node_modules/@asamuzakjp/generational-cache": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+      "integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/@asamuzakjp/nwsapi": {
       "version": "2.3.9",
       "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
@@ -533,54 +543,40 @@
       "license": "MIT"
     },
     "node_modules/@chevrotain/cst-dts-gen": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-11.0.3.tgz",
-      "integrity": "sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
+      "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/gast": "11.0.3",
-        "@chevrotain/types": "11.0.3",
-        "lodash-es": "4.17.21"
+        "@chevrotain/gast": "12.0.0",
+        "@chevrotain/types": "12.0.0"
       }
     },
-    "node_modules/@chevrotain/cst-dts-gen/node_modules/lodash-es": {
-      "version": "4.17.21",
-      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
-      "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
-      "license": "MIT"
-    },
     "node_modules/@chevrotain/gast": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-11.0.3.tgz",
-      "integrity": "sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
+      "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/types": "11.0.3",
-        "lodash-es": "4.17.21"
+        "@chevrotain/types": "12.0.0"
       }
     },
-    "node_modules/@chevrotain/gast/node_modules/lodash-es": {
-      "version": "4.17.21",
-      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
-      "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
-      "license": "MIT"
-    },
     "node_modules/@chevrotain/regexp-to-ast": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-11.0.3.tgz",
-      "integrity": "sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
+      "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==",
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/types": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.0.3.tgz",
-      "integrity": "sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
+      "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==",
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/utils": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-11.0.3.tgz",
-      "integrity": "sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
+      "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==",
       "license": "Apache-2.0"
     },
     "node_modules/@cspotcode/source-map-support": {
@@ -628,9 +624,9 @@
       }
     },
     "node_modules/@csstools/css-calc": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.1.1.tgz",
-      "integrity": "sha512-HJ26Z/vmsZQqs/o3a6bgKslXGFAungXGbinULZO3eMsOyNJHeBBZfup5FiZInOghgoM4Hwnmw+OgbJCNg1wwUQ==",
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.2.0.tgz",
+      "integrity": "sha512-bR9e6o2BDB12jzN/gIbjHa5wLJ4UjD1CB9pM7ehlc0ddk6EBz+yYS1EV2MF55/HUxrHcB/hehAyt5vhsA3hx7w==",
       "dev": true,
       "funding": [
         {
@@ -652,9 +648,9 @@
       }
     },
     "node_modules/@csstools/css-color-parser": {
-      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.0.2.tgz",
-      "integrity": "sha512-0GEfbBLmTFf0dJlpsNU7zwxRIH0/BGEMuXLTCvFYxuL1tNhqzTbtnFICyJLTNK4a+RechKP75e7w42ClXSnJQw==",
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.1.0.tgz",
+      "integrity": "sha512-U0KhLYmy2GVj6q4T3WaAe6NPuFYCPQoE3b0dRGxejWDgcPp8TP7S5rVdM5ZrFaqu4N67X8YaPBw14dQSYx3IyQ==",
       "dev": true,
       "funding": [
         {
@@ -669,7 +665,7 @@
       "license": "MIT",
       "dependencies": {
         "@csstools/color-helpers": "^6.0.2",
-        "@csstools/css-calc": "^3.1.1"
+        "@csstools/css-calc": "^3.2.0"
       },
       "engines": {
         "node": ">=20.19.0"
@@ -1764,12 +1760,12 @@
       }
     },
     "node_modules/@mermaid-js/parser": {
-      "version": "0.6.3",
-      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-0.6.3.tgz",
-      "integrity": "sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==",
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
+      "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
       "license": "MIT",
       "dependencies": {
-        "langium": "3.3.1"
+        "langium": "^4.0.0"
       }
     },
     "node_modules/@napi-rs/wasm-runtime": {
@@ -2224,257 +2220,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@swc/core": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core/-/core-1.15.8.tgz",
-      "integrity": "sha512-T8keoJjXaSUoVBCIjgL6wAnhADIb09GOELzKg10CjNg+vLX48P93SME6jTfte9MZIm5m+Il57H3rTSk/0kzDUw==",
-      "dev": true,
-      "hasInstallScript": true,
-      "license": "Apache-2.0",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@swc/counter": "^0.1.3",
-        "@swc/types": "^0.1.25"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/swc"
-      },
-      "optionalDependencies": {
-        "@swc/core-darwin-arm64": "1.15.8",
-        "@swc/core-darwin-x64": "1.15.8",
-        "@swc/core-linux-arm-gnueabihf": "1.15.8",
-        "@swc/core-linux-arm64-gnu": "1.15.8",
-        "@swc/core-linux-arm64-musl": "1.15.8",
-        "@swc/core-linux-x64-gnu": "1.15.8",
-        "@swc/core-linux-x64-musl": "1.15.8",
-        "@swc/core-win32-arm64-msvc": "1.15.8",
-        "@swc/core-win32-ia32-msvc": "1.15.8",
-        "@swc/core-win32-x64-msvc": "1.15.8"
-      },
-      "peerDependencies": {
-        "@swc/helpers": ">=0.5.17"
-      },
-      "peerDependenciesMeta": {
-        "@swc/helpers": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@swc/core-darwin-arm64": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-darwin-arm64/-/core-darwin-arm64-1.15.8.tgz",
-      "integrity": "sha512-M9cK5GwyWWRkRGwwCbREuj6r8jKdES/haCZ3Xckgkl8MUQJZA3XB7IXXK1IXRNeLjg6m7cnoMICpXv1v1hlJOg==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-darwin-x64": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-darwin-x64/-/core-darwin-x64-1.15.8.tgz",
-      "integrity": "sha512-j47DasuOvXl80sKJHSi2X25l44CMc3VDhlJwA7oewC1nV1VsSzwX+KOwE5tLnfORvVJJyeiXgJORNYg4jeIjYQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-linux-arm-gnueabihf": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-linux-arm-gnueabihf/-/core-linux-arm-gnueabihf-1.15.8.tgz",
-      "integrity": "sha512-siAzDENu2rUbwr9+fayWa26r5A9fol1iORG53HWxQL1J8ym4k7xt9eME0dMPXlYZDytK5r9sW8zEA10F2U3Xwg==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-linux-arm64-gnu": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-linux-arm64-gnu/-/core-linux-arm64-gnu-1.15.8.tgz",
-      "integrity": "sha512-o+1y5u6k2FfPYbTRUPvurwzNt5qd0NTumCTFscCNuBksycloXY16J8L+SMW5QRX59n4Hp9EmFa3vpvNHRVv1+Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-linux-arm64-musl": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-linux-arm64-musl/-/core-linux-arm64-musl-1.15.8.tgz",
-      "integrity": "sha512-koiCqL09EwOP1S2RShCI7NbsQuG6r2brTqUYE7pV7kZm9O17wZ0LSz22m6gVibpwEnw8jI3IE1yYsQTVpluALw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-linux-x64-gnu": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-linux-x64-gnu/-/core-linux-x64-gnu-1.15.8.tgz",
-      "integrity": "sha512-4p6lOMU3bC+Vd5ARtKJ/FxpIC5G8v3XLoPEZ5s7mLR8h7411HWC/LmTXDHcrSXRC55zvAVia1eldy6zDLz8iFQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-linux-x64-musl": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-linux-x64-musl/-/core-linux-x64-musl-1.15.8.tgz",
-      "integrity": "sha512-z3XBnbrZAL+6xDGAhJoN4lOueIxC/8rGrJ9tg+fEaeqLEuAtHSW2QHDHxDwkxZMjuF/pZ6MUTjHjbp8wLbuRLA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-win32-arm64-msvc": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-win32-arm64-msvc/-/core-win32-arm64-msvc-1.15.8.tgz",
-      "integrity": "sha512-djQPJ9Rh9vP8GTS/Df3hcc6XP6xnG5c8qsngWId/BLA9oX6C7UzCPAn74BG/wGb9a6j4w3RINuoaieJB3t+7iQ==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-win32-ia32-msvc": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-win32-ia32-msvc/-/core-win32-ia32-msvc-1.15.8.tgz",
-      "integrity": "sha512-/wfAgxORg2VBaUoFdytcVBVCgf1isWZIEXB9MZEUty4wwK93M/PxAkjifOho9RN3WrM3inPLabICRCEgdHpKKQ==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/core-win32-x64-msvc": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/core-win32-x64-msvc/-/core-win32-x64-msvc-1.15.8.tgz",
-      "integrity": "sha512-GpMePrh9Sl4d61o4KAHOOv5is5+zt6BEXCOCgs/H0FLGeii7j9bWDE8ExvKFy2GRRZVNR1ugsnzaGWHKM6kuzA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "Apache-2.0 AND MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/@swc/counter": {
-      "version": "0.1.3",
-      "resolved": "https://registry.npmjs.org/@swc/counter/-/counter-0.1.3.tgz",
-      "integrity": "sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "optional": true,
-      "peer": true
-    },
-    "node_modules/@swc/types": {
-      "version": "0.1.25",
-      "resolved": "https://registry.npmjs.org/@swc/types/-/types-0.1.25.tgz",
-      "integrity": "sha512-iAoY/qRhNH8a/hBvm3zKj9qQ4oc2+3w1unPJa2XvTK3XjeLXtzcCingVPw/9e5mn1+0yPqxcBGp9Jf0pkfMb1g==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@swc/counter": "^0.1.3"
-      }
-    },
-    "node_modules/@swc/wasm": {
-      "version": "1.15.8",
-      "resolved": "https://registry.npmjs.org/@swc/wasm/-/wasm-1.15.8.tgz",
-      "integrity": "sha512-RG2BxGbbsjtddFCo1ghKH6A/BMXbY1eMBfpysV0lJMCpI4DZOjW1BNBnxvBt7YsYmlJtmy5UXIg9/4ekBTFFaQ==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "optional": true,
-      "peer": true
-    },
     "node_modules/@tailwindcss/node": {
       "version": "4.1.18",
       "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.1.18.tgz",
@@ -2490,6 +2235,12 @@
         "tailwindcss": "4.1.18"
       }
     },
+    "node_modules/@tailwindcss/node/node_modules/tailwindcss": {
+      "version": "4.1.18",
+      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz",
+      "integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==",
+      "license": "MIT"
+    },
     "node_modules/@tailwindcss/oxide": {
       "version": "4.1.18",
       "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.1.18.tgz",
@@ -2732,6 +2483,12 @@
         "vite": "^5.2.0 || ^6 || ^7"
       }
     },
+    "node_modules/@tailwindcss/vite/node_modules/tailwindcss": {
+      "version": "4.1.18",
+      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz",
+      "integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==",
+      "license": "MIT"
+    },
     "node_modules/@testing-library/dom": {
       "version": "10.4.1",
       "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz",
@@ -3358,6 +3115,16 @@
       "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==",
       "license": "ISC"
     },
+    "node_modules/@upsetjs/venn.js": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/@upsetjs/venn.js/-/venn.js-2.0.0.tgz",
+      "integrity": "sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==",
+      "license": "MIT",
+      "optionalDependencies": {
+        "d3-selection": "^3.0.0",
+        "d3-transition": "^3.0.1"
+      }
+    },
     "node_modules/@vercel/build-utils": {
       "version": "13.2.11",
       "resolved": "https://registry.npmjs.org/@vercel/build-utils/-/build-utils-13.2.11.tgz",
@@ -3829,14 +3596,14 @@
       "license": "MIT"
     },
     "node_modules/axios": {
-      "version": "1.13.2",
-      "resolved": "https://registry.npmjs.org/axios/-/axios-1.13.2.tgz",
-      "integrity": "sha512-VPk9ebNqPcy5lRGuSlKx752IlDatOjT9paPlm8A7yOuW2Fbvp4X3JznJtT4f0GzGLLiWE9W8onz51SqLYwzGaA==",
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/axios/-/axios-1.15.0.tgz",
+      "integrity": "sha512-wWyJDlAatxk30ZJer+GeCWS209sA42X+N5jU2jy6oHTp7ufw8uzUTVFBX9+wTfAlhiJXGS0Bq7X6efruWjuK9Q==",
       "license": "MIT",
       "dependencies": {
-        "follow-redirects": "^1.15.6",
-        "form-data": "^4.0.4",
-        "proxy-from-env": "^1.1.0"
+        "follow-redirects": "^1.15.11",
+        "form-data": "^4.0.5",
+        "proxy-from-env": "^2.1.0"
       }
     },
     "node_modules/bail": {
@@ -4129,37 +3896,33 @@
       }
     },
     "node_modules/chevrotain": {
-      "version": "11.0.3",
-      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz",
-      "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==",
+      "version": "12.0.0",
+      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
+      "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/cst-dts-gen": "11.0.3",
-        "@chevrotain/gast": "11.0.3",
-        "@chevrotain/regexp-to-ast": "11.0.3",
-        "@chevrotain/types": "11.0.3",
-        "@chevrotain/utils": "11.0.3",
-        "lodash-es": "4.17.21"
+        "@chevrotain/cst-dts-gen": "12.0.0",
+        "@chevrotain/gast": "12.0.0",
+        "@chevrotain/regexp-to-ast": "12.0.0",
+        "@chevrotain/types": "12.0.0",
+        "@chevrotain/utils": "12.0.0"
+      },
+      "engines": {
+        "node": ">=22.0.0"
       }
     },
     "node_modules/chevrotain-allstar": {
-      "version": "0.3.1",
-      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.3.1.tgz",
-      "integrity": "sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==",
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.1.tgz",
+      "integrity": "sha512-PvVJm3oGqrveUVW2Vt/eZGeiAIsJszYweUcYwcskg9e+IubNYKKD+rHHem7A6XVO22eDAL+inxNIGAzZ/VIWlA==",
       "license": "MIT",
       "dependencies": {
         "lodash-es": "^4.17.21"
       },
       "peerDependencies": {
-        "chevrotain": "^11.0.0"
+        "chevrotain": "^12.0.0"
       }
     },
-    "node_modules/chevrotain/node_modules/lodash-es": {
-      "version": "4.17.21",
-      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz",
-      "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==",
-      "license": "MIT"
-    },
     "node_modules/chownr": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz",
@@ -4830,9 +4593,9 @@
       }
     },
     "node_modules/dagre-d3-es": {
-      "version": "7.0.13",
-      "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.13.tgz",
-      "integrity": "sha512-efEhnxpSuwpYOKRm/L5KbqoZmNNukHa/Flty4Wp62JRvgH2ojwVgPgdYyr4twpieZnyRDdIH7PY2mopX26+j2Q==",
+      "version": "7.0.14",
+      "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.14.tgz",
+      "integrity": "sha512-P4rFMVq9ESWqmOgK+dlXvOtLwYg0i7u0HBGJER0LZDJT2VHIPAMZ/riPxqJceWMStH5+E61QxFra9kIS3AqdMg==",
       "license": "MIT",
       "dependencies": {
         "d3": "^7.9.0",
@@ -6064,9 +5827,9 @@
       }
     },
     "node_modules/joi": {
-      "version": "18.0.2",
-      "resolved": "https://registry.npmjs.org/joi/-/joi-18.0.2.tgz",
-      "integrity": "sha512-RuCOQMIt78LWnktPoeBL0GErkNaJPTBGcYuyaBvUOQSpcpcLfWrHPPihYdOGbV5pam9VTWbeoF7TsGiHugcjGA==",
+      "version": "18.1.2",
+      "resolved": "https://registry.npmjs.org/joi/-/joi-18.1.2.tgz",
+      "integrity": "sha512-rF5MAmps5esSlhCA+N1b6IYHDw9j/btzGaqfgie522jS02Ju/HXBxamlXVlKEHAxoMKQL77HWI8jlqWsFuekZA==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
@@ -6076,7 +5839,7 @@
         "@hapi/pinpoint": "^2.0.1",
         "@hapi/tlds": "^1.1.1",
         "@hapi/topo": "^6.0.2",
-        "@standard-schema/spec": "^1.0.0"
+        "@standard-schema/spec": "^1.1.0"
       },
       "engines": {
         "node": ">= 20"
@@ -6098,14 +5861,14 @@
       "license": "MIT"
     },
     "node_modules/jsdom": {
-      "version": "29.0.0",
-      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.0.0.tgz",
-      "integrity": "sha512-9FshNB6OepopZ08unmmGpsF7/qCjxGPbo3NbgfJAnPeHXnsODE9WWffXZtRFRFe0ntzaAOcSKNJFz8wiyvF1jQ==",
+      "version": "29.0.2",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.0.2.tgz",
+      "integrity": "sha512-9VnGEBosc/ZpwyOsJBCQ/3I5p7Q5ngOY14a9bf5btenAORmZfDse1ZEheMiWcJ3h81+Fv7HmJFdS0szo/waF2w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@asamuzakjp/css-color": "^5.0.1",
-        "@asamuzakjp/dom-selector": "^7.0.2",
+        "@asamuzakjp/css-color": "^5.1.5",
+        "@asamuzakjp/dom-selector": "^7.0.6",
         "@bramus/specificity": "^2.4.2",
         "@csstools/css-syntax-patches-for-csstree": "^1.1.1",
         "@exodus/bytes": "^1.15.0",
@@ -6119,7 +5882,7 @@
         "saxes": "^6.0.0",
         "symbol-tree": "^3.2.4",
         "tough-cookie": "^6.0.1",
-        "undici": "^7.24.3",
+        "undici": "^7.24.5",
         "w3c-xmlserializer": "^5.0.0",
         "webidl-conversions": "^8.0.1",
         "whatwg-mimetype": "^5.0.0",
@@ -6152,9 +5915,9 @@
       }
     },
     "node_modules/jsdom/node_modules/undici": {
-      "version": "7.24.3",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.3.tgz",
-      "integrity": "sha512-eJdUmK/Wrx2d+mnWWmwwLRyA7OQCkLap60sk3dOK4ViZR7DKwwptwuIvFBg2HaiP9ESaEdhtpSymQPvytpmkCA==",
+      "version": "7.25.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.25.0.tgz",
+      "integrity": "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -6295,19 +6058,21 @@
       }
     },
     "node_modules/langium": {
-      "version": "3.3.1",
-      "resolved": "https://registry.npmjs.org/langium/-/langium-3.3.1.tgz",
-      "integrity": "sha512-QJv/h939gDpvT+9SiLVlY7tZC3xB2qK57v0J04Sh9wpMb6MP1q8gB21L3WIo8T5P1MSMg3Ep14L7KkDCFG3y4w==",
+      "version": "4.2.2",
+      "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.2.tgz",
+      "integrity": "sha512-JUshTRAfHI4/MF9dH2WupvjSXyn8JBuUEWazB8ZVJUtXutT0doDlAv1XKbZ1Pb5sMexa8FF4CFBc0iiul7gbUQ==",
       "license": "MIT",
       "dependencies": {
-        "chevrotain": "~11.0.3",
-        "chevrotain-allstar": "~0.3.0",
+        "@chevrotain/regexp-to-ast": "~12.0.0",
+        "chevrotain": "~12.0.0",
+        "chevrotain-allstar": "~0.4.1",
         "vscode-languageserver": "~9.0.1",
         "vscode-languageserver-textdocument": "~1.0.11",
-        "vscode-uri": "~3.0.8"
+        "vscode-uri": "~3.1.0"
       },
       "engines": {
-        "node": ">=16.0.0"
+        "node": ">=20.10.0",
+        "npm": ">=10.2.3"
       }
     },
     "node_modules/langsmith": {
@@ -6613,16 +6378,16 @@
       }
     },
     "node_modules/lodash": {
-      "version": "4.17.23",
-      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz",
-      "integrity": "sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==",
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
       "dev": true,
       "license": "MIT"
     },
     "node_modules/lodash-es": {
-      "version": "4.17.22",
-      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.22.tgz",
-      "integrity": "sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==",
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz",
+      "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==",
       "license": "MIT"
     },
     "node_modules/longest-streak": {
@@ -7072,27 +6837,28 @@
       }
     },
     "node_modules/mermaid": {
-      "version": "11.12.2",
-      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.12.2.tgz",
-      "integrity": "sha512-n34QPDPEKmaeCG4WDMGy0OT6PSyxKCfy2pJgShP+Qow2KLrvWjclwbc3yXfSIf4BanqWEhQEpngWwNp/XhZt6w==",
+      "version": "11.14.0",
+      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
+      "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
       "license": "MIT",
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.1",
-        "@iconify/utils": "^3.0.1",
-        "@mermaid-js/parser": "^0.6.3",
+        "@iconify/utils": "^3.0.2",
+        "@mermaid-js/parser": "^1.1.0",
         "@types/d3": "^7.4.3",
-        "cytoscape": "^3.29.3",
+        "@upsetjs/venn.js": "^2.0.0",
+        "cytoscape": "^3.33.1",
         "cytoscape-cose-bilkent": "^4.1.0",
         "cytoscape-fcose": "^2.2.0",
         "d3": "^7.9.0",
         "d3-sankey": "^0.12.3",
-        "dagre-d3-es": "7.0.13",
-        "dayjs": "^1.11.18",
-        "dompurify": "^3.2.5",
-        "katex": "^0.16.22",
+        "dagre-d3-es": "7.0.14",
+        "dayjs": "^1.11.19",
+        "dompurify": "^3.3.1",
+        "katex": "^0.16.25",
         "khroma": "^2.1.0",
-        "lodash-es": "^4.17.21",
-        "marked": "^16.2.1",
+        "lodash-es": "^4.17.23",
+        "marked": "^16.3.0",
         "roughjs": "^4.6.6",
         "stylis": "^4.3.6",
         "ts-dedent": "^2.2.0",
@@ -8317,10 +8083,13 @@
       }
     },
     "node_modules/proxy-from-env": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
-      "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
-      "license": "MIT"
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz",
+      "integrity": "sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
     },
     "node_modules/punycode": {
       "version": "2.3.1",
@@ -9006,9 +8775,9 @@
       "license": "MIT"
     },
     "node_modules/tailwindcss": {
-      "version": "4.1.18",
-      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz",
-      "integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==",
+      "version": "4.2.2",
+      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.2.2.tgz",
+      "integrity": "sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==",
       "license": "MIT"
     },
     "node_modules/tapable": {
@@ -10270,9 +10039,9 @@
       "license": "MIT"
     },
     "node_modules/vscode-uri": {
-      "version": "3.0.8",
-      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.0.8.tgz",
-      "integrity": "sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==",
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
+      "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
       "license": "MIT"
     },
     "node_modules/w3c-xmlserializer": {
@@ -10289,15 +10058,15 @@
       }
     },
     "node_modules/wait-on": {
-      "version": "8.0.5",
-      "resolved": "https://registry.npmjs.org/wait-on/-/wait-on-8.0.5.tgz",
-      "integrity": "sha512-J3WlS0txVHkhLRb2FsmRg3dkMTCV1+M6Xra3Ho7HzZDHpE7DCOnoSoCJsZotrmW3uRMhvIJGSKUKrh/MeF4iag==",
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/wait-on/-/wait-on-9.0.5.tgz",
+      "integrity": "sha512-qgnbHDfDTRIp73ANEJNRW/7kn8CrDUcvZz18xotJQku/P4saTGkbIzvnMZebPmVvVNUiRq1qWAPyqCH+W4H8KA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "axios": "^1.12.1",
-        "joi": "^18.0.1",
-        "lodash": "^4.17.21",
+        "axios": "^1.15.0",
+        "joi": "^18.1.2",
+        "lodash": "^4.18.1",
         "minimist": "^1.2.8",
         "rxjs": "^7.8.2"
       },
@@ -10305,7 +10074,7 @@
         "wait-on": "bin/wait-on"
       },
       "engines": {
-        "node": ">=12.0.0"
+        "node": ">=20.0.0"
       }
     },
     "node_modules/webidl-conversions": {
diff --git a/gitnexus-web/package.json b/gitnexus-web/package.json
index 9616845d1..08b2eed7d 100644
--- a/gitnexus-web/package.json
+++ b/gitnexus-web/package.json
@@ -39,7 +39,7 @@
     "langchain": "^1.2.10",
     "lru-cache": "^11.2.4",
     "lucide-react": "^0.562.0",
-    "mermaid": "^11.12.2",
+    "mermaid": "^11.14.0",
     "mnemonist": "^0.39.0",
     "pandemonium": "^2.4.0",
     "react": "^18.3.1",
@@ -49,7 +49,7 @@
     "react-zoom-pan-pinch": "^3.7.0",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
-    "tailwindcss": "^4.1.18",
+    "tailwindcss": "^4.2.2",
     "uuid": "^13.0.0",
     "zod": "^3.25.76"
   },
@@ -67,11 +67,11 @@
     "@vercel/node": "^5.5.16",
     "@vitejs/plugin-react": "^5.1.0",
     "@vitest/coverage-v8": "^3.2.4",
-    "jsdom": "^29.0.0",
+    "jsdom": "^29.0.2",
     "tree-sitter-wasms": "^0.1.13",
     "typescript": "^5.4.5",
     "vite": "^5.2.0",
     "vitest": "^3.2.4",
-    "wait-on": "^8.0.5"
+    "wait-on": "^9.0.5"
   }
 }
diff --git a/gitnexus-web/vite.config.ts b/gitnexus-web/vite.config.ts
index b177f6804..a62b9e586 100644
--- a/gitnexus-web/vite.config.ts
+++ b/gitnexus-web/vite.config.ts
@@ -16,6 +16,7 @@ export default defineConfig({
     alias: {
       '@': path.resolve(__dirname, './src'),
       '@shared': path.resolve(__dirname, '../shared'),
+      'gitnexus-shared': path.resolve(__dirname, '../gitnexus-shared/src/index.ts'),
       // Fix for Rollup failing to resolve this deep import from @langchain/anthropic
       '@anthropic-ai/sdk/lib/transform-json-schema': path.resolve(
         __dirname,
diff --git a/gitnexus/CHANGELOG.md b/gitnexus/CHANGELOG.md
index 80096345d..203089d93 100644
--- a/gitnexus/CHANGELOG.md
+++ b/gitnexus/CHANGELOG.md
@@ -2,6 +2,46 @@
 
 All notable changes to GitNexus will be documented in this file.
 
+## [1.6.2] - 2026-04-18
+
+### Added
+
+- **Docker support** — containerized ingestion and MCP serving for reproducible runs on CI and container platforms (#848)
+- **Language-agnostic heritage extractor** — config+factory pattern for class-heritage extraction (EXTENDS / IMPLEMENTS), completing the extractor refactor alongside method/field/call/variable (#890)
+- **Language-agnostic call extractor** — config+factory pattern that collapses ~225 lines of inline parse-worker logic into declarative per-language configs (#877)
+- **Language-agnostic variable extractor** — structured metadata for `Const` / `Static` / `Variable` nodes via config+factory pattern (#878)
+- **AST-aware embedding chunking** — offset-based splitting preserves symbol boundaries, improving semantic search precision on large files (#889)
+- **HTTP consumer detection for jQuery and axios object-form** — `$.ajax` / `$.get` / `$.post` and `axios({ url, method })` now recognized as HTTP call sites (#887)
+
+### Fixed
+
+- **Python external dotted imports** — avoid spurious same-file matches when an import path like `foo.bar.baz` refers to a third-party module (#899)
+- **Worker warnings no longer terminate ingestion** — non-fatal parser warnings keep the pipeline running instead of aborting the run (#900, #261)
+- **Global-install upgrade `ENOTEMPTY`** — devendored `tree-sitter-proto` install lifecycle + preinstall cleanup so `npm i -g gitnexus@latest` succeeds on top of an older install (#843, #846)
+- **`env.cacheDir`** now defaults to a user-writable location, unblocking ingestion on systems where the install directory is read-only (#845)
+- **Content-hash staleness detection for embeddings** — zero-node rebuilds no longer skip vector-index creation, fixing semantic search after selective re-analysis (#831)
+- **`tree-sitter-c-sharp` version pin** — locked to 0.23.1 to avoid a breaking change in a transitive prerelease (#834)
+- **`release-drafter` v7 CI** — replaced the removed `disable-releaser` flag with `dry-run` so release-note drafts still work
+- **`npm arborist` crash from `tree-sitter-dart`** — switched the dependency URL format so `npm install` no longer crashes on clean installs
+- **Service-group `ManifestExtractor`** — `config.links` now wires the manifest extractor properly, restoring cross-link discovery that had silently dropped to zero
+
+### Changed
+
+- **SemanticModel wired as a first-class resolution input (SM-20)** — `call-processor`, `resolution-context`, `type-env`, and `heritage-map` now consult `table.model.*` directly; 37 internal call sites migrated off the SymbolTable wrapper (#885)
+- **Per-strategy `ImportSemantics` hooks** — `named` / `wildcard-transitive` / `wildcard-leaf` / `namespace` strategies split into composable hooks, replacing the monolithic conditional (Strategies 1–4 of #886)
+- **Class extraction configs moved to `configs/` subdirectory** — per-language class configs now co-locate with the other extractor configs, completing the extractor layer's directory convention (#879)
+- **CLI AI-context trimmed** — duplicated CLAUDE.md block removed from the shipped context, reducing token usage in LLM-consuming workflows (#904)
+- **LLM context files optimized** — AI-consumed documentation tuned for accuracy and token efficiency (#857)
+- **Workflow concurrency standardized** — all CI workflows adopt the consistent concurrency key pattern documented in CONTRIBUTING.md; release-note labeling automated (#837)
+- **E2E status-ready timeout raised** — 45s accommodates parallel-worker startup variance on CI (#908)
+
+### Chore / Dependencies
+
+- **tree-sitter 0.25 upgrade readiness** — daily Dependabot monitor for the upcoming major-version bump (#847)
+- Dependency bumps: `glob` 11.1.0 → 13.0.6 (#867), `commander` 12.1.0 → 14.0.3 (#868), `@huggingface/transformers` (#869), `@modelcontextprotocol/sdk` (#866), `lru-cache` 11.2.7 → 11.3.5 (#870), `mnemonist` 0.39.8 → 0.40.3 (#871), `@ladybugdb/core` (#873)
+- gitnexus-web dependency bumps: `mermaid` 11.12.2 → 11.14.0 (#860), `tailwindcss` (#861), `jsdom` 29.0.0 → 29.0.2 (#863), `wait-on` 8.0.5 → 9.0.5 (#859), `@vitest/coverage-v8` (#864)
+- GitHub Actions bumps: `actions/checkout` 4.3.1 → 6.0.2 (#842), `actions/upload-artifact` 4.6.2 → 7.0.1 (#838), `actions/setup-node` 4.4.0 → 6.3.0 (#841), `actions/cache` 5.0.4 → 5.0.5 (#840), `actions/github-script` 7.0.1 → 9.0.0 (#850), `dorny/paths-filter` 3.0.2 → 4.0.1 (#839), `amannn/action-semantic-pull-request` 6.1.1 (#853), `release-drafter/release-drafter` 6.0.0 → 7.2.0 (#852), `marocchino/sticky-pull-request-comment` 3.0.4 (#851), `softprops/action-gh-release` 2.5.0 → 3.0.0 (#849)
+
 ## [1.6.1] - 2026-04-13
 
 ### Added
diff --git a/gitnexus/Dockerfile.test b/gitnexus/Dockerfile.test
index b2d22384f..7cafbe2c1 100644
--- a/gitnexus/Dockerfile.test
+++ b/gitnexus/Dockerfile.test
@@ -1,6 +1,6 @@
 FROM node:20-bookworm
 WORKDIR /app
-RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+RUN apt-get -o Acquire::Check-Valid-Until=false -o Acquire::Check-Date=false update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
 COPY . .
 RUN npm ci --ignore-scripts \
     && node scripts/patch-tree-sitter-swift.cjs \
diff --git a/gitnexus/package-lock.json b/gitnexus/package-lock.json
index def88c93c..76afc1fde 100644
--- a/gitnexus/package-lock.json
+++ b/gitnexus/package-lock.json
@@ -1,31 +1,31 @@
 {
   "name": "gitnexus",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "gitnexus",
-      "version": "1.6.1",
+      "version": "1.6.2",
       "hasInstallScript": true,
       "license": "PolyForm-Noncommercial-1.0.0",
       "dependencies": {
-        "@huggingface/transformers": "^3.0.0",
+        "@huggingface/transformers": "^4.1.0",
         "@ladybugdb/core": "^0.15.2",
         "@modelcontextprotocol/sdk": "^1.0.0",
         "@scarf/scarf": "^1.4.0",
         "cli-progress": "^3.12.0",
-        "commander": "^12.0.0",
+        "commander": "^14.0.3",
         "cors": "^2.8.5",
         "express": "^4.19.2",
-        "glob": "^11.0.0",
+        "glob": "^13.0.6",
         "graphology": "^0.25.4",
         "graphology-indices": "^0.17.0",
         "graphology-utils": "^2.3.0",
         "ignore": "^7.0.5",
         "js-yaml": "^4.1.1",
         "lru-cache": "^11.0.0",
-        "mnemonist": "^0.39.0",
+        "mnemonist": "^0.40.3",
         "onnxruntime-node": "^1.24.0",
         "pandemonium": "^2.4.0",
         "tree-sitter": "^0.21.1",
@@ -138,14 +138,14 @@
       }
     },
     "node_modules/@emnapi/core": {
-      "version": "1.9.1",
-      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.1.tgz",
-      "integrity": "sha512-mukuNALVsoix/w1BJwFzwXBN/dHeejQtuVzcDsfOEsdpCumXb/E9j8w11h5S54tT1xhifGfbbSm/ICrObRb3KA==",
+      "version": "1.9.2",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.2.tgz",
+      "integrity": "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==",
       "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@emnapi/wasi-threads": "1.2.0",
+        "@emnapi/wasi-threads": "1.2.1",
         "tslib": "^2.4.0"
       }
     },
@@ -160,9 +160,9 @@
       }
     },
     "node_modules/@emnapi/wasi-threads": {
-      "version": "1.2.0",
-      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.0.tgz",
-      "integrity": "sha512-N10dEJNSsUx41Z6pZsXU8FjPjpBEplgH24sfkmITrBED1/U2Esum9F3lfLrMjKHHjmi557zQn7kR9R+XWXu5Rg==",
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
+      "integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
       "dev": true,
       "license": "MIT",
       "optional": true,
@@ -633,16 +633,23 @@
         "node": ">=18"
       }
     },
+    "node_modules/@huggingface/tokenizers": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/@huggingface/tokenizers/-/tokenizers-0.1.3.tgz",
+      "integrity": "sha512-8rF/RRT10u+kn7YuUbUg0OF30K8rjTc78aHpxT+qJ1uWSqxT1MHi8+9ltwYfkFYJzT/oS+qw3JVfHtNMGAdqyA==",
+      "license": "Apache-2.0"
+    },
     "node_modules/@huggingface/transformers": {
-      "version": "3.8.1",
-      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-3.8.1.tgz",
-      "integrity": "sha512-tsTk4zVjImqdqjS8/AOZg2yNLd1z9S5v+7oUPpXaasDRwEDhB+xnglK1k5cad26lL5/ZIaeREgWWy0bs9y9pPA==",
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-4.1.0.tgz",
+      "integrity": "sha512-WiMf9eyvF6V2pj4gs12A7GQV3svyFIBtB/W+Hn5lT5E5DyqWUno1ZrWoAfJv69X1RNv/0GoOo6DFmL6NOYd+rg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@huggingface/jinja": "^0.5.3",
-        "onnxruntime-node": "1.21.0",
-        "onnxruntime-web": "1.22.0-dev.20250409-89f8206ba4",
-        "sharp": "^0.34.1"
+        "@huggingface/jinja": "^0.5.6",
+        "@huggingface/tokenizers": "^0.1.3",
+        "onnxruntime-node": "1.24.3",
+        "onnxruntime-web": "1.26.0-dev.20260410-5e55544225",
+        "sharp": "^0.34.5"
       }
     },
     "node_modules/@img/colour": {
@@ -1110,15 +1117,6 @@
         "url": "https://opencollective.com/libvips"
       }
     },
-    "node_modules/@isaacs/cliui": {
-      "version": "9.0.0",
-      "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-9.0.0.tgz",
-      "integrity": "sha512-AokJm4tuBHillT+FpMtxQ60n8ObyXBatq7jD2/JA9dxbDDokKQm8KMht5ibGzLVU9IJDIKK4TPKgMHEYMn3lMg==",
-      "license": "BlueOak-1.0.0",
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/@isaacs/fs-minipass": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/@isaacs/fs-minipass/-/fs-minipass-4.0.1.tgz",
@@ -1160,9 +1158,9 @@
       }
     },
     "node_modules/@ladybugdb/core": {
-      "version": "0.15.2",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.15.2.tgz",
-      "integrity": "sha512-DpseEj9CM/QTV0z+rvBk6nB2mOoG4GVhnKKLiXChGTVddgpH6R/Pv2YiDZB7rUIDnFpJxVQNbQaYEkZ7i1h1KA==",
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core/-/core-0.15.3.tgz",
+      "integrity": "sha512-Xa8VmWhMTvTCWmApnqm9FJtyxxV+CiMCokl1p9vEfXNuBz3SWXWGDmHlzKikswtQbUe9tTV3J9MxPdVFVE6/yg==",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -1170,16 +1168,16 @@
         "node-addon-api": "^6.0.0"
       },
       "optionalDependencies": {
-        "@ladybugdb/core-darwin-arm64": "0.15.2",
-        "@ladybugdb/core-linux-arm64": "0.15.2",
-        "@ladybugdb/core-linux-x64": "0.15.2",
-        "@ladybugdb/core-win32-x64": "0.15.2"
+        "@ladybugdb/core-darwin-arm64": "0.15.3",
+        "@ladybugdb/core-linux-arm64": "0.15.3",
+        "@ladybugdb/core-linux-x64": "0.15.3",
+        "@ladybugdb/core-win32-x64": "0.15.3"
       }
     },
     "node_modules/@ladybugdb/core-darwin-arm64": {
-      "version": "0.15.2",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.15.2.tgz",
-      "integrity": "sha512-ifLyUTPzlh2zR1IqkUT5AfldX+X4zfWBzwakmGTgMPxyrEiRNDwUKfnNxHeLQ/TJTOS/nfzYxxLLt5CZf2/FhA==",
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-darwin-arm64/-/core-darwin-arm64-0.15.3.tgz",
+      "integrity": "sha512-+bqAb3wbbmxPSeNQjbVd6Ek5K8GbHr1KlDr09YkNqZ7XWhKqWxbs097xAG9bynLcZh9oxok2PGCoK4w5YHs11w==",
       "cpu": [
         "arm64"
       ],
@@ -1190,9 +1188,9 @@
       ]
     },
     "node_modules/@ladybugdb/core-linux-arm64": {
-      "version": "0.15.2",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.15.2.tgz",
-      "integrity": "sha512-9537UbHOiuSr/BaTfjcoBsHxEKF4uEXWyXEjm/AQCGXQFocX3nQDVNDYJzuDYjKZ51oJRJ0oSuesAStOCwjolA==",
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-arm64/-/core-linux-arm64-0.15.3.tgz",
+      "integrity": "sha512-Z8Ur6YbC5y6pgtKh/7b1/xdeRHy69sGhsoVJm1tc9xp9Zrar6G2A71bEdjOdDJ/mDRt6RtY0zdhUgIgQXYQtbQ==",
       "cpu": [
         "arm64"
       ],
@@ -1203,9 +1201,9 @@
       ]
     },
     "node_modules/@ladybugdb/core-linux-x64": {
-      "version": "0.15.2",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.15.2.tgz",
-      "integrity": "sha512-1+xLoapjbMQzDHxcPpMPt8Suuvms3nhOIZFNGPDcWz90NwEmLAjWNFQZZHeg8DRz0vG2j8UY292bvGORVcxs8g==",
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-linux-x64/-/core-linux-x64-0.15.3.tgz",
+      "integrity": "sha512-DT9xBc91tuxzjRu1dJ3xGt/K/uR1Q8bX5+8tCtj66UbVIVvp1RWAAE9phq7eahcF/3zBuFRonkxW/tTyQdQIlQ==",
       "cpu": [
         "x64"
       ],
@@ -1216,9 +1214,9 @@
       ]
     },
     "node_modules/@ladybugdb/core-win32-x64": {
-      "version": "0.15.2",
-      "resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.15.2.tgz",
-      "integrity": "sha512-+LIJVKBNSrf2bGruJO4l0ihrLKZkv5+lNitK8xc3T7gC1bcc+FaYtRMvlgZP6Qh2rEHAjqfbaSKVrdw0M2EXTw==",
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/@ladybugdb/core-win32-x64/-/core-win32-x64-0.15.3.tgz",
+      "integrity": "sha512-ymHC8nHGIT7M9aditBQFIystxW+WoqvI3xklz22BHaFpU9CrTNtdU20K6cuRZvqEA2//Edu7kMoP9OwLkIleCg==",
       "cpu": [
         "x64"
       ],
@@ -1235,9 +1233,9 @@
       "license": "MIT"
     },
     "node_modules/@modelcontextprotocol/sdk": {
-      "version": "1.28.0",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.28.0.tgz",
-      "integrity": "sha512-gmloF+i+flI8ouQK7MWW4mOwuMh4RePBuPFAEPC6+pdqyWOUMDOixb6qZ69owLJpz6XmyllCouc4t8YWO+E2Nw==",
+      "version": "1.29.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
+      "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
       "license": "MIT",
       "dependencies": {
         "@hono/node-server": "^1.19.9",
@@ -1537,26 +1535,28 @@
       }
     },
     "node_modules/@napi-rs/wasm-runtime": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.1.tgz",
-      "integrity": "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A==",
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.4.tgz",
+      "integrity": "sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==",
       "dev": true,
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@emnapi/core": "^1.7.1",
-        "@emnapi/runtime": "^1.7.1",
         "@tybys/wasm-util": "^0.10.1"
       },
       "funding": {
         "type": "github",
         "url": "https://github.com/sponsors/Brooooooklyn"
+      },
+      "peerDependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1"
       }
     },
     "node_modules/@oxc-project/types": {
-      "version": "0.122.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.122.0.tgz",
-      "integrity": "sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==",
+      "version": "0.124.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.124.0.tgz",
+      "integrity": "sha512-VBFWMTBvHxS11Z5Lvlr3IWgrwhMTXV+Md+EQF0Xf60+wAdsGFTBx7X7K/hP4pi8N7dcm1RvcHwDxZ16Qx8keUg==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -1628,9 +1628,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.12.tgz",
-      "integrity": "sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-YYe6aWruPZDtHNpwu7+qAHEMbQ/yRl6atqb/AhznLTnD3UY99Q1jE7ihLSahNWkF4EqRPVC4SiR4O0UkLK02tA==",
       "cpu": [
         "arm64"
       ],
@@ -1645,9 +1645,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.12.tgz",
-      "integrity": "sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-oArR/ig8wNTPYsXL+Mzhs0oxhxfuHRfG7Ikw7jXsw8mYOtk71W0OkF2VEVh699pdmzjPQsTjlD1JIOoHkLP1Fg==",
       "cpu": [
         "arm64"
       ],
@@ -1662,9 +1662,9 @@
       }
     },
     "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.12.tgz",
-      "integrity": "sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-YzeVqOqjPYvUbJSWJ4EDL8ahbmsIXQpgL3JVipmN+MX0XnXMeWomLN3Fb+nwCmP/jfyqte5I3XRSm7OfQrbyxw==",
       "cpu": [
         "x64"
       ],
@@ -1679,9 +1679,9 @@
       }
     },
     "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.12.tgz",
-      "integrity": "sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-9Erhx956jeQ0nNTyif1+QWAXDRD38ZNjr//bSHrt6wDwB+QkAfl2q6Mn1k6OBPerznjRmbM10lgRb1Pli4xZPw==",
       "cpu": [
         "x64"
       ],
@@ -1696,9 +1696,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.12.tgz",
-      "integrity": "sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.15.tgz",
+      "integrity": "sha512-cVwk0w8QbZJGTnP/AHQBs5yNwmpgGYStL88t4UIaqcvYJWBfS0s3oqVLZPwsPU6M0zlW4GqjP0Zq5MnAGwFeGA==",
       "cpu": [
         "arm"
       ],
@@ -1713,9 +1713,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.12.tgz",
-      "integrity": "sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-eBZ/u8iAK9SoHGanqe/jrPnY0JvBN6iXbVOsbO38mbz+ZJsaobExAm1Iu+rxa4S1l2FjG0qEZn4Rc6X8n+9M+w==",
       "cpu": [
         "arm64"
       ],
@@ -1730,9 +1730,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.12.tgz",
-      "integrity": "sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.15.tgz",
+      "integrity": "sha512-ZvRYMGrAklV9PEkgt4LQM6MjQX2P58HPAuecwYObY2DhS2t35R0I810bKi0wmaYORt6m/2Sm+Z+nFgb0WhXNcQ==",
       "cpu": [
         "arm64"
       ],
@@ -1747,9 +1747,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.12.tgz",
-      "integrity": "sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-VDpgGBzgfg5hLg+uBpCLoFG5kVvEyafmfxGUV0UHLcL5irxAK7PKNeC2MwClgk6ZAiNhmo9FLhRYgvMmedLtnQ==",
       "cpu": [
         "ppc64"
       ],
@@ -1764,9 +1764,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.12.tgz",
-      "integrity": "sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-y1uXY3qQWCzcPgRJATPSOUP4tCemh4uBdY7e3EZbVwCJTY3gLJWnQABgeUetvED+bt1FQ01OeZwvhLS2bpNrAQ==",
       "cpu": [
         "s390x"
       ],
@@ -1781,9 +1781,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.12.tgz",
-      "integrity": "sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.15.tgz",
+      "integrity": "sha512-023bTPBod7J3Y/4fzAN6QtpkSABR0rigtrwaP+qSEabUh5zf6ELr9Nc7GujaROuPY3uwdSIXWrvhn1KxOvurWA==",
       "cpu": [
         "x64"
       ],
@@ -1798,9 +1798,9 @@
       }
     },
     "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.12.tgz",
-      "integrity": "sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.15.tgz",
+      "integrity": "sha512-witB2O0/hU4CgfOOKUoeFgQ4GktPi1eEbAhaLAIpgD6+ZnhcPkUtPsoKKHRzmOoWPZue46IThdSgdo4XneOLYw==",
       "cpu": [
         "x64"
       ],
@@ -1815,9 +1815,9 @@
       }
     },
     "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.12.tgz",
-      "integrity": "sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.15.tgz",
+      "integrity": "sha512-UCL68NJ0Ud5zRipXZE9dF5PmirzJE4E4BCIOOssEnM7wLDsxjc6Qb0sGDxTNRTP53I6MZpygyCpY8Aa8sPfKPg==",
       "cpu": [
         "arm64"
       ],
@@ -1832,9 +1832,9 @@
       }
     },
     "node_modules/@rolldown/binding-wasm32-wasi": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.12.tgz",
-      "integrity": "sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.15.tgz",
+      "integrity": "sha512-ApLruZq/ig+nhaE7OJm4lDjayUnOHVUa77zGeqnqZ9pn0ovdVbbNPerVibLXDmWeUZXjIYIT8V3xkT58Rm9u5Q==",
       "cpu": [
         "wasm32"
       ],
@@ -1842,16 +1842,29 @@
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@napi-rs/wasm-runtime": "^1.1.1"
+        "@emnapi/core": "1.9.2",
+        "@emnapi/runtime": "1.9.2",
+        "@napi-rs/wasm-runtime": "^1.1.3"
       },
       "engines": {
         "node": ">=14.0.0"
       }
     },
+    "node_modules/@rolldown/binding-wasm32-wasi/node_modules/@emnapi/runtime": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.9.2.tgz",
+      "integrity": "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
     "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.12.tgz",
-      "integrity": "sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.15.tgz",
+      "integrity": "sha512-KmoUoU7HnN+Si5YWJigfTws1jz1bKBYDQKdbLspz0UaqjjFkddHsqorgiW1mxcAj88lYUE6NC/zJNwT+SloqtA==",
       "cpu": [
         "arm64"
       ],
@@ -1866,9 +1879,9 @@
       }
     },
     "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.12.tgz",
-      "integrity": "sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.15.tgz",
+      "integrity": "sha512-3P2A8L+x75qavWLe/Dll3EYBJLQmtkJN8rfh+U/eR3MqMgL/h98PhYI+JFfXuDPgPeCB7iZAKiqii5vqOvnA0g==",
       "cpu": [
         "x64"
       ],
@@ -1883,9 +1896,9 @@
       }
     },
     "node_modules/@rolldown/pluginutils": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.12.tgz",
-      "integrity": "sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.15.tgz",
+      "integrity": "sha512-UromN0peaE53IaBRe9W7CjrZgXl90fqGpK+mIZbA3qSTeYqg3pqpROBdIPvOG3F5ereDHNwoHBI2e50n1BDr1g==",
       "dev": true,
       "license": "MIT"
     },
@@ -2091,14 +2104,14 @@
       "license": "MIT"
     },
     "node_modules/@vitest/coverage-v8": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.2.tgz",
-      "integrity": "sha512-sPK//PHO+kAkScb8XITeB1bf7fsk85Km7+rt4eeuRR3VS1/crD47cmV5wicisJmjNdfeokTZwjMk4Mj2d58Mgg==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.4.tgz",
+      "integrity": "sha512-x7FptB5oDruxNPDNY2+S8tCh0pcq7ymCe1gTHcsp733jYjrJl8V1gMUlVysuCD9Kz46Xz9t1akkv08dPcYDs1w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@bcoe/v8-coverage": "^1.0.2",
-        "@vitest/utils": "4.1.2",
+        "@vitest/utils": "4.1.4",
         "ast-v8-to-istanbul": "^1.0.0",
         "istanbul-lib-coverage": "^3.2.2",
         "istanbul-lib-report": "^3.0.1",
@@ -2112,8 +2125,8 @@
         "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "@vitest/browser": "4.1.2",
-        "vitest": "4.1.2"
+        "@vitest/browser": "4.1.4",
+        "vitest": "4.1.4"
       },
       "peerDependenciesMeta": {
         "@vitest/browser": {
@@ -2122,16 +2135,16 @@
       }
     },
     "node_modules/@vitest/expect": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.2.tgz",
-      "integrity": "sha512-gbu+7B0YgUJ2nkdsRJrFFW6X7NTP44WlhiclHniUhxADQJH5Szt9mZ9hWnJPJ8YwOK5zUOSSlSvyzRf0u1DSBQ==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.4.tgz",
+      "integrity": "sha512-iPBpra+VDuXmBFI3FMKHSFXp3Gx5HfmSCE8X67Dn+bwephCnQCaB7qWK2ldHa+8ncN8hJU8VTMcxjPpyMkUjww==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "@standard-schema/spec": "^1.1.0",
         "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.2",
-        "@vitest/utils": "4.1.2",
+        "@vitest/spy": "4.1.4",
+        "@vitest/utils": "4.1.4",
         "chai": "^6.2.2",
         "tinyrainbow": "^3.1.0"
       },
@@ -2140,13 +2153,13 @@
       }
     },
     "node_modules/@vitest/mocker": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.2.tgz",
-      "integrity": "sha512-Ize4iQtEALHDttPRCmN+FKqOl2vxTiNUhzobQFFt/BM1lRUTG7zRCLOykG/6Vo4E4hnUdfVLo5/eqKPukcWW7Q==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.4.tgz",
+      "integrity": "sha512-R9HTZBhW6yCSGbGQnDnH3QHfJxokKN4KB+Yvk9Q1le7eQNYwiCyKxmLmurSpFy6BzJanSLuEUDrD+j97Q+ZLPg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/spy": "4.1.2",
+        "@vitest/spy": "4.1.4",
         "estree-walker": "^3.0.3",
         "magic-string": "^0.30.21"
       },
@@ -2167,9 +2180,9 @@
       }
     },
     "node_modules/@vitest/pretty-format": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.2.tgz",
-      "integrity": "sha512-dwQga8aejqeuB+TvXCMzSQemvV9hNEtDDpgUKDzOmNQayl2OG241PSWeJwKRH3CiC+sESrmoFd49rfnq7T4RnA==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.4.tgz",
+      "integrity": "sha512-ddmDHU0gjEUyEVLxtZa7xamrpIefdEETu3nZjWtHeZX4QxqJ7tRxSteHVXJOcr8jhiLoGAhkK4WJ3WqBpjx42A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2180,13 +2193,13 @@
       }
     },
     "node_modules/@vitest/runner": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.2.tgz",
-      "integrity": "sha512-Gr+FQan34CdiYAwpGJmQG8PgkyFVmARK8/xSijia3eTFgVfpcpztWLuP6FttGNfPLJhaZVP/euvujeNYar36OQ==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.4.tgz",
+      "integrity": "sha512-xTp7VZ5aXP5ZJrn15UtJUWlx6qXLnGtF6jNxHepdPHpMfz/aVPx+htHtgcAL2mDXJgKhpoo2e9/hVJsIeFbytQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/utils": "4.1.2",
+        "@vitest/utils": "4.1.4",
         "pathe": "^2.0.3"
       },
       "funding": {
@@ -2194,14 +2207,14 @@
       }
     },
     "node_modules/@vitest/snapshot": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.2.tgz",
-      "integrity": "sha512-g7yfUmxYS4mNxk31qbOYsSt2F4m1E02LFqO53Xpzg3zKMhLAPZAjjfyl9e6z7HrW6LvUdTwAQR3HHfLjpko16A==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.4.tgz",
+      "integrity": "sha512-MCjCFgaS8aZz+m5nTcEcgk/xhWv0rEH4Yl53PPlMXOZ1/Ka2VcZU6CJ+MgYCZbcJvzGhQRjVrGQNZqkGPttIKw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.2",
-        "@vitest/utils": "4.1.2",
+        "@vitest/pretty-format": "4.1.4",
+        "@vitest/utils": "4.1.4",
         "magic-string": "^0.30.21",
         "pathe": "^2.0.3"
       },
@@ -2210,9 +2223,9 @@
       }
     },
     "node_modules/@vitest/spy": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.2.tgz",
-      "integrity": "sha512-DU4fBnbVCJGNBwVA6xSToNXrkZNSiw59H8tcuUspVMsBDBST4nfvsPsEHDHGtWRRnqBERBQu7TrTKskmjqTXKA==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.4.tgz",
+      "integrity": "sha512-XxNdAsKW7C+FLydqFJLb5KhJtl3PGCMmYwFRfhvIgxJvLSXhhVI1zM8f1qD3Zg7RCjTSzDVyct6sghs9UEgBEQ==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -2220,13 +2233,13 @@
       }
     },
     "node_modules/@vitest/utils": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.2.tgz",
-      "integrity": "sha512-xw2/TiX82lQHA06cgbqRKFb5lCAy3axQ4H4SoUFhUsg+wztiet+co86IAMDtF6Vm1hc7J6j09oh/rgDn+JdKIQ==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.4.tgz",
+      "integrity": "sha512-13QMT+eysM5uVGa1rG4kegGYNp6cnQcsTc67ELFbhNLQO+vgsygtYJx2khvdt4gVQqSSpC/KT5FZZxUpP3Oatw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/pretty-format": "4.1.2",
+        "@vitest/pretty-format": "4.1.4",
         "convert-source-map": "^2.0.0",
         "tinyrainbow": "^3.1.0"
       },
@@ -2554,12 +2567,12 @@
       "license": "MIT"
     },
     "node_modules/commander": {
-      "version": "12.1.0",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz",
-      "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
       "license": "MIT",
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "node_modules/content-disposition": {
@@ -3115,22 +3128,6 @@
       "integrity": "sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==",
       "license": "Apache-2.0"
     },
-    "node_modules/foreground-child": {
-      "version": "3.3.1",
-      "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
-      "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==",
-      "license": "ISC",
-      "dependencies": {
-        "cross-spawn": "^7.0.6",
-        "signal-exit": "^4.0.1"
-      },
-      "engines": {
-        "node": ">=14"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -3251,24 +3248,17 @@
       "link": true
     },
     "node_modules/glob": {
-      "version": "11.1.0",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-11.1.0.tgz",
-      "integrity": "sha512-vuNwKSaKiqm7g0THUBu2x7ckSs3XJLXE+2ssL7/MfTGPLLcrJQ/4Uq1CjPTtO5cCIiRxqvN6Twy1qOwhL0Xjcw==",
-      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "version": "13.0.6",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
+      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
-        "foreground-child": "^3.3.1",
-        "jackspeak": "^4.1.1",
-        "minimatch": "^10.1.1",
-        "minipass": "^7.1.2",
-        "package-json-from-dist": "^1.0.0",
-        "path-scurry": "^2.0.0"
-      },
-      "bin": {
-        "glob": "dist/esm/bin.mjs"
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
       },
       "engines": {
-        "node": "20 || >=22"
+        "node": "18 || 20 || >=22"
       },
       "funding": {
         "url": "https://github.com/sponsors/isaacs"
@@ -3351,6 +3341,15 @@
         "graphology-types": ">=0.20.0"
       }
     },
+    "node_modules/graphology-indices/node_modules/mnemonist": {
+      "version": "0.39.8",
+      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.8.tgz",
+      "integrity": "sha512-vyWo2K3fjrUw8YeeZ1zF0fy6Mu59RHokURlld8ymdUPjMlD9EC9ov1/YPqTgqRvUN9nTr3Gqfz29LYAmu0PHPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "obliterator": "^2.0.1"
+      }
+    },
     "node_modules/graphology-types": {
       "version": "0.24.8",
       "resolved": "https://registry.npmjs.org/graphology-types/-/graphology-types-0.24.8.tgz",
@@ -3569,21 +3568,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/jackspeak": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-4.2.3.tgz",
-      "integrity": "sha512-ykkVRwrYvFm1nb2AJfKKYPr0emF6IiXDYUaFx4Zn9ZuIH7MrzEZ3sD5RlqGXNRpHtvUHJyOnCEFxOlNDtGo7wg==",
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "@isaacs/cliui": "^9.0.0"
-      },
-      "engines": {
-        "node": "20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/jose": {
       "version": "6.2.2",
       "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.2.tgz",
@@ -3910,9 +3894,9 @@
       "license": "Apache-2.0"
     },
     "node_modules/lru-cache": {
-      "version": "11.2.7",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.7.tgz",
-      "integrity": "sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==",
+      "version": "11.3.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
+      "integrity": "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==",
       "license": "BlueOak-1.0.0",
       "engines": {
         "node": "20 || >=22"
@@ -4083,12 +4067,12 @@
       }
     },
     "node_modules/mnemonist": {
-      "version": "0.39.8",
-      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.8.tgz",
-      "integrity": "sha512-vyWo2K3fjrUw8YeeZ1zF0fy6Mu59RHokURlld8ymdUPjMlD9EC9ov1/YPqTgqRvUN9nTr3Gqfz29LYAmu0PHPQ==",
+      "version": "0.40.3",
+      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.40.3.tgz",
+      "integrity": "sha512-Vjyr90sJ23CKKH/qPAgUKicw/v6pRoamxIEDFOF8uSgFME7DqPRpHgRTejWVjkdGg5dXj0/NyxZHZ9bcjH+2uQ==",
       "license": "MIT",
       "dependencies": {
-        "obliterator": "^2.0.1"
+        "obliterator": "^2.0.4"
       }
     },
     "node_modules/ms": {
@@ -4243,31 +4227,25 @@
       }
     },
     "node_modules/onnxruntime-web": {
-      "version": "1.22.0-dev.20250409-89f8206ba4",
-      "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.22.0-dev.20250409-89f8206ba4.tgz",
-      "integrity": "sha512-0uS76OPgH0hWCPrFKlL8kYVV7ckM7t/36HfbgoFw6Nd0CZVVbQC4PkrR8mBX8LtNUFZO25IQBqV2Hx2ho3FlbQ==",
+      "version": "1.26.0-dev.20260410-5e55544225",
+      "resolved": "https://registry.npmjs.org/onnxruntime-web/-/onnxruntime-web-1.26.0-dev.20260410-5e55544225.tgz",
+      "integrity": "sha512-hHd9n8DzIfGSAjM4Dvslesc8i6h9HEEcl8qt7X3LfhUxMgls6FBJ32j2xrDtJjKJFEehFeJmyB/pvad1I8KS8w==",
       "license": "MIT",
       "dependencies": {
         "flatbuffers": "^25.1.24",
         "guid-typescript": "^1.0.9",
         "long": "^5.2.3",
-        "onnxruntime-common": "1.22.0-dev.20250409-89f8206ba4",
+        "onnxruntime-common": "1.24.0-dev.20251116-b39e144322",
         "platform": "^1.3.6",
         "protobufjs": "^7.2.4"
       }
     },
     "node_modules/onnxruntime-web/node_modules/onnxruntime-common": {
-      "version": "1.22.0-dev.20250409-89f8206ba4",
-      "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.22.0-dev.20250409-89f8206ba4.tgz",
-      "integrity": "sha512-vDJMkfCfb0b1A836rgHj+ORuZf4B4+cc2bASQtpeoJLueuFc5DuYwjIZUBrSvx/fO5IrLjLz+oTrB3pcGlhovQ==",
+      "version": "1.24.0-dev.20251116-b39e144322",
+      "resolved": "https://registry.npmjs.org/onnxruntime-common/-/onnxruntime-common-1.24.0-dev.20251116-b39e144322.tgz",
+      "integrity": "sha512-BOoomdHYmNRL5r4iQ4bMvsl2t0/hzVQ3OM3PHD0gxeXu1PmggqBv3puZicEUVOA3AtHHYmqZtjMj9FOfGrATTw==",
       "license": "MIT"
     },
-    "node_modules/package-json-from-dist": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
-      "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==",
-      "license": "BlueOak-1.0.0"
-    },
     "node_modules/pandemonium": {
       "version": "2.4.1",
       "resolved": "https://registry.npmjs.org/pandemonium/-/pandemonium-2.4.1.tgz",
@@ -4277,6 +4255,15 @@
         "mnemonist": "^0.39.2"
       }
     },
+    "node_modules/pandemonium/node_modules/mnemonist": {
+      "version": "0.39.8",
+      "resolved": "https://registry.npmjs.org/mnemonist/-/mnemonist-0.39.8.tgz",
+      "integrity": "sha512-vyWo2K3fjrUw8YeeZ1zF0fy6Mu59RHokURlld8ymdUPjMlD9EC9ov1/YPqTgqRvUN9nTr3Gqfz29LYAmu0PHPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "obliterator": "^2.0.1"
+      }
+    },
     "node_modules/parseurl": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz",
@@ -4360,9 +4347,9 @@
       "license": "MIT"
     },
     "node_modules/postcss": {
-      "version": "8.5.8",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
-      "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==",
+      "version": "8.5.10",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz",
+      "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==",
       "dev": true,
       "funding": [
         {
@@ -4389,9 +4376,9 @@
       }
     },
     "node_modules/protobufjs": {
-      "version": "7.5.4",
-      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz",
-      "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==",
+      "version": "7.5.5",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz",
+      "integrity": "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg==",
       "hasInstallScript": true,
       "license": "BSD-3-Clause",
       "dependencies": {
@@ -4541,14 +4528,14 @@
       }
     },
     "node_modules/rolldown": {
-      "version": "1.0.0-rc.12",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.12.tgz",
-      "integrity": "sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==",
+      "version": "1.0.0-rc.15",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.15.tgz",
+      "integrity": "sha512-Ff31guA5zT6WjnGp0SXw76X6hzGRk/OQq2hE+1lcDe+lJdHSgnSX6nK3erbONHyCbpSj9a9E+uX/OvytZoWp2g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@oxc-project/types": "=0.122.0",
-        "@rolldown/pluginutils": "1.0.0-rc.12"
+        "@oxc-project/types": "=0.124.0",
+        "@rolldown/pluginutils": "1.0.0-rc.15"
       },
       "bin": {
         "rolldown": "bin/cli.mjs"
@@ -4557,21 +4544,21 @@
         "node": "^20.19.0 || >=22.12.0"
       },
       "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.0-rc.12",
-        "@rolldown/binding-darwin-arm64": "1.0.0-rc.12",
-        "@rolldown/binding-darwin-x64": "1.0.0-rc.12",
-        "@rolldown/binding-freebsd-x64": "1.0.0-rc.12",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.12",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.12",
-        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.12",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.12",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.12",
-        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.12",
-        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.12",
-        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.12",
-        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.12",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.12",
-        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.12"
+        "@rolldown/binding-android-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.15",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.15",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.15",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.15",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.15",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.15",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.15",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.15"
       }
     },
     "node_modules/router": {
@@ -4863,18 +4850,6 @@
       "dev": true,
       "license": "ISC"
     },
-    "node_modules/signal-exit": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
-      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
-      "license": "ISC",
-      "engines": {
-        "node": ">=14"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -4996,14 +4971,14 @@
       }
     },
     "node_modules/tinyglobby": {
-      "version": "0.2.15",
-      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
-      "integrity": "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==",
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "fdir": "^6.5.0",
-        "picomatch": "^4.0.3"
+        "picomatch": "^4.0.4"
       },
       "engines": {
         "node": ">=12.0.0"
@@ -5498,16 +5473,16 @@
       }
     },
     "node_modules/vite": {
-      "version": "8.0.3",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.3.tgz",
-      "integrity": "sha512-B9ifbFudT1TFhfltfaIPgjo9Z3mDynBTJSUYxTjOQruf/zHH+ezCQKcoqO+h7a9Pw9Nm/OtlXAiGT1axBgwqrQ==",
+      "version": "8.0.8",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.8.tgz",
+      "integrity": "sha512-dbU7/iLVa8KZALJyLOBOQ88nOXtNG8vxKuOT4I2mD+Ya70KPceF4IAmDsmU0h1Qsn5bPrvsY9HJstCRh3hG6Uw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
         "lightningcss": "^1.32.0",
         "picomatch": "^4.0.4",
         "postcss": "^8.5.8",
-        "rolldown": "1.0.0-rc.12",
+        "rolldown": "1.0.0-rc.15",
         "tinyglobby": "^0.2.15"
       },
       "bin": {
@@ -5525,7 +5500,7 @@
       "peerDependencies": {
         "@types/node": "^20.19.0 || >=22.12.0",
         "@vitejs/devtools": "^0.1.0",
-        "esbuild": "^0.27.0",
+        "esbuild": "^0.27.0 || ^0.28.0",
         "jiti": ">=1.21.0",
         "less": "^4.0.0",
         "sass": "^1.70.0",
@@ -5576,19 +5551,19 @@
       }
     },
     "node_modules/vitest": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.2.tgz",
-      "integrity": "sha512-xjR1dMTVHlFLh98JE3i/f/WePqJsah4A0FK9cc8Ehp9Udk0AZk6ccpIZhh1qJ/yxVWRZ+Q54ocnD8TXmkhspGg==",
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.4.tgz",
+      "integrity": "sha512-tFuJqTxKb8AvfyqMfnavXdzfy3h3sWZRWwfluGbkeR7n0HUev+FmNgZ8SDrRBTVrVCjgH5cA21qGbCffMNtWvg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@vitest/expect": "4.1.2",
-        "@vitest/mocker": "4.1.2",
-        "@vitest/pretty-format": "4.1.2",
-        "@vitest/runner": "4.1.2",
-        "@vitest/snapshot": "4.1.2",
-        "@vitest/spy": "4.1.2",
-        "@vitest/utils": "4.1.2",
+        "@vitest/expect": "4.1.4",
+        "@vitest/mocker": "4.1.4",
+        "@vitest/pretty-format": "4.1.4",
+        "@vitest/runner": "4.1.4",
+        "@vitest/snapshot": "4.1.4",
+        "@vitest/spy": "4.1.4",
+        "@vitest/utils": "4.1.4",
         "es-module-lexer": "^2.0.0",
         "expect-type": "^1.3.0",
         "magic-string": "^0.30.21",
@@ -5616,10 +5591,12 @@
         "@edge-runtime/vm": "*",
         "@opentelemetry/api": "^1.9.0",
         "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.2",
-        "@vitest/browser-preview": "4.1.2",
-        "@vitest/browser-webdriverio": "4.1.2",
-        "@vitest/ui": "4.1.2",
+        "@vitest/browser-playwright": "4.1.4",
+        "@vitest/browser-preview": "4.1.4",
+        "@vitest/browser-webdriverio": "4.1.4",
+        "@vitest/coverage-istanbul": "4.1.4",
+        "@vitest/coverage-v8": "4.1.4",
+        "@vitest/ui": "4.1.4",
         "happy-dom": "*",
         "jsdom": "*",
         "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
@@ -5643,6 +5620,12 @@
         "@vitest/browser-webdriverio": {
           "optional": true
         },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
         "@vitest/ui": {
           "optional": true
         },
diff --git a/gitnexus/package.json b/gitnexus/package.json
index ad075041d..d8f2c126a 100644
--- a/gitnexus/package.json
+++ b/gitnexus/package.json
@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "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",
@@ -51,22 +51,22 @@
     "prepack": "node scripts/build.js"
   },
   "dependencies": {
-    "@huggingface/transformers": "^3.0.0",
+    "@huggingface/transformers": "^4.1.0",
     "@ladybugdb/core": "^0.15.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@scarf/scarf": "^1.4.0",
     "cli-progress": "^3.12.0",
-    "commander": "^12.0.0",
+    "commander": "^14.0.3",
     "cors": "^2.8.5",
     "express": "^4.19.2",
-    "glob": "^11.0.0",
+    "glob": "^13.0.6",
     "graphology": "^0.25.4",
     "graphology-indices": "^0.17.0",
     "graphology-utils": "^2.3.0",
     "ignore": "^7.0.5",
     "js-yaml": "^4.1.1",
     "lru-cache": "^11.0.0",
-    "mnemonist": "^0.39.0",
+    "mnemonist": "^0.40.3",
     "onnxruntime-node": "^1.24.0",
     "pandemonium": "^2.4.0",
     "tree-sitter": "^0.21.1",
diff --git a/gitnexus/shadow-parity-dashboard/index.html b/gitnexus/shadow-parity-dashboard/index.html
new file mode 100644
index 000000000..104d7b026
--- /dev/null
+++ b/gitnexus/shadow-parity-dashboard/index.html
@@ -0,0 +1,291 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>GitNexus — Shadow Parity Dashboard</title>
+    <!--
+      Static dashboard for the RFC #909 shadow-mode parity report.
+
+      Reads `latest.json` from this directory and renders a per-language
+      parity table. Zero build step, zero runtime dependencies — a
+      single file that any browser or file:// context can open.
+
+      Usage:
+          # from repo root, after a shadow-mode run
+          cp .gitnexus/shadow-parity/latest.json gitnexus/shadow-parity-dashboard/
+          open gitnexus/shadow-parity-dashboard/index.html
+
+      CI artifact wiring (follow-up): the CI job publishes a snapshot
+      of this directory + latest.json as a downloadable bundle per run.
+    -->
+    <style>
+      :root {
+        color-scheme: light dark;
+        --fg: #1f2937;
+        --fg-muted: #6b7280;
+        --bg: #ffffff;
+        --bg-muted: #f9fafb;
+        --border: #e5e7eb;
+        --good: #16a34a;
+        --warn: #d97706;
+        --bad: #dc2626;
+        --primary-tag-legacy: #7c3aed;
+        --primary-tag-registry: #0ea5e9;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --fg: #e5e7eb;
+          --fg-muted: #9ca3af;
+          --bg: #111827;
+          --bg-muted: #1f2937;
+          --border: #374151;
+        }
+      }
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        background: var(--bg);
+        color: var(--fg);
+        font:
+          14px/1.45 system-ui,
+          -apple-system,
+          sans-serif;
+      }
+      main {
+        max-width: 1200px;
+        margin: 0 auto;
+        padding: 24px 16px;
+      }
+      h1 {
+        font-size: 20px;
+        margin: 0 0 4px;
+      }
+      .meta {
+        color: var(--fg-muted);
+        font-size: 12px;
+        margin-bottom: 20px;
+      }
+      .cards {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+        gap: 10px;
+        margin-bottom: 20px;
+      }
+      .card {
+        border: 1px solid var(--border);
+        border-radius: 6px;
+        padding: 10px 12px;
+        background: var(--bg-muted);
+      }
+      .card .k {
+        color: var(--fg-muted);
+        font-size: 11px;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+      }
+      .card .v {
+        font-size: 20px;
+        font-weight: 600;
+      }
+      table {
+        width: 100%;
+        border-collapse: collapse;
+        font-variant-numeric: tabular-nums;
+      }
+      th,
+      td {
+        padding: 6px 10px;
+        text-align: right;
+        border-bottom: 1px solid var(--border);
+      }
+      th:first-child,
+      td:first-child {
+        text-align: left;
+      }
+      thead th {
+        font-weight: 600;
+        color: var(--fg-muted);
+        font-size: 12px;
+        background: var(--bg-muted);
+      }
+      tbody tr:hover {
+        background: var(--bg-muted);
+      }
+      .parity {
+        font-weight: 600;
+      }
+      .parity.good {
+        color: var(--good);
+      }
+      .parity.warn {
+        color: var(--warn);
+      }
+      .parity.bad {
+        color: var(--bad);
+      }
+      .tag {
+        display: inline-block;
+        padding: 1px 6px;
+        border-radius: 10px;
+        font-size: 10px;
+        margin-left: 6px;
+        color: white;
+      }
+      .tag.legacy {
+        background: var(--primary-tag-legacy);
+      }
+      .tag.registry {
+        background: var(--primary-tag-registry);
+      }
+      .empty {
+        padding: 40px;
+        text-align: center;
+        color: var(--fg-muted);
+      }
+      code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        background: var(--bg-muted);
+        padding: 1px 4px;
+        border-radius: 3px;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Shadow Parity — RFC #909</h1>
+      <div class="meta" id="meta">loading <code>latest.json</code>…</div>
+      <div class="cards" id="cards"></div>
+      <table id="per-language">
+        <thead>
+          <tr>
+            <th>Language</th>
+            <th>Total</th>
+            <th>Agree</th>
+            <th>Only legacy</th>
+            <th>Only new</th>
+            <th>Disagree</th>
+            <th>Both empty</th>
+            <th>Parity</th>
+          </tr>
+        </thead>
+        <tbody></tbody>
+      </table>
+      <div id="empty" class="empty" style="display: none">
+        No records yet. Enable <code>GITNEXUS_SHADOW_MODE=1</code> and run ingestion to populate.
+      </div>
+    </main>
+    <script>
+      /* global fetch, document */
+      (async function () {
+        const tbody = document.querySelector('#per-language tbody');
+        const cards = document.getElementById('cards');
+        const meta = document.getElementById('meta');
+        const empty = document.getElementById('empty');
+        const table = document.getElementById('per-language');
+
+        let payload;
+        try {
+          const r = await fetch('./latest.json', { cache: 'no-store' });
+          if (!r.ok) throw new Error('HTTP ' + r.status);
+          payload = await r.json();
+        } catch (err) {
+          meta.textContent = 'Failed to load latest.json: ' + err.message;
+          table.style.display = 'none';
+          empty.style.display = 'block';
+          return;
+        }
+
+        const primary = payload.primaryByLanguage || {};
+        const report = payload.report || {};
+        const perLang = report.perLanguage || [];
+        const overall = report.overall || {};
+
+        meta.textContent =
+          'Run ' +
+          payload.runId +
+          ' — generated ' +
+          payload.generatedAt +
+          ' (schema v' +
+          payload.schemaVersion +
+          ')';
+
+        // Overall summary cards.
+        cards.innerHTML = '';
+        const overallParity = overall.parity !== undefined ? overall.parity : 0;
+        cards.appendChild(makeCard('Total calls', overall.totalCalls ?? 0));
+        cards.appendChild(makeCard('Both agree', overall.bothAgree ?? 0));
+        cards.appendChild(makeCard('Disagree', overall.bothDisagree ?? 0));
+        cards.appendChild(makeCard('Overall parity', formatPct(overallParity)));
+
+        if (!perLang.length) {
+          table.style.display = 'none';
+          empty.style.display = 'block';
+          return;
+        }
+
+        for (const row of perLang) {
+          const tr = document.createElement('tr');
+          const primaryTag = primary[row.language];
+          const tag = primaryTag
+            ? '<span class="tag ' + primaryTag + '">primary: ' + primaryTag + '</span>'
+            : '';
+          const parityClass = parityClassFor(row.parity);
+          tr.innerHTML =
+            '<td>' +
+            escape(row.language) +
+            tag +
+            '</td>' +
+            '<td>' +
+            row.totalCalls +
+            '</td>' +
+            '<td>' +
+            row.bothAgree +
+            '</td>' +
+            '<td>' +
+            row.onlyLegacy +
+            '</td>' +
+            '<td>' +
+            row.onlyNew +
+            '</td>' +
+            '<td>' +
+            row.bothDisagree +
+            '</td>' +
+            '<td>' +
+            row.bothEmpty +
+            '</td>' +
+            '<td class="parity ' +
+            parityClass +
+            '">' +
+            formatPct(row.parity) +
+            '</td>';
+          tbody.appendChild(tr);
+        }
+
+        function makeCard(k, v) {
+          const div = document.createElement('div');
+          div.className = 'card';
+          div.innerHTML =
+            '<div class="k">' + escape(k) + '</div><div class="v">' + escape(String(v)) + '</div>';
+          return div;
+        }
+        function formatPct(x) {
+          if (typeof x !== 'number' || !isFinite(x)) return '—';
+          return (x * 100).toFixed(1) + '%';
+        }
+        function parityClassFor(x) {
+          if (typeof x !== 'number') return '';
+          if (x >= 0.95) return 'good';
+          if (x >= 0.8) return 'warn';
+          return 'bad';
+        }
+        function escape(s) {
+          return String(s).replace(/[&<>"']/g, function (c) {
+            return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+          });
+        }
+      })();
+    </script>
+  </body>
+</html>
diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts
index fd7e3cc29..984a16f7b 100644
--- a/gitnexus/src/cli/ai-context.ts
+++ b/gitnexus/src/cli/ai-context.ts
@@ -101,19 +101,6 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
 - When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
 
-## When Debugging
-
-1. \`gitnexus_query({query: "<error or symptom>"})\` — find execution flows related to the issue
-2. \`gitnexus_context({name: "<suspect function>"})\` — see all callers, callees, and process participation
-3. \`READ gitnexus://repo/${projectName}/process/{processName}\` — trace the full execution flow step by step
-4. For regressions: \`gitnexus_detect_changes({scope: "compare", base_ref: "main"})\` — see what your branch changed
-
-## When Refactoring
-
-- **Renaming**: MUST use \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with \`dry_run: false\`.
-- **Extracting/Splitting**: MUST run \`gitnexus_context({name: "target"})\` to see all incoming/outgoing refs, then \`gitnexus_impact({target: "target", direction: "upstream"})\` to find all external callers before moving code.
-- After any refactor: run \`gitnexus_detect_changes({scope: "all"})\` to verify only expected files changed.
-
 ## Never Do
 
 - NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
@@ -121,25 +108,6 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 - NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
 - NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
 
-## Tools Quick Reference
-
-| Tool | When to use | Command |
-|------|-------------|---------|
-| \`query\` | Find code by concept | \`gitnexus_query({query: "auth validation"})\` |
-| \`context\` | 360-degree view of one symbol | \`gitnexus_context({name: "validateUser"})\` |
-| \`impact\` | Blast radius before editing | \`gitnexus_impact({target: "X", direction: "upstream"})\` |
-| \`detect_changes\` | Pre-commit scope check | \`gitnexus_detect_changes({scope: "staged"})\` |
-| \`rename\` | Safe multi-file rename | \`gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})\` |
-| \`cypher\` | Custom graph queries | \`gitnexus_cypher({query: "MATCH ..."})\` |
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| d=1 | WILL BREAK — direct callers/importers | MUST update these |
-| d=2 | LIKELY AFFECTED — indirect deps | Should test |
-| d=3 | MAY NEED TESTING — transitive | Test if critical path |
-
 ## Resources
 
 | Resource | Use for |
@@ -149,32 +117,6 @@ This project is indexed by GitNexus as **${projectName}**${noStats ? '' : ` (${s
 | \`gitnexus://repo/${projectName}/processes\` | All execution flows |
 | \`gitnexus://repo/${projectName}/process/{name}\` | Step-by-step execution trace |
 
-## Self-Check Before Finishing
-
-Before completing any code modification task, verify:
-1. \`gitnexus_impact\` was run for all modified symbols
-2. No HIGH/CRITICAL risk warnings were ignored
-3. \`gitnexus_detect_changes()\` confirms changes match expected scope
-4. All d=1 (WILL BREAK) dependents were updated
-
-## Keeping the Index Fresh
-
-After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
-
-\`\`\`bash
-npx gitnexus analyze
-\`\`\`
-
-If the index previously included embeddings, preserve them by adding \`--embeddings\`:
-
-\`\`\`bash
-npx gitnexus analyze --embeddings
-\`\`\`
-
-To check whether embeddings exist, inspect \`.gitnexus/meta.json\` — the \`stats.embeddings\` field shows the count (0 means no embeddings). **Running analyze without \`--embeddings\` will delete any previously generated embeddings.**
-
-> Claude Code users: A PostToolUse hook handles this automatically after \`git commit\` and \`git merge\`.
-
 ${
   groupNames && groupNames.length > 0
     ? `## Cross-Repo Groups
diff --git a/gitnexus/src/cli/analyze.ts b/gitnexus/src/cli/analyze.ts
index 26d1ae8c6..46cedc434 100644
--- a/gitnexus/src/cli/analyze.ts
+++ b/gitnexus/src/cli/analyze.ts
@@ -13,7 +13,11 @@ import { execFileSync } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
-import { getStoragePaths, getGlobalRegistryPath } from '../storage/repo-manager.js';
+import {
+  getStoragePaths,
+  getGlobalRegistryPath,
+  RegistryNameCollisionError,
+} from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir } from '../storage/git.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import fs from 'fs/promises';
@@ -59,6 +63,21 @@ export interface AnalyzeOptions {
   noStats?: boolean;
   /** Index the folder even when no .git directory is present. */
   skipGit?: boolean;
+  /**
+   * Override the default basename-derived registry `name` with a
+   * user-supplied alias (#829). Disambiguates repos whose paths share a
+   * basename. Persisted — subsequent re-analyses of the same path without
+   * `--name` preserve the alias.
+   */
+  name?: string;
+  /**
+   * Allow registration even when another path already uses the same
+   * `--name` alias (#829). Intentionally a distinct flag from `--force`
+   * because the user may want to coexist under the same name WITHOUT
+   * paying the cost of a pipeline re-index. Maps to registerRepo's
+   * `allowDuplicateName` option end-to-end.
+   */
+  allowDuplicateName?: boolean;
 }
 
 export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
@@ -147,9 +166,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   const origLog = console.log.bind(console);
   const origWarn = console.warn.bind(console);
   const origError = console.error.bind(console);
+  let barCurrentValue = 0;
   const barLog = (...args: any[]) => {
     process.stdout.write('\x1b[2K\r');
     origLog(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' '));
+    bar.update(barCurrentValue);
   };
   console.log = barLog;
   console.warn = barLog;
@@ -160,6 +181,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   let phaseStart = Date.now();
 
   const updateBar = (value: number, phaseLabel: string) => {
+    barCurrentValue = value;
     if (phaseLabel !== lastPhaseLabel) {
       lastPhaseLabel = phaseLabel;
       phaseStart = Date.now();
@@ -183,11 +205,20 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     const result = await runFullAnalysis(
       repoPath,
       {
+        // Pipeline re-index — OR'd with --skills because skill generation
+        // needs a fresh pipelineResult. Has no bearing on the registry
+        // collision guard (see allowDuplicateName below).
         force: options?.force || options?.skills,
         embeddings: options?.embeddings,
         skipGit: options?.skipGit,
         skipAgentsMd: options?.skipAgentsMd,
         noStats: options?.noStats,
+        registryName: options?.name,
+        // Registry-collision bypass — its own CLI flag, intentionally NOT
+        // overloading --force. A user who hits the collision guard should
+        // be able to accept the duplicate name without also paying the
+        // cost of a full pipeline re-index. See #829 review round 2.
+        allowDuplicateName: options?.allowDuplicateName,
       },
       {
         onProgress: (_phase, percent, message) => {
@@ -295,6 +326,22 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     bar.stop();
 
     const msg = err.message || String(err);
+
+    // Registry name-collision from --name (#829) — surface as an
+    // actionable error rather than a generic stack-trace.
+    if (err instanceof RegistryNameCollisionError) {
+      console.error(`\n  Registry name collision:\n`);
+      console.error(`    "${err.registryName}" is already used by "${err.existingPath}".\n`);
+      console.error(`  Options:`);
+      console.error(`    • Pick a different alias:  gitnexus analyze --name <alias>`);
+      console.error(
+        `    • Allow the duplicate:     gitnexus analyze --allow-duplicate-name  (leaves "-r ${err.registryName}" ambiguous)`,
+      );
+      console.error('');
+      process.exitCode = 1;
+      return;
+    }
+
     console.error(`\n  Analysis failed: ${msg}\n`);
 
     // Provide helpful guidance for known failure modes
diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts
index 02581ae47..dca5983e0 100644
--- a/gitnexus/src/cli/index.ts
+++ b/gitnexus/src/cli/index.ts
@@ -28,6 +28,16 @@ program
   .option('--skip-agents-md', 'Skip updating the gitnexus section in AGENTS.md and CLAUDE.md')
   .option('--no-stats', 'Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md')
   .option('--skip-git', 'Index a folder without requiring a .git directory')
+  .option(
+    '--name <alias>',
+    'Register this repo under a custom name in ~/.gitnexus/registry.json ' +
+      '(disambiguates repos whose paths share a basename, e.g. two different .../app folders)',
+  )
+  .option(
+    '--allow-duplicate-name',
+    'Register this repo even if another path already uses the same --name alias. ' +
+      'Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
+  )
   .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
   .addHelpText(
     'after',
diff --git a/gitnexus/src/cli/list.ts b/gitnexus/src/cli/list.ts
index 722c8ad59..5da9a86f0 100644
--- a/gitnexus/src/cli/list.ts
+++ b/gitnexus/src/cli/list.ts
@@ -17,12 +17,23 @@ export const listCommand = async () => {
 
   console.log(`\n  Indexed Repositories (${entries.length})\n`);
 
+  // Count occurrences of each name so colliding entries can be
+  // disambiguated in the header (#829). Unique-name entries render
+  // identically to pre-#829 output; only collisions gain a suffix.
+  const nameCounts = new Map<string, number>();
+  for (const e of entries) {
+    const key = e.name.toLowerCase();
+    nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+  }
+
   for (const entry of entries) {
     const indexedDate = new Date(entry.indexedAt).toLocaleString();
     const stats = entry.stats || {};
     const commitShort = entry.lastCommit?.slice(0, 7) || 'unknown';
+    const hasCollision = (nameCounts.get(entry.name.toLowerCase()) ?? 0) > 1;
+    const header = hasCollision ? `${entry.name}  (${entry.path})` : entry.name;
 
-    console.log(`  ${entry.name}`);
+    console.log(`  ${header}`);
     console.log(`    Path:    ${entry.path}`);
     console.log(`    Indexed: ${indexedDate}`);
     console.log(`    Commit:  ${commitShort}`);
diff --git a/gitnexus/src/core/embeddings/ast-utils.ts b/gitnexus/src/core/embeddings/ast-utils.ts
new file mode 100644
index 000000000..fb51ac052
--- /dev/null
+++ b/gitnexus/src/core/embeddings/ast-utils.ts
@@ -0,0 +1,112 @@
+/**
+ * Shared AST utilities for the embedding pipeline.
+ * Centralizes parser caching and tree-sitter node lookups
+ * used by both chunker.ts and structural-extractor.ts.
+ */
+
+import { getLanguageFromFilename } from 'gitnexus-shared';
+import {
+  createParserForLanguage,
+  isLanguageAvailable,
+  resolveLanguageKey,
+} from '../tree-sitter/parser-loader.js';
+
+const parserCache = new Map<string, any>();
+
+/**
+ * Ensure parser is initialized and language is loaded, then parse content.
+ * Returns null if language is unavailable or parsing fails.
+ */
+export const ensureAndParse = async (content: string, filePath: string): Promise<any | null> => {
+  const language = getLanguageFromFilename(filePath);
+  if (!language) return null;
+  if (!isLanguageAvailable(language)) return null;
+
+  const parserKey = resolveLanguageKey(language, filePath);
+  let parserInstance = parserCache.get(parserKey);
+  if (!parserInstance) {
+    parserInstance = await createParserForLanguage(language, filePath);
+    parserCache.set(parserKey, parserInstance);
+  }
+
+  return parserInstance.parse(content);
+};
+
+const FUNCTION_LIKE_TYPES = new Set([
+  'function_declaration',
+  'function_definition',
+  'method_declaration',
+  'method_definition',
+  'function_item',
+  'function_signature_item',
+  'arrow_function',
+  'function_expression',
+  'generator_function_declaration',
+  'generator_function',
+  'async_function_declaration',
+  'async_arrow_function',
+  'constructor_declaration',
+  'constructor_definition',
+  'compact_constructor_declaration',
+  'short_function_declaration',
+  'proc_declaration',
+  'func_literal',
+  'local_function_statement',
+  'anonymous_function',
+  'lambda_literal',
+  'init_declaration',
+  'deinit_declaration',
+]);
+
+/**
+ * Find the first function/method-like declaration in a snippet AST.
+ * Used by the chunker when parsing node.content where absolute line
+ * numbers don't apply.
+ */
+export const findFunctionNode = (root: any): any | null => {
+  if (FUNCTION_LIKE_TYPES.has(root.type)) return root;
+
+  for (let i = 0; i < root.namedChildCount; i++) {
+    const child = root.namedChild(i);
+    if (!child) continue;
+    if (FUNCTION_LIKE_TYPES.has(child.type)) return child;
+    const found = findFunctionNode(child);
+    if (found) return found;
+  }
+
+  return null;
+};
+
+/**
+ * Find the first class/struct/interface/enum-like declaration in an AST.
+ * Used when parsing node.content (a snippet, not a full file) where
+ * absolute line numbers don't apply.
+ */
+export const findDeclarationNode = (root: any): any | null => {
+  const CLASS_LIKE_TYPES = new Set([
+    'class_declaration',
+    'class_definition',
+    'struct_declaration',
+    'struct_item',
+    'interface_declaration',
+    'interface_definition',
+    'enum_declaration',
+    'enum_item',
+    'type_declaration', // Go: type X struct
+    'declaration', // Go: type X struct
+    'object_declaration', // Kotlin: object
+    'impl_item', // Rust: impl
+  ]);
+
+  if (CLASS_LIKE_TYPES.has(root.type)) return root;
+
+  for (let i = 0; i < root.namedChildCount; i++) {
+    const child = root.namedChild(i);
+    if (!child) continue;
+    if (CLASS_LIKE_TYPES.has(child.type)) return child;
+    const found = findDeclarationNode(child);
+    if (found) return found;
+  }
+
+  return null;
+};
diff --git a/gitnexus/src/core/embeddings/character-chunk.ts b/gitnexus/src/core/embeddings/character-chunk.ts
new file mode 100644
index 000000000..e4f6f949c
--- /dev/null
+++ b/gitnexus/src/core/embeddings/character-chunk.ts
@@ -0,0 +1,63 @@
+/**
+ * Character-based sliding window chunking (pure, no tree-sitter dependency)
+ */
+
+import { buildLineIndex, resolveChunkLines } from './line-index.js';
+
+export interface Chunk {
+  text: string;
+  chunkIndex: number;
+  startOffset: number;
+  endOffset: number;
+  startLine: number;
+  endLine: number;
+}
+
+export const characterChunk = (
+  content: string,
+  startLine: number,
+  endLine: number,
+  chunkSize: number = 1200,
+  overlap: number = 120,
+): Chunk[] => {
+  if (content.length <= chunkSize) {
+    return [
+      {
+        text: content,
+        chunkIndex: 0,
+        startOffset: 0,
+        endOffset: content.length,
+        startLine,
+        endLine,
+      },
+    ];
+  }
+
+  const chunks: Chunk[] = [];
+  let offset = 0;
+  const lineOffsets = buildLineIndex(content);
+
+  while (offset < content.length) {
+    const end = Math.min(offset + chunkSize, content.length);
+    const chunkText = content.slice(offset, end);
+    const lineRange = resolveChunkLines(lineOffsets, offset, end, startLine);
+
+    chunks.push({
+      text: chunkText,
+      chunkIndex: chunks.length,
+      startOffset: offset,
+      endOffset: end,
+      startLine: lineRange.startLine,
+      endLine: lineRange.endLine,
+    });
+
+    offset = end - overlap;
+    if (offset >= content.length) break;
+    if (end >= content.length) break;
+    if (offset <= (chunks.length > 1 ? end - chunkSize : 0)) {
+      offset = end;
+    }
+  }
+
+  return chunks;
+};
diff --git a/gitnexus/src/core/embeddings/chunker.ts b/gitnexus/src/core/embeddings/chunker.ts
new file mode 100644
index 000000000..114a5f68c
--- /dev/null
+++ b/gitnexus/src/core/embeddings/chunker.ts
@@ -0,0 +1,363 @@
+/**
+ * Chunker Module
+ *
+ * Splits code nodes into chunks for embedding.
+ * - Function/Method: AST-aware chunking by statement boundaries
+ * - Other types: character-based sliding window fallback
+ * - Short content (≤ chunkSize): no chunking
+ */
+
+export { type Chunk, characterChunk } from './character-chunk.js';
+
+import { characterChunk } from './character-chunk.js';
+import type { Chunk } from './character-chunk.js';
+import { ensureAndParse, findDeclarationNode, findFunctionNode } from './ast-utils.js';
+import { buildLineIndex, resolveChunkLines } from './line-index.js';
+
+/**
+ * Main chunkNode function: dispatches by label
+ */
+export const chunkNode = async (
+  label: string,
+  content: string,
+  filePath: string,
+  startLine: number,
+  endLine: number,
+  chunkSize: number = 1200,
+  overlap: number = 120,
+): Promise<Chunk[]> => {
+  // Content fits in one chunk — no splitting needed
+  if (content.length <= chunkSize) {
+    return [
+      {
+        text: content,
+        chunkIndex: 0,
+        startOffset: 0,
+        endOffset: content.length,
+        startLine,
+        endLine,
+      },
+    ];
+  }
+
+  // Only function-like labels get AST chunking
+  if (label === 'Function' || label === 'Method' || label === 'Constructor') {
+    try {
+      const astChunks = await astChunk(content, filePath, startLine, endLine, chunkSize, overlap);
+      if (astChunks.length > 0) return astChunks;
+    } catch {
+      // AST parsing failed — fall through to character fallback
+    }
+  }
+
+  if (label === 'Class' || label === 'Interface') {
+    try {
+      const declarationChunks = await declarationChunk(
+        label,
+        content,
+        filePath,
+        startLine,
+        endLine,
+        chunkSize,
+        overlap,
+      );
+      if (declarationChunks.length > 0) return declarationChunks;
+    } catch {
+      // AST parsing failed — fall through to character fallback
+    }
+  }
+
+  // Character-based fallback for everything else
+  return characterChunk(content, startLine, endLine, chunkSize, overlap);
+};
+
+/**
+ * AST-based chunking for Function/Method
+ * Parse snippet content, locate the function declaration node,
+ * split body by statement boundaries.
+ */
+const astChunk = async (
+  content: string,
+  filePath: string,
+  startLine: number,
+  endLine: number,
+  chunkSize: number,
+  overlap: number,
+): Promise<Chunk[]> => {
+  const tree = await ensureAndParse(content, filePath);
+  if (!tree) return [];
+
+  const root = tree.rootNode;
+  const lineOffsets = buildLineIndex(content);
+
+  // Find the function/method declaration in the snippet AST.
+  // tree-sitter parses node.content (a snippet), so rows are relative (0-based).
+  const targetNode = findFunctionNode(root);
+  if (!targetNode) return [];
+
+  // Get the body (statements) via childForFieldName('body')
+  const bodyNode = targetNode.childForFieldName('body');
+  if (!bodyNode) return [];
+
+  // Extract individual statements
+  const statements: Array<{ startIndex: number; endIndex: number }> = [];
+  for (let i = 0; i < bodyNode.namedChildCount; i++) {
+    const child = bodyNode.namedChild(i);
+    if (!child) continue;
+    statements.push({
+      startIndex: child.startIndex,
+      endIndex: child.endIndex,
+    });
+  }
+
+  if (statements.length === 0) return [];
+
+  return chunkByUnits(
+    content,
+    lineOffsets,
+    startLine,
+    chunkSize,
+    overlap,
+    statements,
+    targetNode.startIndex,
+    targetNode.endIndex,
+    true,
+    true,
+  );
+};
+
+const DECLARATION_BODY_NODE_TYPES = new Set([
+  'class_body',
+  'object_type',
+  'declaration_list',
+  'interface_body',
+]);
+
+const FIELD_LIKE_MEMBER_TYPES = new Set([
+  'field_definition',
+  'public_field_definition',
+  'property_definition',
+  'property_signature',
+  'variable_declarator',
+  'lexical_declaration',
+  'pair',
+  'enum_assignment',
+]);
+
+const declarationChunk = async (
+  label: 'Class' | 'Interface',
+  content: string,
+  filePath: string,
+  startLine: number,
+  endLine: number,
+  chunkSize: number,
+  overlap: number,
+): Promise<Chunk[]> => {
+  const tree = await ensureAndParse(content, filePath);
+  if (!tree) return [];
+
+  const targetNode = findDeclarationNode(tree.rootNode);
+  if (!targetNode) return [];
+
+  const bodyNode = getDeclarationBodyNode(targetNode);
+  if (!bodyNode) return [];
+
+  const members = collectDeclarationUnits(bodyNode, label);
+  if (members.length === 0) return [];
+
+  return chunkByUnits(
+    content,
+    buildLineIndex(content),
+    startLine,
+    chunkSize,
+    overlap,
+    members,
+    targetNode.startIndex,
+    targetNode.endIndex,
+    false,
+    false,
+  );
+};
+
+const buildChunk = (
+  content: string,
+  lineOffsets: Int32Array,
+  chunkIndex: number,
+  startOffset: number,
+  endOffset: number,
+  baseStartLine: number,
+): Chunk => {
+  const lineRange = resolveChunkLines(lineOffsets, startOffset, endOffset, baseStartLine);
+  return {
+    text: content.slice(startOffset, endOffset),
+    chunkIndex,
+    startOffset,
+    endOffset,
+    startLine: lineRange.startLine,
+    endLine: lineRange.endLine,
+  };
+};
+
+const chunkByUnits = (
+  content: string,
+  lineOffsets: Int32Array,
+  baseStartLine: number,
+  chunkSize: number,
+  overlap: number,
+  units: Array<{ startIndex: number; endIndex: number }>,
+  containerStartOffset: number,
+  containerEndOffset: number,
+  includeContainerPrefixOnFirstChunk: boolean,
+  includeContainerSuffixOnLastChunk: boolean,
+): Chunk[] => {
+  const chunks: Chunk[] = [];
+  let chunkStartUnitIdx = 0;
+
+  while (chunkStartUnitIdx < units.length) {
+    const chunkStartOffset =
+      chunkStartUnitIdx === 0 && includeContainerPrefixOnFirstChunk
+        ? containerStartOffset
+        : units[chunkStartUnitIdx].startIndex;
+
+    let chunkEndUnitIdx = chunkStartUnitIdx;
+    let candidateEndOffset =
+      chunkEndUnitIdx === units.length - 1 && includeContainerSuffixOnLastChunk
+        ? containerEndOffset
+        : units[chunkEndUnitIdx].endIndex;
+
+    while (chunkEndUnitIdx + 1 < units.length) {
+      const nextEndOffset =
+        chunkEndUnitIdx + 1 === units.length - 1 && includeContainerSuffixOnLastChunk
+          ? containerEndOffset
+          : units[chunkEndUnitIdx + 1].endIndex;
+      if (nextEndOffset - chunkStartOffset > chunkSize) break;
+      chunkEndUnitIdx += 1;
+      candidateEndOffset = nextEndOffset;
+    }
+
+    if (candidateEndOffset - chunkStartOffset > chunkSize) {
+      const oversizedUnit = units[chunkStartUnitIdx];
+      const oversizedLineRange = resolveChunkLines(
+        lineOffsets,
+        oversizedUnit.startIndex,
+        oversizedUnit.endIndex,
+        baseStartLine,
+      );
+      const oversizedChunks = characterChunk(
+        content.slice(oversizedUnit.startIndex, oversizedUnit.endIndex),
+        oversizedLineRange.startLine,
+        oversizedLineRange.endLine,
+        chunkSize,
+        overlap,
+      ).map((chunk, offsetIdx) => ({
+        ...chunk,
+        chunkIndex: chunks.length + offsetIdx,
+        startOffset: chunk.startOffset + oversizedUnit.startIndex,
+        endOffset: chunk.endOffset + oversizedUnit.startIndex,
+      }));
+      chunks.push(...oversizedChunks);
+      chunkStartUnitIdx += 1;
+      continue;
+    }
+
+    chunks.push(
+      buildChunk(
+        content,
+        lineOffsets,
+        chunks.length,
+        chunkStartOffset,
+        candidateEndOffset,
+        baseStartLine,
+      ),
+    );
+
+    if (chunkEndUnitIdx === units.length - 1) {
+      break;
+    }
+
+    const nextChunkStartUnitIdx = findOverlapStartIndex(
+      units,
+      chunkStartUnitIdx,
+      chunkEndUnitIdx,
+      overlap,
+    );
+    if (nextChunkStartUnitIdx <= chunkStartUnitIdx) {
+      chunkStartUnitIdx = chunkEndUnitIdx + 1;
+    } else {
+      chunkStartUnitIdx = nextChunkStartUnitIdx;
+    }
+  }
+
+  return chunks;
+};
+
+const findOverlapStartIndex = (
+  statements: Array<{ startIndex: number; endIndex: number }>,
+  chunkStartStmtIdx: number,
+  chunkEndStmtIdx: number,
+  overlapSize: number,
+): number => {
+  if (overlapSize <= 0) return chunkEndStmtIdx + 1;
+
+  let overlapStartIdx = chunkEndStmtIdx;
+  while (overlapStartIdx > chunkStartStmtIdx) {
+    const overlapLength =
+      statements[chunkEndStmtIdx].endIndex - statements[overlapStartIdx - 1].startIndex;
+    if (overlapLength > overlapSize) break;
+    overlapStartIdx -= 1;
+  }
+
+  return overlapStartIdx;
+};
+
+const getDeclarationBodyNode = (node: any): any | null => {
+  const bodyNode = node.childForFieldName?.('body');
+  if (bodyNode) return bodyNode;
+
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child) continue;
+    if (DECLARATION_BODY_NODE_TYPES.has(child.type)) return child;
+  }
+
+  return null;
+};
+
+const collectDeclarationUnits = (
+  bodyNode: any,
+  label: 'Class' | 'Interface',
+): Array<{ startIndex: number; endIndex: number }> => {
+  const members: Array<{ startIndex: number; endIndex: number; groupable: boolean }> = [];
+
+  for (let i = 0; i < bodyNode.namedChildCount; i++) {
+    const child = bodyNode.namedChild(i);
+    if (!child) continue;
+    members.push({
+      startIndex: child.startIndex,
+      endIndex: child.endIndex,
+      groupable: label === 'Class' && FIELD_LIKE_MEMBER_TYPES.has(child.type),
+    });
+  }
+
+  if (members.length === 0) return [];
+
+  const grouped: Array<{ startIndex: number; endIndex: number }> = [];
+  let current = members[0];
+
+  for (let i = 1; i < members.length; i++) {
+    const next = members[i];
+    if (current.groupable && next.groupable) {
+      current = {
+        startIndex: current.startIndex,
+        endIndex: next.endIndex,
+        groupable: true,
+      };
+      continue;
+    }
+    grouped.push({ startIndex: current.startIndex, endIndex: current.endIndex });
+    current = next;
+  }
+
+  grouped.push({ startIndex: current.startIndex, endIndex: current.endIndex });
+  return grouped;
+};
diff --git a/gitnexus/src/core/embeddings/embedding-pipeline.ts b/gitnexus/src/core/embeddings/embedding-pipeline.ts
index cb28ca945..302903f8b 100644
--- a/gitnexus/src/core/embeddings/embedding-pipeline.ts
+++ b/gitnexus/src/core/embeddings/embedding-pipeline.ts
@@ -3,9 +3,9 @@
  *
  * Orchestrates the background embedding process:
  * 1. Query embeddable nodes from LadybugDB
- * 2. Generate text representations
- * 3. Batch embed using transformers.js
- * 4. Update LadybugDB with embeddings
+ * 2. Generate text representations with enriched metadata
+ * 3. Chunk long nodes, batch embed
+ * 4. Update LadybugDB with chunk-aware embeddings
  * 5. Create vector index for semantic search
  */
 
@@ -17,20 +17,28 @@ import {
   embeddingToArray,
   isEmbedderReady,
 } from './embedder.js';
-import { generateEmbeddingText, generateBatchEmbeddingTexts } from './text-generator.js';
+import { generateEmbeddingText } from './text-generator.js';
+import { chunkNode, characterChunk } from './chunker.js';
+import { extractStructuralNames } from './structural-extractor.js';
 import {
   type EmbeddingProgress,
   type EmbeddingConfig,
   type EmbeddableNode,
   type SemanticSearchResult,
   type ModelProgress,
+  type EmbeddingContext,
   DEFAULT_EMBEDDING_CONFIG,
   EMBEDDABLE_LABELS,
+  isShortLabel,
+  LABELS_WITH_EXPORTED,
+  STRUCTURAL_LABELS,
+  collectBestChunks,
 } from './types.js';
 import {
   EMBEDDING_TABLE_NAME,
   EMBEDDING_INDEX_NAME,
   CREATE_VECTOR_INDEX_QUERY,
+  STALE_HASH_SENTINEL,
 } from '../lbug/schema.js';
 import { loadVectorExtension } from '../lbug/lbug-adapter.js';
 
@@ -46,7 +54,14 @@ export const contentHashForNode = (
   node: EmbeddableNode,
   config: Partial<EmbeddingConfig> = {},
 ): string => {
-  const text = generateEmbeddingText(node, config);
+  // Hash must be deterministic across runs, so exclude methodNames/fieldNames
+  // which are populated during the batch loop via AST extraction.
+  // Using only node.content ensures the hash stays stable.
+  const text = generateEmbeddingText(
+    { ...node, methodNames: undefined, fieldNames: undefined },
+    node.content,
+    config,
+  );
   return createHash('sha1').update(text).digest('hex');
 };
 
@@ -57,37 +72,50 @@ export type EmbeddingProgressCallback = (progress: EmbeddingProgress) => void;
 
 /**
  * Query all embeddable nodes from LadybugDB
- * Uses table-specific queries (File has different schema than code elements)
+ * Uses table-specific queries for different label types
  */
 const queryEmbeddableNodes = async (
   executeQuery: (cypher: string) => Promise<any[]>,
 ): Promise<EmbeddableNode[]> => {
   const allNodes: EmbeddableNode[] = [];
 
-  // Query each embeddable table with table-specific columns
   for (const label of EMBEDDABLE_LABELS) {
     try {
       let query: string;
 
-      if (label === 'File') {
-        // File nodes don't have startLine/endLine
+      if (label === 'Method') {
+        // Method has parameterCount and returnType
         query = `
-          MATCH (n:File)
-          RETURN n.id AS id, n.name AS name, 'File' AS label, 
-                 n.filePath AS filePath, n.content AS content
+          MATCH (n:Method)
+          RETURN n.id AS id, n.name AS name, 'Method' AS label,
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.isExported AS isExported, n.description AS description,
+                 n.parameterCount AS parameterCount, n.returnType AS returnType
+        `;
+      } else if (LABELS_WITH_EXPORTED.has(label)) {
+        // Function, Class, Interface have isExported and description
+        query = `
+          MATCH (n:\`${label}\`)
+          RETURN n.id AS id, n.name AS name, '${label}' AS label,
+                 n.filePath AS filePath, n.content AS content,
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.isExported AS isExported, n.description AS description
         `;
       } else {
-        // Code elements have startLine/endLine
+        // Multi-language tables (Struct, Enum, etc.) — have description but no isExported
         query = `
-          MATCH (n:${label})
-          RETURN n.id AS id, n.name AS name, '${label}' AS label, 
+          MATCH (n:\`${label}\`)
+          RETURN n.id AS id, n.name AS name, '${label}' AS label,
                  n.filePath AS filePath, n.content AS content,
-                 n.startLine AS startLine, n.endLine AS endLine
+                 n.startLine AS startLine, n.endLine AS endLine,
+                 n.description AS description
         `;
       }
 
       const rows = await executeQuery(query);
       for (const row of rows) {
+        const hasExportedColumn = label === 'Method' || LABELS_WITH_EXPORTED.has(label);
         allNodes.push({
           id: row.id ?? row[0],
           name: row.name ?? row[1],
@@ -96,10 +124,17 @@ const queryEmbeddableNodes = async (
           content: row.content ?? row[4] ?? '',
           startLine: row.startLine ?? row[5],
           endLine: row.endLine ?? row[6],
+          isExported: hasExportedColumn ? (row.isExported ?? row[7]) : undefined,
+          description: row.description ?? (hasExportedColumn ? row[8] : row[7]),
+          ...(label === 'Method'
+            ? {
+                parameterCount: row.parameterCount ?? row[9],
+                returnType: row.returnType ?? row[10],
+              }
+            : {}),
         });
       }
     } catch (error) {
-      // Table might not exist or be empty, continue
       if (isDev) {
         console.warn(`Query for ${label} nodes failed:`, error);
       }
@@ -110,32 +145,42 @@ const queryEmbeddableNodes = async (
 };
 
 /**
- * Batch INSERT embeddings into separate CodeEmbedding table
- * Using a separate lightweight table avoids copy-on-write overhead
- * that occurs when UPDATEing nodes with large content fields
+ * Batch INSERT chunk-aware embeddings into CodeEmbedding table
  */
-const batchInsertEmbeddings = async (
+export const batchInsertEmbeddings = async (
   executeWithReusedStatement: (
     cypher: string,
     paramsList: Array<Record<string, any>>,
   ) => Promise<void>,
-  updates: Array<{ id: string; embedding: number[]; contentHash: string }>,
+  updates: Array<{
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    embedding: number[];
+    contentHash?: string;
+  }>,
 ): Promise<void> => {
-  // MERGE instead of CREATE — idempotent, handles concurrent analyzes and partial prior runs
-  const cypher = `MERGE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) SET e.embedding = $embedding, e.contentHash = $contentHash`;
+  const cypher = `CREATE (e:${EMBEDDING_TABLE_NAME} {id: $id, nodeId: $nodeId, chunkIndex: $chunkIndex, startLine: $startLine, endLine: $endLine, embedding: $embedding, contentHash: $contentHash})`;
   const paramsList = updates.map((u) => ({
-    nodeId: u.id,
+    id: `${u.nodeId}:${u.chunkIndex}`,
+    nodeId: u.nodeId,
+    chunkIndex: u.chunkIndex,
+    startLine: u.startLine,
+    endLine: u.endLine,
     embedding: u.embedding,
-    contentHash: u.contentHash,
+    contentHash: u.contentHash ?? STALE_HASH_SENTINEL,
   }));
   await executeWithReusedStatement(cypher, paramsList);
 };
 
 /**
  * Create the vector index for semantic search
+
  * Now indexes the separate CodeEmbedding table.
  * Delegates extension loading to lbug-adapter's loadVectorExtension(),
  * which owns the VECTOR extension lifecycle and state tracking.
+
  */
 const createVectorIndex = async (
   executeQuery: (cypher: string) => Promise<any[]>,
@@ -146,7 +191,6 @@ const createVectorIndex = async (
   try {
     await executeQuery(CREATE_VECTOR_INDEX_QUERY);
   } catch (error) {
-    // Index might already exist
     if (isDev) {
       console.warn('Vector index creation warning:', error);
     }
@@ -160,9 +204,12 @@ const createVectorIndex = async (
  * @param executeWithReusedStatement - Function to execute with reused prepared statement
  * @param onProgress - Callback for progress updates
  * @param config - Optional configuration override
+ * @param skipNodeIds - Optional set of node IDs that already have embeddings (incremental mode)
+ * @param context - Optional repo/server context for metadata enrichment
  * @param existingEmbeddings - Optional map of nodeId → contentHash for incremental mode.
  *        Nodes whose hash matches are skipped; nodes with a changed hash are DELETE'd
  *        and re-embedded; nodes not in the map are embedded fresh.
+
  */
 export const runEmbeddingPipeline = async (
   executeQuery: (cypher: string) => Promise<any[]>,
@@ -172,6 +219,8 @@ export const runEmbeddingPipeline = async (
   ) => Promise<void>,
   onProgress: EmbeddingProgressCallback,
   config: Partial<EmbeddingConfig> = {},
+  skipNodeIds?: Set<string>,
+  context?: EmbeddingContext,
   existingEmbeddings?: Map<string, string>,
 ): Promise<void> => {
   const finalConfig = { ...DEFAULT_EMBEDDING_CONFIG, ...config };
@@ -208,6 +257,14 @@ export const runEmbeddingPipeline = async (
     // Phase 2: Query embeddable nodes
     let nodes = await queryEmbeddableNodes(executeQuery);
 
+    // Apply context metadata
+    if (context?.repoName) {
+      for (const node of nodes) {
+        node.repoName = context.repoName;
+        node.serverName = context.serverName;
+      }
+    }
+
     // Incremental mode: compare content hashes, delete stale rows, skip fresh ones.
     // Computed hashes for stale nodes are cached so batchInsertEmbeddings can reuse them
     // (avoids double computation).
@@ -284,10 +341,12 @@ export const runEmbeddingPipeline = async (
       return;
     }
 
-    // Phase 3: Batch embed nodes
+    // Phase 3: Chunk + embed nodes
     const batchSize = finalConfig.batchSize;
-    const totalBatches = Math.ceil(totalNodes / batchSize);
+    const chunkSize = finalConfig.chunkSize;
+    const overlap = finalConfig.overlap;
     let processedNodes = 0;
+    let totalChunks = 0;
 
     onProgress({
       phase: 'embedding',
@@ -295,40 +354,116 @@ export const runEmbeddingPipeline = async (
       nodesProcessed: 0,
       totalNodes,
       currentBatch: 0,
-      totalBatches,
+      totalBatches: Math.ceil(totalNodes / batchSize),
     });
 
-    for (let batchIndex = 0; batchIndex < totalBatches; batchIndex++) {
-      const start = batchIndex * batchSize;
-      const end = Math.min(start + batchSize, totalNodes);
-      const batch = nodes.slice(start, end);
+    // Process in batches of nodes
+    for (let batchIndex = 0; batchIndex < totalNodes; batchIndex += batchSize) {
+      const batch = nodes.slice(batchIndex, batchIndex + batchSize);
 
-      // Generate texts for this batch
-      const texts = generateBatchEmbeddingTexts(batch, finalConfig);
+      // Chunk each node and generate text
+      const allTexts: string[] = [];
+      const allUpdates: Array<{
+        nodeId: string;
+        chunkIndex: number;
+        startLine: number;
+        endLine: number;
+        contentHash: string;
+      }> = [];
 
-      // Embed the batch
-      const embeddings = await embedBatch(texts);
+      for (const node of batch) {
+        const isShort = isShortLabel(node.label);
+        const startLine = node.startLine ?? 0;
+        const endLine = node.endLine ?? 0;
 
-      // Update LadybugDB with embeddings
-      const updates = batch.map((node, i) => ({
-        id: node.id,
-        embedding: embeddingToArray(embeddings[i]),
-        contentHash: computedStaleHashes.get(node.id) ?? contentHashForNode(node, finalConfig),
-      }));
+        // Extract structural names for class-like nodes via AST extractors
+        if (!isShort && STRUCTURAL_LABELS.has(node.label)) {
+          try {
+            const names = await extractStructuralNames(node.content, node.filePath);
+            node.methodNames = names.methodNames;
+            node.fieldNames = names.fieldNames;
+          } catch {
+            // AST extraction failed — names stay undefined, text-generator handles gracefully
+          }
+        }
 
-      await batchInsertEmbeddings(executeWithReusedStatement, updates);
+        // Compute content hash once per node (re-use cached value for stale nodes)
+        const hash = computedStaleHashes.get(node.id) ?? contentHashForNode(node, finalConfig);
+
+        let chunks: Array<{ text: string; chunkIndex: number; startLine: number; endLine: number }>;
+        if (isShort) {
+          chunks = [{ text: node.content, chunkIndex: 0, startLine, endLine }];
+        } else {
+          try {
+            chunks = await chunkNode(
+              node.label,
+              node.content,
+              node.filePath,
+              startLine,
+              endLine,
+              chunkSize,
+              overlap,
+            );
+          } catch (chunkErr) {
+            if (isDev) {
+              console.warn(
+                `⚠️ AST chunking failed for ${node.label} "${node.name}" (${node.filePath}), falling back to character-based chunking:`,
+                chunkErr,
+              );
+            }
+            chunks = characterChunk(node.content, startLine, endLine, chunkSize, overlap);
+          }
+        }
+
+        for (const chunk of chunks) {
+          const text = generateEmbeddingText(node, chunk.text, finalConfig);
+          allTexts.push(text);
+          allUpdates.push({
+            nodeId: node.id,
+            chunkIndex: chunk.chunkIndex,
+            startLine: chunk.startLine,
+            endLine: chunk.endLine,
+            contentHash: hash,
+          });
+        }
+      }
+
+      // Embed chunk texts in sub-batches to control memory
+      const EMBED_SUB_BATCH = 8;
+      for (let si = 0; si < allTexts.length; si += EMBED_SUB_BATCH) {
+        const subTexts = allTexts.slice(si, si + EMBED_SUB_BATCH);
+        const subUpdates = allUpdates.slice(si, si + EMBED_SUB_BATCH);
+
+        let embeddings: Float32Array[];
+        try {
+          embeddings = await embedBatch(subTexts);
+        } catch (embedErr) {
+          console.error(
+            `❌ embedBatch failed for ${subTexts.length} texts (first: "${subTexts[0]?.substring(0, 80)}..."):`,
+            embedErr,
+          );
+          throw embedErr;
+        }
+
+        const dbUpdates = subUpdates.map((u, i) => ({
+          ...u,
+          embedding: embeddingToArray(embeddings[i]),
+        }));
+
+        await batchInsertEmbeddings(executeWithReusedStatement, dbUpdates);
+      }
 
       processedNodes += batch.length;
+      totalChunks += allUpdates.length;
 
-      // Report progress (20-90% for embedding phase)
       const embeddingProgress = 20 + (processedNodes / totalNodes) * 70;
       onProgress({
         phase: 'embedding',
         percent: Math.round(embeddingProgress),
         nodesProcessed: processedNodes,
         totalNodes,
-        currentBatch: batchIndex + 1,
-        totalBatches,
+        currentBatch: Math.floor(batchIndex / batchSize) + 1,
+        totalBatches: Math.ceil(totalNodes / batchSize),
       });
     }
 
@@ -346,7 +481,6 @@ export const runEmbeddingPipeline = async (
 
     await createVectorIndex(executeQuery);
 
-    // Complete
     onProgress({
       phase: 'ready',
       percent: 100,
@@ -355,7 +489,9 @@ export const runEmbeddingPipeline = async (
     });
 
     if (isDev) {
-      console.log('✅ Embedding pipeline complete!');
+      console.log(
+        `✅ Embedding pipeline complete! (${totalChunks} chunks from ${totalNodes} nodes)`,
+      );
     }
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : 'Unknown error';
@@ -375,15 +511,7 @@ export const runEmbeddingPipeline = async (
 };
 
 /**
- * Perform semantic search using the vector index
- *
- * Uses CodeEmbedding table and queries each node table to get metadata
- *
- * @param executeQuery - Function to execute Cypher queries
- * @param query - Search query text
- * @param k - Number of results to return (default: 10)
- * @param maxDistance - Maximum distance threshold (default: 0.5)
- * @returns Array of search results ordered by relevance
+ * Perform semantic search using the vector index with chunk deduplication
  */
 export const semanticSearch = async (
   executeQuery: (cypher: string) => Promise<any[]>,
@@ -395,37 +523,46 @@ export const semanticSearch = async (
     throw new Error('Embedding model not initialized. Run embedding pipeline first.');
   }
 
-  // Embed the query
   const queryEmbedding = await embedText(query);
   const queryVec = embeddingToArray(queryEmbedding);
   const queryVecStr = `[${queryVec.join(',')}]`;
 
-  // Query the vector index on CodeEmbedding to get nodeIds and distances
-  const vectorQuery = `
-    CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}', 
-      CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${k})
-    YIELD node AS emb, distance
-    WITH emb, distance
-    WHERE distance < ${maxDistance}
-    RETURN emb.nodeId AS nodeId, distance
-    ORDER BY distance
-  `;
+  const bestChunks = await collectBestChunks(k, async (fetchLimit) => {
+    const vectorQuery = `
+      CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+        CAST(${queryVecStr} AS FLOAT[${queryVec.length}]), ${fetchLimit})
+      YIELD node AS emb, distance
+      WITH emb, distance
+      WHERE distance < ${maxDistance}
+      RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+             emb.startLine AS startLine, emb.endLine AS endLine, distance
+      ORDER BY distance
+    `;
 
-  const embResults = await executeQuery(vectorQuery);
+    const embResults = await executeQuery(vectorQuery);
+    return embResults.map((row) => ({
+      nodeId: row.nodeId ?? row[0],
+      chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+      startLine: row.startLine ?? row[2] ?? 0,
+      endLine: row.endLine ?? row[3] ?? 0,
+      distance: row.distance ?? row[4],
+    }));
+  });
 
-  if (embResults.length === 0) {
+  if (bestChunks.size === 0) {
     return [];
   }
 
   // Group results by label for batched metadata queries
-  const byLabel = new Map<string, Array<{ nodeId: string; distance: number }>>();
-  for (const embRow of embResults) {
-    const nodeId = embRow.nodeId ?? embRow[0];
-    const distance = embRow.distance ?? embRow[1];
+  const byLabel = new Map<
+    string,
+    Array<{ nodeId: string; distance: number } & Record<string, any>>
+  >();
+  for (const [nodeId, chunk] of Array.from(bestChunks.entries()).slice(0, k)) {
     const labelEndIdx = nodeId.indexOf(':');
     const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
     if (!byLabel.has(label)) byLabel.set(label, []);
-    byLabel.get(label)!.push({ nodeId, distance });
+    byLabel.get(label)!.push({ nodeId, ...chunk });
   }
 
   // Batch-fetch metadata per label
@@ -434,19 +571,11 @@ export const semanticSearch = async (
   for (const [label, items] of byLabel) {
     const idList = items.map((i) => `'${i.nodeId.replace(/'/g, "''")}'`).join(', ');
     try {
-      let nodeQuery: string;
-      if (label === 'File') {
-        nodeQuery = `
-          MATCH (n:File) WHERE n.id IN [${idList}]
-          RETURN n.id AS id, n.name AS name, n.filePath AS filePath
-        `;
-      } else {
-        nodeQuery = `
-          MATCH (n:${label}) WHERE n.id IN [${idList}]
-          RETURN n.id AS id, n.name AS name, n.filePath AS filePath,
-                 n.startLine AS startLine, n.endLine AS endLine
-        `;
-      }
+      const nodeQuery = `
+        MATCH (n:\`${label}\`) WHERE n.id IN [${idList}]
+        RETURN n.id AS id, n.name AS name, n.filePath AS filePath,
+               n.startLine AS startLine, n.endLine AS endLine
+      `;
       const nodeRows = await executeQuery(nodeQuery);
       const rowMap = new Map<string, any>();
       for (const row of nodeRows) {
@@ -462,8 +591,8 @@ export const semanticSearch = async (
             label,
             filePath: nodeRow.filePath ?? nodeRow[2] ?? '',
             distance: item.distance,
-            startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[3]) : undefined,
-            endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[4]) : undefined,
+            startLine: item.startLine,
+            endLine: item.endLine,
           });
         }
       }
@@ -472,7 +601,6 @@ export const semanticSearch = async (
     }
   }
 
-  // Re-sort by distance since batch queries may have mixed order
   results.sort((a, b) => a.distance - b.distance);
 
   return results;
@@ -480,16 +608,6 @@ export const semanticSearch = async (
 
 /**
  * Semantic search with graph expansion (flattened results)
- *
- * Note: With multi-table schema, graph traversal is simplified.
- * Returns semantic matches with their metadata.
- * For full graph traversal, use execute_vector_cypher tool directly.
- *
- * @param executeQuery - Function to execute Cypher queries
- * @param query - Search query text
- * @param k - Number of initial semantic matches (default: 5)
- * @param _hops - Unused (kept for API compatibility).
- * @returns Semantic matches with metadata
  */
 export const semanticSearchWithContext = async (
   executeQuery: (cypher: string) => Promise<any[]>,
@@ -497,8 +615,6 @@ export const semanticSearchWithContext = async (
   k: number = 5,
   _hops: number = 1,
 ): Promise<any[]> => {
-  // For multi-table schema, just return semantic search results
-  // Graph traversal is complex with separate tables - use execute_vector_cypher instead
   const results = await semanticSearch(executeQuery, query, k, 0.5);
 
   return results.map((r) => ({
diff --git a/gitnexus/src/core/embeddings/line-index.ts b/gitnexus/src/core/embeddings/line-index.ts
new file mode 100644
index 000000000..2dc12de3d
--- /dev/null
+++ b/gitnexus/src/core/embeddings/line-index.ts
@@ -0,0 +1,50 @@
+export interface ResolvedLineRange {
+  startLine: number;
+  endLine: number;
+}
+
+export const buildLineIndex = (content: string): Int32Array => {
+  const offsets: number[] = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content.charCodeAt(i) === 10) offsets.push(i + 1);
+  }
+  return new Int32Array(offsets);
+};
+
+const clampOffset = (lineOffsets: Int32Array, charOffset: number): number => {
+  if (lineOffsets.length === 0) return 0;
+  const maxOffset = lineOffsets[lineOffsets.length - 1];
+  if (charOffset < 0) return 0;
+  if (charOffset > maxOffset) return maxOffset;
+  return charOffset;
+};
+
+export const lineFromOffset = (lineOffsets: Int32Array, charOffset: number): number => {
+  if (lineOffsets.length === 0) return 0;
+
+  const clamped = clampOffset(lineOffsets, charOffset);
+  let lo = 0;
+  let hi = lineOffsets.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineOffsets[mid] <= clamped) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+};
+
+export const resolveChunkLines = (
+  lineOffsets: Int32Array,
+  startOffset: number,
+  endOffset: number,
+  baseStartLine: number,
+): ResolvedLineRange => {
+  const relativeStartLine = lineFromOffset(lineOffsets, startOffset);
+  const effectiveEndOffset = endOffset > startOffset ? endOffset - 1 : startOffset;
+  const relativeEndLine = lineFromOffset(lineOffsets, effectiveEndOffset);
+
+  return {
+    startLine: baseStartLine + relativeStartLine,
+    endLine: baseStartLine + relativeEndLine,
+  };
+};
diff --git a/gitnexus/src/core/embeddings/server-mapping.ts b/gitnexus/src/core/embeddings/server-mapping.ts
new file mode 100644
index 000000000..fa685ac8f
--- /dev/null
+++ b/gitnexus/src/core/embeddings/server-mapping.ts
@@ -0,0 +1,37 @@
+/**
+ * Server Mapping Configuration
+ *
+ * Reads ~/.gitnexus/server-mapping.json to map repo names to service names.
+ * Used in embedding text to enrich metadata with microservice context.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+
+const MAPPING_FILE = path.join(os.homedir(), '.gitnexus', 'server-mapping.json');
+
+let cachedMapping: Record<string, string> | null = null;
+
+/**
+ * Read the server mapping file and return the serverName for a given repoName.
+ * Returns undefined if no mapping exists.
+ */
+export const readServerMapping = async (repoName: string): Promise<string | undefined> => {
+  try {
+    if (!cachedMapping) {
+      const raw = await fs.readFile(MAPPING_FILE, 'utf-8');
+      cachedMapping = JSON.parse(raw);
+    }
+    return cachedMapping[repoName];
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Clear the cached mapping (useful for testing or after file changes)
+ */
+export const clearServerMappingCache = (): void => {
+  cachedMapping = null;
+};
diff --git a/gitnexus/src/core/embeddings/structural-extractor.ts b/gitnexus/src/core/embeddings/structural-extractor.ts
new file mode 100644
index 000000000..7035ee569
--- /dev/null
+++ b/gitnexus/src/core/embeddings/structural-extractor.ts
@@ -0,0 +1,89 @@
+/**
+ * Structural Extractor Module
+ *
+ * Reuses ingestion pipeline's AST-based MethodExtractor / FieldExtractor
+ * to extract method and field names for embedding text generation.
+ */
+
+import { getProviderForFile } from '../ingestion/languages/index.js';
+import type { MethodExtractorContext, ExtractedMethods } from '../ingestion/method-types.js';
+import type { FieldExtractorContext, ExtractedFields } from '../ingestion/field-types.js';
+import type { LanguageProvider } from '../ingestion/language-provider.js';
+import { buildTypeEnv } from '../ingestion/type-env.js';
+import { SupportedLanguages } from 'gitnexus-shared';
+import { ensureAndParse, findDeclarationNode } from './ast-utils.js';
+
+export interface StructuralNames {
+  methodNames: string[];
+  fieldNames: string[];
+}
+
+const NOOP_SYMBOL_TABLE = {
+  lookupExactAll: () => [],
+  lookupExact: () => undefined,
+  lookupExactFull: () => undefined,
+} as any;
+
+/**
+ * Extract method and field names from a class/struct/interface node
+ * using the ingestion pipeline's AST extractors.
+ */
+export const extractStructuralNames = async (
+  content: string,
+  filePath: string,
+): Promise<StructuralNames> => {
+  const provider = getProviderForFile(filePath);
+  if (!provider) return { methodNames: [], fieldNames: [] };
+
+  const tree = await ensureAndParse(content, filePath);
+  if (!tree) return { methodNames: [], fieldNames: [] };
+
+  // Parse node.content (a snippet) — find declaration directly, not by range
+  const classNode = findDeclarationNode(tree.rootNode);
+  if (!classNode) return { methodNames: [], fieldNames: [] };
+
+  const language = provider.id;
+
+  const methodNames = extractMethodNames(classNode, provider, filePath, language);
+  const fieldNames = extractFieldNames(classNode, provider, tree, filePath, language);
+
+  return { methodNames, fieldNames };
+};
+
+function extractMethodNames(
+  classNode: any,
+  provider: LanguageProvider,
+  filePath: string,
+  language: SupportedLanguages,
+): string[] {
+  if (!provider.methodExtractor) return [];
+
+  const context: MethodExtractorContext = { filePath, language };
+  const result: ExtractedMethods | null = provider.methodExtractor.extract(classNode, context);
+  if (!result?.methods?.length) return [];
+
+  return result.methods.map((m) => m.name);
+}
+
+function extractFieldNames(
+  classNode: any,
+  provider: LanguageProvider,
+  tree: any,
+  filePath: string,
+  language: SupportedLanguages,
+): string[] {
+  if (!provider.fieldExtractor) return [];
+
+  const typeEnv = buildTypeEnv(tree, language);
+
+  const context: FieldExtractorContext = {
+    typeEnv,
+    symbolTable: NOOP_SYMBOL_TABLE,
+    filePath,
+    language,
+  };
+  const result: ExtractedFields | null = provider.fieldExtractor.extract(classNode, context);
+  if (!result?.fields?.length) return [];
+
+  return result.fields.map((f) => f.name);
+}
diff --git a/gitnexus/src/core/embeddings/text-generator.ts b/gitnexus/src/core/embeddings/text-generator.ts
index d74a9f894..5b96f6b5e 100644
--- a/gitnexus/src/core/embeddings/text-generator.ts
+++ b/gitnexus/src/core/embeddings/text-generator.ts
@@ -1,206 +1,253 @@
 /**
  * Text Generator Module
  *
- * Pure functions to generate embedding text from code nodes.
- * Combines node metadata with code snippets for semantic matching.
+ * Generates enriched embedding text from code nodes with metadata.
+ * Supports chunkable labels (Function/Method with AST chunking),
+ * Class-specific structural text, and short-node direct embed.
+ *
+ * Method/field names for Class nodes are extracted by the ingestion
+ * pipeline's AST extractors and passed via node.methodNames/node.fieldNames.
  */
 
 import type { EmbeddableNode, EmbeddingConfig } from './types.js';
-import { DEFAULT_EMBEDDING_CONFIG } from './types.js';
+import { DEFAULT_EMBEDDING_CONFIG, isShortLabel } from './types.js';
 
 /**
- * Extract the filename from a file path
+ * Truncate description to max length at sentence/word boundary
  */
-const getFileName = (filePath: string): string => {
-  const parts = filePath.split('/');
-  return parts[parts.length - 1] || filePath;
-};
+const truncateDescription = (text: string, maxLength: number): string => {
+  if (text.length <= maxLength) return text;
 
-/**
- * Extract the directory path from a file path
- */
-const getDirectory = (filePath: string): string => {
-  const parts = filePath.split('/');
-  parts.pop();
-  return parts.join('/') || '';
-};
+  const truncated = text.slice(0, maxLength);
 
-/**
- * Truncate content to max length, preserving word boundaries
- */
-const truncateContent = (content: string, maxLength: number): string => {
-  if (content.length <= maxLength) {
-    return content;
+  // Try sentence boundary (. ! ?)
+  const sentenceEnd = Math.max(
+    truncated.lastIndexOf('. '),
+    truncated.lastIndexOf('! '),
+    truncated.lastIndexOf('? '),
+  );
+  if (sentenceEnd > maxLength * 0.5) {
+    return truncated.slice(0, sentenceEnd + 1);
   }
 
-  // Find last space before maxLength to avoid cutting words
-  const truncated = content.slice(0, maxLength);
+  // Try word boundary
   const lastSpace = truncated.lastIndexOf(' ');
-
-  if (lastSpace > maxLength * 0.8) {
-    return truncated.slice(0, lastSpace) + '...';
+  if (lastSpace > maxLength * 0.5) {
+    return truncated.slice(0, lastSpace);
   }
 
-  return truncated + '...';
+  return truncated;
 };
 
 /**
  * Clean code content for embedding
- * Removes excessive whitespace while preserving structure
  */
 const cleanContent = (content: string): string => {
-  return (
-    content
-      // Normalize line endings
-      .replace(/\r\n/g, '\n')
-      // Remove excessive blank lines (more than 2)
-      .replace(/\n{3,}/g, '\n\n')
-      // Trim each line
-      .split('\n')
-      .map((line) => line.trimEnd())
-      .join('\n')
-      .trim()
-  );
+  return content
+    .replace(/\r\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .join('\n')
+    .trim();
 };
 
 /**
- * Generate embedding text for a Function node
+ * Build metadata header for a node
  */
-const generateFunctionText = (node: EmbeddableNode, maxSnippetLength: number): string => {
-  const parts: string[] = [`Function: ${node.name}`, `File: ${getFileName(node.filePath)}`];
+const buildMetadataHeader = (node: EmbeddableNode, config: Partial<EmbeddingConfig>): string => {
+  const parts: string[] = [];
 
-  const dir = getDirectory(node.filePath);
-  if (dir) {
-    parts.push(`Directory: ${dir}`);
+  // Label + name
+  parts.push(`${node.label}: ${node.name}`);
+
+  // Repo name
+  if (node.repoName) {
+    parts.push(`Repo: ${node.repoName}`);
   }
 
-  if (node.content) {
-    const cleanedContent = cleanContent(node.content);
-    const snippet = truncateContent(cleanedContent, maxSnippetLength);
-    parts.push('', snippet);
+  // Server name (optional)
+  if (node.serverName) {
+    parts.push(`Server: ${node.serverName}`);
+  }
+
+  // Full file path
+  parts.push(`Path: ${node.filePath}`);
+
+  // Export status
+  if (node.isExported !== undefined) {
+    parts.push(`Export: ${node.isExported}`);
+  }
+
+  // Description (truncated)
+  if (node.description) {
+    const maxLen = config.maxDescriptionLength ?? DEFAULT_EMBEDDING_CONFIG.maxDescriptionLength;
+    const truncated = truncateDescription(node.description, maxLen);
+    if (truncated) {
+      parts.push(truncated);
+    }
   }
 
   return parts.join('\n');
 };
 
-/**
- * Generate embedding text for a Class node
- */
-const generateClassText = (node: EmbeddableNode, maxSnippetLength: number): string => {
-  const parts: string[] = [`Class: ${node.name}`, `File: ${getFileName(node.filePath)}`];
+const generateCodeBodyText = (
+  node: EmbeddableNode,
+  codeBody: string,
+  config: Partial<EmbeddingConfig>,
+): string => {
+  const header = buildMetadataHeader(node, config);
+  const cleaned = cleanContent(codeBody);
+  return `${header}\n\n${cleaned}`;
+};
 
-  const dir = getDirectory(node.filePath);
-  if (dir) {
-    parts.push(`Directory: ${dir}`);
+/**
+ * Generate embedding text for Class nodes
+ * Signature + properties + method name list only (no method bodies)
+ * Method/field names come from AST extractors via node.methodNames/node.fieldNames.
+ */
+const generateClassText = (
+  node: EmbeddableNode,
+  codeBody: string,
+  config: Partial<EmbeddingConfig>,
+): string => {
+  return generateStructuralTypeText(node, codeBody, config);
+};
+
+const generateStructuralTypeText = (
+  node: EmbeddableNode,
+  codeBody: string,
+  config: Partial<EmbeddingConfig>,
+): string => {
+  const header = buildMetadataHeader(node, config);
+  const parts: string[] = [header];
+
+  if (node.methodNames?.length) {
+    parts.push(`Methods: ${node.methodNames.join(', ')}`);
+  }
+  if (node.fieldNames?.length) {
+    parts.push(`Properties: ${node.fieldNames.join(', ')}`);
   }
 
-  if (node.content) {
-    const cleanedContent = cleanContent(node.content);
-    const snippet = truncateContent(cleanedContent, maxSnippetLength);
-    parts.push('', snippet);
+  const declarationOnly = extractDeclarationOnly(cleanContent(node.content));
+  if (declarationOnly) {
+    parts.push('', declarationOnly);
+  }
+
+  const cleanedChunk = cleanContent(codeBody);
+  if (cleanedChunk && cleanedChunk !== cleanContent(node.content)) {
+    parts.push('', cleanedChunk);
   }
 
   return parts.join('\n');
 };
 
-/**
- * Generate embedding text for a Method node
- */
-const generateMethodText = (node: EmbeddableNode, maxSnippetLength: number): string => {
-  const parts: string[] = [`Method: ${node.name}`, `File: ${getFileName(node.filePath)}`];
-
-  const dir = getDirectory(node.filePath);
-  if (dir) {
-    parts.push(`Directory: ${dir}`);
-  }
-
-  if (node.content) {
-    const cleanedContent = cleanContent(node.content);
-    const snippet = truncateContent(cleanedContent, maxSnippetLength);
-    parts.push('', snippet);
-  }
-
-  return parts.join('\n');
-};
+const DECL_START_RE =
+  /^(?:(?:export|pub|data|abstract)\s+)*(?:type\s+\w+\s+struct|(?:class|struct|enum|interface)\s)/;
 
 /**
- * Generate embedding text for an Interface node
+ * Extract class/interface/struct declaration lines, skipping method bodies.
+ * - Brace-based languages: detects method signatures (lines with `(` and `{`)
+ *   and skips until depth returns to class body level.
+ * - Non-brace languages (Python/Ruby): returns empty string (patterns handle extraction).
  */
-const generateInterfaceText = (node: EmbeddableNode, maxSnippetLength: number): string => {
-  const parts: string[] = [`Interface: ${node.name}`, `File: ${getFileName(node.filePath)}`];
+export const extractDeclarationOnly = (content: string): string => {
+  const lines = content.split('\n');
+  const declLines: string[] = [];
+  let depth = 0;
+  let started = false;
+  let classDepth = 0;
+  let skipDepth = 0;
 
-  const dir = getDirectory(node.filePath);
-  if (dir) {
-    parts.push(`Directory: ${dir}`);
+  for (const [idx, line] of lines.entries()) {
+    const trimmed = line.trim();
+
+    if (!started) {
+      if (DECL_START_RE.test(trimmed)) {
+        // Non-brace language check: current line or next 3 lines must have `{`
+        const nextLines = lines.slice(idx + 1, idx + 4);
+        if (!trimmed.includes('{') && !nextLines.some((l) => l.includes('{'))) {
+          return '';
+        }
+        started = true;
+        declLines.push(trimmed);
+        for (const ch of trimmed) {
+          if (ch === '{') depth++;
+          else if (ch === '}') depth--;
+        }
+        if (depth > 0) classDepth = depth;
+      }
+      continue;
+    }
+
+    // Always update depth (even when skipping)
+    const opens = (trimmed.match(/{/g) || []).length;
+    const closes = (trimmed.match(/}/g) || []).length;
+    const prevDepth = depth;
+    depth += opens - closes;
+
+    if (skipDepth > 0) {
+      if (depth <= classDepth) {
+        skipDepth = 0;
+        // Closing brace of class
+        if (depth <= 0) {
+          declLines.push(trimmed);
+          break;
+        }
+      }
+      continue;
+    }
+
+    // Detect method signature: line has both `(` and `{` and goes deeper than class body
+    const hasParens = trimmed.includes('(');
+    const hasOpenBrace = opens > 0;
+    if (hasParens && hasOpenBrace && prevDepth + opens > classDepth) {
+      if (opens === closes && trimmed.endsWith(';')) {
+        // Property with function/object initializer like `config = { timeout: 5000 };` — keep
+        declLines.push(trimmed);
+      }
+      // else: single-line or multi-line method — skip entirely
+      if (opens !== closes) {
+        skipDepth = classDepth;
+      }
+      continue;
+    }
+
+    declLines.push(trimmed);
+
+    if (depth <= 0 && declLines.length > 1) break;
   }
 
-  if (node.content) {
-    const cleanedContent = cleanContent(node.content);
-    const snippet = truncateContent(cleanedContent, maxSnippetLength);
-    parts.push('', snippet);
-  }
-
-  return parts.join('\n');
-};
-
-/**
- * Generate embedding text for a File node
- * Uses file name and first N characters of content
- */
-const generateFileText = (node: EmbeddableNode, maxSnippetLength: number): string => {
-  const parts: string[] = [`File: ${node.name}`, `Path: ${node.filePath}`];
-
-  if (node.content) {
-    const cleanedContent = cleanContent(node.content);
-    // For files, use a shorter snippet since they can be very long
-    const snippet = truncateContent(cleanedContent, Math.min(maxSnippetLength, 300));
-    parts.push('', snippet);
-  }
-
-  return parts.join('\n');
+  return declLines.join('\n').trim();
 };
 
 /**
  * Generate embedding text for any embeddable node
  * Dispatches to the appropriate generator based on node label
- *
- * @param node - The node to generate text for
- * @param config - Optional configuration for max snippet length
- * @returns Text suitable for embedding
  */
 export const generateEmbeddingText = (
   node: EmbeddableNode,
+  codeBody: string,
   config: Partial<EmbeddingConfig> = {},
 ): string => {
-  const maxSnippetLength = config.maxSnippetLength ?? DEFAULT_EMBEDDING_CONFIG.maxSnippetLength;
-
-  switch (node.label) {
-    case 'Function':
-      return generateFunctionText(node, maxSnippetLength);
-    case 'Class':
-      return generateClassText(node, maxSnippetLength);
-    case 'Method':
-      return generateMethodText(node, maxSnippetLength);
-    case 'Interface':
-      return generateInterfaceText(node, maxSnippetLength);
-    case 'File':
-      return generateFileText(node, maxSnippetLength);
-    default:
-      // Fallback for any other embeddable type
-      return `${node.label}: ${node.name}\nPath: ${node.filePath}`;
+  if (isShortLabel(node.label)) {
+    const header = buildMetadataHeader(node, config);
+    const cleaned = cleanContent(node.content);
+    return `${header}\n\n${cleaned}`;
   }
+
+  if (node.label === 'Class') {
+    return generateClassText(node, codeBody, config);
+  }
+
+  if (node.label === 'Interface') {
+    return generateStructuralTypeText(node, codeBody, config);
+  }
+
+  return generateCodeBodyText(node, codeBody, config);
 };
 
 /**
- * Generate embedding texts for a batch of nodes
- *
- * @param nodes - Array of nodes to generate text for
- * @param config - Optional configuration
- * @returns Array of texts in the same order as input nodes
+ * Export truncation helper for testing
  */
-export const generateBatchEmbeddingTexts = (
-  nodes: EmbeddableNode[],
-  config: Partial<EmbeddingConfig> = {},
-): string[] => {
-  return nodes.map((node) => generateEmbeddingText(node, config));
-};
+export { truncateDescription };
diff --git a/gitnexus/src/core/embeddings/types.ts b/gitnexus/src/core/embeddings/types.ts
index 599faa3a9..c24dcdf40 100644
--- a/gitnexus/src/core/embeddings/types.ts
+++ b/gitnexus/src/core/embeddings/types.ts
@@ -5,10 +5,40 @@
  */
 
 /**
- * Node labels that should be embedded for semantic search
- * These are code elements that benefit from semantic matching
+ * Node labels that need chunking (have code body, potentially long)
  */
-export const EMBEDDABLE_LABELS = ['Function', 'Class', 'Method', 'Interface', 'File'] as const;
+export const CHUNKABLE_LABELS = [
+  'Function',
+  'Method',
+  'Constructor',
+  'Class',
+  'Interface',
+  'Struct',
+  'Enum',
+  'Trait',
+  'Impl',
+  'Macro',
+  'Namespace',
+] as const;
+
+/**
+ * Node labels that are short (no chunking needed, embed directly)
+ */
+export const SHORT_LABELS = [
+  'TypeAlias',
+  'Typedef',
+  'Const',
+  'Property',
+  'Record',
+  'Union',
+  'Static',
+  'Variable',
+] as const;
+
+/**
+ * All embeddable labels (union of CHUNKABLE + SHORT)
+ */
+export const EMBEDDABLE_LABELS = [...CHUNKABLE_LABELS, ...SHORT_LABELS] as const;
 
 export type EmbeddableLabel = (typeof EMBEDDABLE_LABELS)[number];
 
@@ -18,6 +48,39 @@ export type EmbeddableLabel = (typeof EMBEDDABLE_LABELS)[number];
 export const isEmbeddableLabel = (label: string): label is EmbeddableLabel =>
   EMBEDDABLE_LABELS.includes(label as EmbeddableLabel);
 
+/**
+ * Check if a label needs chunking
+ */
+export const isChunkableLabel = (label: string): boolean =>
+  (CHUNKABLE_LABELS as readonly string[]).includes(label);
+
+/**
+ * Check if a label is a short type (no chunking)
+ */
+export const isShortLabel = (label: string): boolean =>
+  (SHORT_LABELS as readonly string[]).includes(label);
+
+/**
+ * Node labels that have structural names (methods/fields) extractable via AST
+ */
+export const STRUCTURAL_LABELS: ReadonlySet<string> = new Set([
+  'Class',
+  'Struct',
+  'Interface',
+  'Enum',
+]);
+
+/**
+ * Node labels that have isExported column in their schema
+ */
+export const LABELS_WITH_EXPORTED = new Set([
+  'Function',
+  'Class',
+  'Interface',
+  'Method',
+  'CodeElement',
+]) as ReadonlySet<string>;
+
 /**
  * Embedding pipeline phases
  */
@@ -57,6 +120,12 @@ export interface EmbeddingConfig {
   device: 'auto' | 'dml' | 'cuda' | 'cpu' | 'wasm';
   /** Maximum characters of code snippet to include */
   maxSnippetLength: number;
+  /** Maximum code chunk size in characters (for chunking long code) */
+  chunkSize: number;
+  /** Overlap between chunks in characters */
+  overlap: number;
+  /** Maximum description length in characters */
+  maxDescriptionLength: number;
 }
 
 /**
@@ -70,6 +139,9 @@ export const DEFAULT_EMBEDDING_CONFIG: EmbeddingConfig = {
   dimensions: 384,
   device: 'auto',
   maxSnippetLength: 500,
+  chunkSize: 1200,
+  overlap: 120,
+  maxDescriptionLength: 150,
 };
 
 /**
@@ -96,6 +168,34 @@ export interface EmbeddableNode {
   content: string;
   startLine?: number;
   endLine?: number;
+  isExported?: boolean;
+  description?: string;
+  parameterCount?: number;
+  returnType?: string;
+  repoName?: string;
+  serverName?: string;
+  methodNames?: string[];
+  fieldNames?: string[];
+}
+
+/**
+ * Cached embedding entry restored from LadybugDB before a graph rebuild
+ */
+export interface CachedEmbedding {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  embedding: number[];
+  contentHash?: string;
+}
+
+/**
+ * Context info for embedding pipeline (repo/server metadata enrichment)
+ */
+export interface EmbeddingContext {
+  repoName?: string;
+  serverName?: string;
 }
 
 /**
@@ -108,3 +208,75 @@ export interface ModelProgress {
   loaded?: number;
   total?: number;
 }
+
+export interface ChunkSearchRow {
+  nodeId: string;
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  distance: number;
+}
+
+export interface BestChunkMatch {
+  chunkIndex: number;
+  startLine: number;
+  endLine: number;
+  distance: number;
+}
+
+/**
+ * Deduplicate vector search chunk results by nodeId,
+ * keeping the chunk with smallest distance for each node.
+ */
+export const dedupBestChunks = (
+  rows: ChunkSearchRow[],
+  limit?: number,
+): Map<string, BestChunkMatch> => {
+  const best = new Map<string, BestChunkMatch>();
+  for (const row of rows) {
+    const existing = best.get(row.nodeId);
+    if (!existing || row.distance < existing.distance) {
+      best.set(row.nodeId, {
+        chunkIndex: row.chunkIndex,
+        startLine: row.startLine,
+        endLine: row.endLine,
+        distance: row.distance,
+      });
+    }
+    if (limit !== undefined && best.size >= limit) break;
+  }
+  return best;
+};
+
+const DEFAULT_FETCH_MULTIPLIER = 4;
+const DEFAULT_FETCH_BUFFER = 8;
+const DEFAULT_MAX_FETCH = 200;
+
+/**
+ * Fetch vector-search chunks until we have enough unique nodeIds
+ * or can tell the result set is exhausted.
+ */
+export const collectBestChunks = async (
+  limit: number,
+  fetchRows: (fetchLimit: number) => Promise<ChunkSearchRow[]>,
+  maxFetch: number = DEFAULT_MAX_FETCH,
+): Promise<Map<string, BestChunkMatch>> => {
+  if (limit <= 0) return new Map();
+
+  let fetchLimit = Math.max(limit * DEFAULT_FETCH_MULTIPLIER, limit + DEFAULT_FETCH_BUFFER);
+  let previousFetchLimit = 0;
+
+  while (fetchLimit > previousFetchLimit) {
+    const rows = await fetchRows(fetchLimit);
+    const bestChunks = dedupBestChunks(rows, limit);
+
+    if (bestChunks.size >= limit || rows.length < fetchLimit) {
+      return bestChunks;
+    }
+
+    previousFetchLimit = fetchLimit;
+    fetchLimit = fetchLimit >= maxFetch ? fetchLimit * 2 : Math.min(maxFetch, fetchLimit * 2);
+  }
+
+  return new Map();
+};
diff --git a/gitnexus/src/core/group/extractors/http-patterns/node.ts b/gitnexus/src/core/group/extractors/http-patterns/node.ts
index 587f48e8c..fbf988665 100644
--- a/gitnexus/src/core/group/extractors/http-patterns/node.ts
+++ b/gitnexus/src/core/group/extractors/http-patterns/node.ts
@@ -17,6 +17,9 @@ import type { HttpDetection, HttpLanguagePlugin } from './types.js';
  *   - Express `router.get(...)` / `app.post(...)` providers
  *   - `fetch(url)` / `fetch(url, { method: 'POST' })` consumers
  *   - `axios.get(url)` / `axios.delete(url)` consumers
+ *   - `axios({ method, url })` object-form consumers
+ *   - jQuery `$.get(url)` / `$.post(url, ...)` shorthand consumers
+ *   - jQuery `$.ajax({ url, method | type })` consumers
  *
  * Because the JavaScript and TypeScript tree-sitter grammars share
  * node type names for every construct we query, pattern sources are
@@ -103,6 +106,48 @@ const AXIOS_SPEC: PatternSpec<Record<string, never>> = {
   `,
 };
 
+// ─── Consumer: jQuery shorthand $.get(url) / $.post(url, ...) ────────
+// `$` is a valid JS identifier, so tree-sitter parses `$.get(...)` as a
+// call_expression whose function is a member_expression on identifier `$`.
+const JQUERY_SHORTHAND_SPEC: PatternSpec<Record<string, never>> = {
+  meta: {},
+  query: `
+    (call_expression
+      function: (member_expression
+        object: (identifier) @obj (#eq? @obj "$")
+        property: (property_identifier) @http_method (#match? @http_method "^(get|post)$"))
+      arguments: (arguments . [(string) (template_string)] @path))
+  `,
+};
+
+// ─── Consumer: jQuery $.ajax({ url, method|type }) ───────────────────
+// The query captures the options object only; key/value pairs are read
+// programmatically via `readStringProp` below, which tolerates any key
+// order and accepts either `method:` or `type:` (jQuery supports both).
+const JQUERY_AJAX_SPEC: PatternSpec<Record<string, never>> = {
+  meta: {},
+  query: `
+    (call_expression
+      function: (member_expression
+        object: (identifier) @obj (#eq? @obj "$")
+        property: (property_identifier) @fn (#eq? @fn "ajax"))
+      arguments: (arguments (object) @options))
+  `,
+};
+
+// ─── Consumer: axios({ method, url }) object form ────────────────────
+// Distinct from AXIOS_SPEC above because the call target is an identifier
+// (`axios`) rather than a member expression (`axios.get`). As with the
+// jQuery ajax form, option keys are resolved programmatically.
+const AXIOS_OBJECT_SPEC: PatternSpec<Record<string, never>> = {
+  meta: {},
+  query: `
+    (call_expression
+      function: (identifier) @fn (#eq? @fn "axios")
+      arguments: (arguments (object) @options))
+  `,
+};
+
 interface NodePatternBundle {
   controller: CompiledPatterns<Record<string, never>>;
   methodDecorator: CompiledPatterns<Record<string, never>>;
@@ -110,6 +155,9 @@ interface NodePatternBundle {
   fetchNoOptions: CompiledPatterns<Record<string, never>>;
   fetchWithOptions: CompiledPatterns<Record<string, never>>;
   axios: CompiledPatterns<Record<string, never>>;
+  jqueryShorthand: CompiledPatterns<Record<string, never>>;
+  jqueryAjax: CompiledPatterns<Record<string, never>>;
+  axiosObject: CompiledPatterns<Record<string, never>>;
 }
 
 function compileBundle(language: unknown, name: string): NodePatternBundle {
@@ -126,6 +174,9 @@ function compileBundle(language: unknown, name: string): NodePatternBundle {
     fetchNoOptions: mk(FETCH_NO_OPTIONS_SPEC, 'fetch-no-options'),
     fetchWithOptions: mk(FETCH_WITH_OPTIONS_SPEC, 'fetch-with-options'),
     axios: mk(AXIOS_SPEC, 'axios'),
+    jqueryShorthand: mk(JQUERY_SHORTHAND_SPEC, 'jquery-shorthand'),
+    jqueryAjax: mk(JQUERY_AJAX_SPEC, 'jquery-ajax'),
+    axiosObject: mk(AXIOS_OBJECT_SPEC, 'axios-object'),
   };
 }
 
@@ -160,6 +211,28 @@ function joinPath(prefix: string, sub: string): string {
   return `/${cleanPrefix}/${cleanSub}`;
 }
 
+/**
+ * Walk `pair` children of an `object` literal and return the unquoted
+ * string/template_string value for the first pair whose key matches one
+ * of `keyNames`. Returns null when no matching pair is present or the
+ * value is not a string literal. Used by the jQuery ajax / axios object
+ * consumers to resolve `url` / `method` / `type` keys in any order.
+ */
+function readStringProp(objectNode: Parser.SyntaxNode, keyNames: readonly string[]): string | null {
+  for (let i = 0; i < objectNode.namedChildCount; i++) {
+    const pair = objectNode.namedChild(i);
+    if (!pair || pair.type !== 'pair') continue;
+    const keyNode = pair.childForFieldName('key');
+    const valueNode = pair.childForFieldName('value');
+    if (!keyNode || !valueNode) continue;
+    if (!keyNames.includes(keyNode.text)) continue;
+    if (valueNode.type !== 'string' && valueNode.type !== 'template_string') continue;
+    const lit = unquoteLiteral(valueNode.text);
+    if (lit !== null) return lit;
+  }
+  return null;
+}
+
 /**
  * For a standalone `decorator` node (child of class_body / program),
  * find the related `class_declaration` node that it decorates. In
@@ -351,6 +424,62 @@ function scanBundle(bundle: NodePatternBundle, tree: Parser.Tree): HttpDetection
     });
   }
 
+  // Consumer: jQuery shorthand $.get(url) / $.post(url, ...)
+  for (const match of runCompiledPatterns(bundle.jqueryShorthand, tree)) {
+    const methodNode = match.captures.http_method;
+    const pathNode = match.captures.path;
+    if (!methodNode || !pathNode) continue;
+    const path = unquoteLiteral(pathNode.text);
+    if (path === null) continue;
+    out.push({
+      role: 'consumer',
+      framework: 'jquery',
+      method: methodNode.text.toUpperCase(),
+      path,
+      name: null,
+      confidence: 0.7,
+    });
+  }
+
+  // Consumer: jQuery $.ajax({ url, method|type }). jQuery accepts either
+  // `method:` or `type:`; both default to GET when absent.
+  for (const match of runCompiledPatterns(bundle.jqueryAjax, tree)) {
+    const optionsNode = match.captures.options;
+    if (!optionsNode) continue;
+    const path = readStringProp(optionsNode, ['url']);
+    if (path === null) continue;
+    const rawMethod = readStringProp(optionsNode, ['method', 'type']);
+    const method = (rawMethod ?? 'GET').toUpperCase();
+    out.push({
+      role: 'consumer',
+      framework: 'jquery',
+      method,
+      path,
+      name: null,
+      confidence: 0.7,
+    });
+  }
+
+  // Consumer: axios({ method, url }) object form. Structurally distinct
+  // from axios.<verb>(url) (identifier vs member_expression call), so no
+  // dedup against the member-form loop above is required.
+  for (const match of runCompiledPatterns(bundle.axiosObject, tree)) {
+    const optionsNode = match.captures.options;
+    if (!optionsNode) continue;
+    const path = readStringProp(optionsNode, ['url']);
+    if (path === null) continue;
+    const rawMethod = readStringProp(optionsNode, ['method']);
+    const method = (rawMethod ?? 'GET').toUpperCase();
+    out.push({
+      role: 'consumer',
+      framework: 'axios',
+      method,
+      path,
+      name: null,
+      confidence: 0.7,
+    });
+  }
+
   return out;
 }
 
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/c-cpp.ts b/gitnexus/src/core/ingestion/call-extractors/configs/c-cpp.ts
new file mode 100644
index 000000000..02a6ed60f
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/c-cpp.ts
@@ -0,0 +1,12 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/c-cpp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const cCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.C,
+};
+
+export const cppCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.CPlusPlus,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/csharp.ts b/gitnexus/src/core/ingestion/call-extractors/configs/csharp.ts
new file mode 100644
index 000000000..e2c0415c2
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/csharp.ts
@@ -0,0 +1,9 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/csharp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const csharpCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.CSharp,
+  typeAsReceiverHeuristic: true,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/dart.ts b/gitnexus/src/core/ingestion/call-extractors/configs/dart.ts
new file mode 100644
index 000000000..9d3c08def
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/dart.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/dart.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const dartCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Dart,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/go.ts b/gitnexus/src/core/ingestion/call-extractors/configs/go.ts
new file mode 100644
index 000000000..870fc88e0
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/go.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/go.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const goCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Go,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/jvm.ts b/gitnexus/src/core/ingestion/call-extractors/configs/jvm.ts
new file mode 100644
index 000000000..51de04228
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/jvm.ts
@@ -0,0 +1,59 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/jvm.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig, ExtractedCallSite } from '../../call-types.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+// ---------------------------------------------------------------------------
+// Java method_reference (::) parsing — absorbs call-sites/java.ts
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse Java `method_reference` nodes (`expr::method`, `Type::new`,
+ * `this::m`, `super::m`).
+ */
+function parseJavaMethodReference(callNode: SyntaxNode): ExtractedCallSite | null {
+  if (callNode.type !== 'method_reference') return null;
+
+  const recv = callNode.namedChild(0);
+  if (!recv) return null;
+
+  // Type::new  →  constructor call
+  for (const c of callNode.children) {
+    if (c.type === 'new') {
+      if (recv.type !== 'identifier') return null;
+      return { calledName: recv.text, callForm: 'constructor' };
+    }
+  }
+
+  // expr::method  →  member call with receiver
+  const rhs = callNode.child(callNode.childCount - 1);
+  if (!rhs || rhs.type !== 'identifier') return null;
+  const methodName = rhs.text;
+
+  if (recv.type === 'identifier') {
+    return { calledName: methodName, callForm: 'member', receiverName: recv.text };
+  }
+  if (recv.type === 'this') {
+    return { calledName: methodName, callForm: 'member', receiverName: 'this' };
+  }
+  if (recv.type === 'super') {
+    return { calledName: methodName, callForm: 'member', receiverName: 'super' };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Configs
+// ---------------------------------------------------------------------------
+
+export const javaCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Java,
+  extractLanguageCallSite: parseJavaMethodReference,
+  typeAsReceiverHeuristic: true,
+};
+
+export const kotlinCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Kotlin,
+  typeAsReceiverHeuristic: true,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/php.ts b/gitnexus/src/core/ingestion/call-extractors/configs/php.ts
new file mode 100644
index 000000000..25ed0b9ab
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/php.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/php.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const phpCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.PHP,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/python.ts b/gitnexus/src/core/ingestion/call-extractors/configs/python.ts
new file mode 100644
index 000000000..35ab87305
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/python.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/python.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const pythonCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Python,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/ruby.ts b/gitnexus/src/core/ingestion/call-extractors/configs/ruby.ts
new file mode 100644
index 000000000..d829c5c89
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/ruby.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/ruby.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const rubyCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Ruby,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/rust.ts b/gitnexus/src/core/ingestion/call-extractors/configs/rust.ts
new file mode 100644
index 000000000..03c48f781
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/rust.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/rust.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const rustCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Rust,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/swift.ts b/gitnexus/src/core/ingestion/call-extractors/configs/swift.ts
new file mode 100644
index 000000000..28f2c180c
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/swift.ts
@@ -0,0 +1,8 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/swift.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const swiftCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.Swift,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/configs/typescript-javascript.ts b/gitnexus/src/core/ingestion/call-extractors/configs/typescript-javascript.ts
new file mode 100644
index 000000000..20a63cda9
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/configs/typescript-javascript.ts
@@ -0,0 +1,12 @@
+// gitnexus/src/core/ingestion/call-extractors/configs/typescript-javascript.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { CallExtractionConfig } from '../../call-types.js';
+
+export const typescriptCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.TypeScript,
+};
+
+export const javascriptCallConfig: CallExtractionConfig = {
+  language: SupportedLanguages.JavaScript,
+};
diff --git a/gitnexus/src/core/ingestion/call-extractors/generic.ts b/gitnexus/src/core/ingestion/call-extractors/generic.ts
new file mode 100644
index 000000000..82e38457b
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-extractors/generic.ts
@@ -0,0 +1,86 @@
+// gitnexus/src/core/ingestion/call-extractors/generic.ts
+
+/**
+ * Generic table-driven call extractor factory.
+ *
+ * Mirrors method-extractors/generic.ts and field-extractors/generic.ts —
+ * define a config per language and generate extractors from configs.
+ *
+ * The factory converts a declarative {@link CallExtractionConfig} into a
+ * runtime {@link CallExtractor} whose `extract()` method:
+ *   1. Tries `config.extractLanguageCallSite(callNode)` for non-standard shapes.
+ *   2. Falls through to the generic path using shared utilities from
+ *      `utils/call-analysis.ts` (`inferCallForm`, `extractReceiverName`, etc.).
+ */
+
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+import {
+  inferCallForm,
+  extractReceiverName,
+  extractReceiverNode,
+  extractMixedChain,
+  countCallArguments,
+} from '../utils/call-analysis.js';
+import type { CallExtractor, CallExtractionConfig, ExtractedCallSite } from '../call-types.js';
+
+/**
+ * Create a CallExtractor from a declarative config.
+ */
+export function createCallExtractor(config: CallExtractionConfig): CallExtractor {
+  return {
+    language: config.language,
+
+    extract(callNode: SyntaxNode, callNameNode: SyntaxNode | undefined): ExtractedCallSite | null {
+      // ── Path 1: Language-specific call site ──────────────────────────
+      // Non-standard call shapes (e.g. Java `::` method references) are
+      // handled entirely by the config hook.  When it returns a result,
+      // the generic path is skipped — no argCount, no mixed chain.
+      //
+      // Note: `extractLanguageCallSite` is called on every `extract()`
+      // invocation — both `extract(callNode, undefined)` (parse-worker
+      // Path 1) and `extract(callNode, callNameNode)` (Path 2).
+      // Language hooks must therefore be idempotent and cheap (e.g. a
+      // single node-type check).
+      if (config.extractLanguageCallSite) {
+        const seed = config.extractLanguageCallSite(callNode);
+        if (seed) {
+          return {
+            ...seed,
+            ...(config.typeAsReceiverHeuristic ? { typeAsReceiverHeuristic: true } : {}),
+          };
+        }
+      }
+
+      // ── Path 2: Generic extraction via @call.name ────────────────────
+      if (!callNameNode) return null;
+
+      const calledName = callNameNode.text;
+      const callForm = inferCallForm(callNode, callNameNode);
+      let receiverName = callForm === 'member' ? extractReceiverName(callNameNode) : undefined;
+      let receiverMixedChain: ExtractedCallSite['receiverMixedChain'];
+
+      // When the receiver is a complex expression (call chain, field chain,
+      // or mixed), extractReceiverName returns undefined.  Walk the receiver
+      // node to build a unified mixed chain for deferred resolution.
+      if (callForm === 'member' && receiverName === undefined) {
+        const receiverNode = extractReceiverNode(callNameNode);
+        if (receiverNode) {
+          const extracted = extractMixedChain(receiverNode);
+          if (extracted && extracted.chain.length > 0) {
+            receiverMixedChain = extracted.chain;
+            receiverName = extracted.baseReceiverName;
+          }
+        }
+      }
+
+      return {
+        calledName,
+        ...(callForm !== undefined ? { callForm } : {}),
+        ...(receiverName !== undefined ? { receiverName } : {}),
+        argCount: countCallArguments(callNode),
+        ...(receiverMixedChain !== undefined ? { receiverMixedChain } : {}),
+        ...(config.typeAsReceiverHeuristic ? { typeAsReceiverHeuristic: true } : {}),
+      };
+    },
+  };
+}
diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts
index ce0364a4d..7d8a9da27 100644
--- a/gitnexus/src/core/ingestion/call-processor.ts
+++ b/gitnexus/src/core/ingestion/call-processor.ts
@@ -1,7 +1,34 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import { ASTCache } from './ast-cache.js';
-import type { SymbolDefinition, SymbolTableReader } from './model/symbol-table.js';
-import { CLASS_TYPES, CALL_TARGET_TYPES } from './model/symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
+import type { SymbolTableReader, HeritageMap, ExtractedHeritage } from './model/index.js';
+import { CLASS_TYPES, CALL_TARGET_TYPES, lookupMethodByOwnerWithMRO } from './model/index.js';
+import type { DispatchDecision, ReceiverEnriched } from './call-types.js';
+
+/** Shorthand for the receiver-source discriminant shared across the DAG. */
+type ReceiverSource = ReceiverEnriched['receiverSource'];
+
+/**
+ * DAG stage 4 fallback: used when `selectDispatch` is absent or returns null.
+ * Preserves pre-DAG dispatch semantics:
+ *   - 'constructor'         → constructor branch
+ *   - 'free'                → free branch (admits Swift/Kotlin class-target fast path)
+ *   - 'member' or undefined → owner-scoped branch
+ *
+ * `undefined` callForm MUST route through owner-scoped (not free) so bare
+ * identifiers without a classified shape do NOT trigger `resolveFreeCall`'s
+ * class-target fast path. Without a `receiverTypeName`, the owner-scoped
+ * branch falls through to `resolveModuleAliasedCall` + `singleCandidate`,
+ * matching legacy behavior where non-callable symbols (Class, Interface)
+ * null-route instead of producing spurious Constructor edges.
+ */
+const defaultDispatchDecision = (
+  callForm: 'free' | 'member' | 'constructor' | undefined,
+): DispatchDecision => {
+  if (callForm === 'constructor') return { primary: 'constructor' };
+  if (callForm === 'free') return { primary: 'free' };
+  return { primary: 'owner-scoped' };
+};
 import Parser from 'tree-sitter';
 import type { ResolutionContext } from './model/resolution-context.js';
 import { TIER_CONFIDENCE, type ResolutionTier } from './model/resolution-context.js';
@@ -32,7 +59,6 @@ import {
 } from './utils/call-analysis.js';
 import { buildTypeEnv, isSubclassOf } from './type-env.js';
 import type { ConstructorBinding, TypeEnvironment } from './type-env.js';
-import type { HeritageMap } from './model/heritage-map.js';
 import type { BindingAccumulator } from './binding-accumulator.js';
 import { getTreeSitterBufferSize } from './constants.js';
 import type {
@@ -42,14 +68,11 @@ import type {
   ExtractedFetchCall,
   FileConstructorBindings,
 } from './workers/parse-worker.js';
-import type { ExtractedHeritage } from './model/heritage-map.js';
 import { normalizeFetchURL, routeMatches } from './route-extractors/nextjs.js';
 import { extractTemplateComponents } from './vue-sfc-extractor.js';
 import { extractReturnTypeName, stripNullable } from './type-extractors/shared.js';
 import type { LiteralTypeInferrer } from './type-extractors/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
-import { extractParsedCallSite } from './call-sites/extract-language-call-site.js';
-import { lookupMethodByOwnerWithMRO } from './model/resolve.js';
 
 /** Per-file resolved type bindings for exported symbols.
  *  Populated during call processing, consumed by Phase 14 re-resolution pass. */
@@ -765,22 +788,26 @@ export const processCalls = async (
     // Extract heritage from query matches to build parentMap for buildTypeEnv.
     // Heritage-processor runs in PARALLEL, so graph edges don't exist when buildTypeEnv runs.
     const fileParentMap = new Map<string, string[]>();
-    for (const match of matches) {
-      const captureMap: Record<string, any> = {};
-      match.captures.forEach((c) => (captureMap[c.name] = c.node));
-      if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
-        const className: string = captureMap['heritage.class'].text;
-        const parentName: string = captureMap['heritage.extends'].text;
-        const extendsNode = captureMap['heritage.extends'];
-        const fieldDecl = extendsNode.parent;
-        if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name'))
-          continue;
-        let parents = fileParentMap.get(className);
-        if (!parents) {
-          parents = [];
-          fileParentMap.set(className, parents);
+    if (provider.heritageExtractor) {
+      for (const match of matches) {
+        const captureMap: Record<string, any> = {};
+        match.captures.forEach((c) => (captureMap[c.name] = c.node));
+        if (captureMap['heritage.class']) {
+          const heritageItems = provider.heritageExtractor.extract(captureMap, {
+            filePath: file.path,
+            language,
+          });
+          for (const item of heritageItems) {
+            if (item.kind === 'extends') {
+              let parents = fileParentMap.get(item.className);
+              if (!parents) {
+                parents = [];
+                fileParentMap.set(item.className, parents);
+              }
+              if (!parents.includes(item.parentName)) parents.push(item.parentName);
+            }
+          }
         }
-        if (!parents.includes(parentName)) parents.push(parentName);
       }
     }
     const parentMap: ReadonlyMap<string, readonly string[]> = fileParentMap;
@@ -910,74 +937,79 @@ export const processCalls = async (
       if (!captureMap['call']) return;
 
       const callNode = captureMap['call'];
-      const languageSeed = extractParsedCallSite(language, callNode);
-      if (languageSeed) {
-        if (provider.isBuiltInName(languageSeed.calledName)) return;
+      const callExtractor = provider.callExtractor;
 
-        const sourceId =
-          findEnclosingFunction(callNode, file.path, ctx, provider) ||
-          generateId('File', file.path);
-        const receiverName =
-          languageSeed.callForm === 'member' ? languageSeed.receiverName : undefined;
-        let receiverTypeName =
-          receiverName && typeEnv ? typeEnv.lookup(receiverName, callNode) : undefined;
+      // ── Language-specific call site (e.g. Java :: method references) ──
+      if (callExtractor) {
+        const langCallSite = callExtractor.extract(callNode, undefined);
+        if (langCallSite) {
+          if (provider.isBuiltInName(langCallSite.calledName)) return;
 
-        if (
-          receiverName !== undefined &&
-          receiverTypeName === undefined &&
-          languageSeed.callForm === 'member' &&
-          (language === 'java' || language === 'csharp' || language === 'kotlin')
-        ) {
-          const c0 = receiverName.charCodeAt(0);
-          if (c0 >= 65 && c0 <= 90) receiverTypeName = receiverName;
-        }
+          const sourceId =
+            findEnclosingFunction(callNode, file.path, ctx, provider) ||
+            generateId('File', file.path);
+          const receiverName =
+            langCallSite.callForm === 'member' ? langCallSite.receiverName : undefined;
+          let receiverTypeName =
+            receiverName && typeEnv ? typeEnv.lookup(receiverName, callNode) : undefined;
 
-        const resolved = resolveCallTarget(
-          {
-            calledName: languageSeed.calledName,
-            callForm: languageSeed.callForm,
-            ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
-            ...(receiverName !== undefined ? { receiverName } : {}),
-          },
-          file.path,
-          ctx,
-          undefined,
-          widenCache,
-          undefined,
-          heritageMap,
-        );
+          if (
+            langCallSite.typeAsReceiverHeuristic &&
+            receiverName !== undefined &&
+            receiverTypeName === undefined &&
+            langCallSite.callForm === 'member'
+          ) {
+            const c0 = receiverName.charCodeAt(0);
+            if (c0 >= 65 && c0 <= 90) receiverTypeName = receiverName;
+          }
 
-        if (!resolved) return;
-        graph.addRelationship({
-          id: generateId('CALLS', `${sourceId}:${languageSeed.calledName}->${resolved.nodeId}`),
-          sourceId,
-          targetId: resolved.nodeId,
-          type: 'CALLS',
-          confidence: resolved.confidence,
-          reason: resolved.reason,
-        });
-
-        if (heritageMap && languageSeed.callForm === 'member' && receiverTypeName) {
-          const implTargets = findInterfaceDispatchTargets(
-            languageSeed.calledName,
-            receiverTypeName,
+          const resolved = resolveCallTarget(
+            {
+              calledName: langCallSite.calledName,
+              callForm: langCallSite.callForm,
+              ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
+              ...(receiverName !== undefined ? { receiverName } : {}),
+            },
             file.path,
             ctx,
+            undefined,
+            widenCache,
+            undefined,
             heritageMap,
-            resolved.nodeId,
           );
-          for (const impl of implTargets) {
-            graph.addRelationship({
-              id: generateId('CALLS', `${sourceId}:${languageSeed.calledName}->${impl.nodeId}`),
-              sourceId,
-              targetId: impl.nodeId,
-              type: 'CALLS',
-              confidence: impl.confidence,
-              reason: impl.reason,
-            });
+
+          if (!resolved) return;
+          graph.addRelationship({
+            id: generateId('CALLS', `${sourceId}:${langCallSite.calledName}->${resolved.nodeId}`),
+            sourceId,
+            targetId: resolved.nodeId,
+            type: 'CALLS',
+            confidence: resolved.confidence,
+            reason: resolved.reason,
+          });
+
+          if (heritageMap && langCallSite.callForm === 'member' && receiverTypeName) {
+            const implTargets = findInterfaceDispatchTargets(
+              langCallSite.calledName,
+              receiverTypeName,
+              file.path,
+              ctx,
+              heritageMap,
+              resolved.nodeId,
+            );
+            for (const impl of implTargets) {
+              graph.addRelationship({
+                id: generateId('CALLS', `${sourceId}:${langCallSite.calledName}->${impl.nodeId}`),
+                sourceId,
+                targetId: impl.nodeId,
+                type: 'CALLS',
+                confidence: impl.confidence,
+                reason: impl.reason,
+              });
+            }
           }
+          return;
         }
-        return;
       }
 
       const nameNode = captureMap['call.name'];
@@ -985,6 +1017,28 @@ export const processCalls = async (
 
       const calledName = nameNode.text;
 
+      // Check heritage extractor for call-based heritage (e.g., Ruby include/extend/prepend)
+      if (provider.heritageExtractor?.extractFromCall) {
+        const heritageItems = provider.heritageExtractor.extractFromCall(
+          calledName,
+          captureMap['call'],
+          { filePath: file.path, language },
+        );
+        if (heritageItems !== null) {
+          for (const item of heritageItems) {
+            collectedHeritage.push({
+              filePath: file.path,
+              className: item.className,
+              parentName: item.parentName,
+              kind: item.kind,
+            });
+          }
+          return;
+        }
+      }
+
+      // Dispatch: route language-specific calls (properties, imports)
+      // Heritage routing is handled by heritageExtractor.extractFromCall above.
       const routed = callRouter?.(calledName, captureMap['call']);
       if (routed) {
         switch (routed.kind) {
@@ -992,17 +1046,6 @@ export const processCalls = async (
           case 'import':
             return;
 
-          case 'heritage':
-            for (const item of routed.items) {
-              collectedHeritage.push({
-                filePath: file.path,
-                className: item.enclosingClass,
-                parentName: item.mixinName,
-                kind: item.heritageKind,
-              });
-            }
-            return;
-
           case 'properties': {
             const fileId = generateId('File', file.path);
             const propEnclosingClassId = findEnclosingClassId(captureMap['call'], file.path);
@@ -1055,10 +1098,17 @@ export const processCalls = async (
 
       if (provider.isBuiltInName(calledName)) return;
 
-      const callForm = inferCallForm(callNode, nameNode);
-      const receiverName = callForm === 'member' ? extractReceiverName(nameNode) : undefined;
+      // --- DAG stage 2-3: classify-form + infer-receiver (shared defaults) ---
+      // These stages run the shared inference chain. Language providers can
+      // customize infer-receiver (stage 3) via the inferImplicitReceiver hook
+      // which runs AFTER this default chain (typed-binding → constructor-map →
+      // module-alias → class-as-receiver → mixed-chain), and selectDispatch
+      // (stage 4) which picks the resolver branch.
+      let callForm = inferCallForm(callNode, nameNode);
+      let receiverName = callForm === 'member' ? extractReceiverName(nameNode) : undefined;
       let receiverTypeName =
         receiverName && typeEnv ? typeEnv.lookup(receiverName, callNode) : undefined;
+      let receiverSource: ReceiverSource = receiverTypeName ? 'typed-binding' : 'none';
       // Phase P: virtual dispatch override — when the declared type is a base class but
       // the constructor created a known subclass, prefer the more specific type.
       // Checks per-file parentMap first, then falls back to globalParentMap for
@@ -1097,6 +1147,7 @@ export const processCalls = async (
               ctx.model.types.lookupClassByName(receiverTypeName).length > 0)
           ) {
             receiverTypeName = ctorType;
+            receiverSource = 'constructor-map';
           }
         }
       }
@@ -1105,10 +1156,14 @@ export const processCalls = async (
         const enclosingFunc = findEnclosingFunction(callNode, file.path, ctx, provider);
         const funcName = enclosingFunc ? extractFuncNameFromSourceId(enclosingFunc) : '';
         receiverTypeName = lookupReceiverType(receiverIndex, funcName, receiverName);
+        if (receiverTypeName) receiverSource = 'constructor-map';
       }
-      // Fall back to class-as-receiver for static method calls (e.g. UserService.find_user()).
-      // When the receiver name is not a variable in TypeEnv but resolves to a Class/Struct/Interface
-      // through the standard tiered resolution, use it directly as the receiver type.
+      // Fall back to class-as-receiver for static method calls (e.g. UserService.find_user(),
+      // Greetable.format()). When the receiver name is not a variable in TypeEnv but
+      // resolves to a class-like symbol (Class / Interface / Struct / Enum / Trait) via
+      // tiered resolution, use it directly as the receiver type. `Trait` is included so
+      // Ruby module class-method calls flow through the class-as-receiver path and reach
+      // the `selectDispatch` hook's singleton branch.
       if (!receiverTypeName && receiverName && callForm === 'member') {
         const typeResolved = ctx.resolve(receiverName, file.path);
         if (
@@ -1118,10 +1173,12 @@ export const processCalls = async (
               d.type === 'Class' ||
               d.type === 'Interface' ||
               d.type === 'Struct' ||
-              d.type === 'Enum',
+              d.type === 'Enum' ||
+              d.type === 'Trait',
           )
         ) {
           receiverTypeName = receiverName;
+          receiverSource = 'class-as-receiver';
         }
       }
       // Hoist sourceId so it's available for ACCESSES edge emission during chain walk.
@@ -1167,11 +1224,51 @@ export const processCalls = async (
                 makeAccessEmitter(graph, sourceId),
                 heritageMap,
               );
+              if (receiverTypeName) receiverSource = 'mixed-chain';
             }
           }
         }
       }
 
+      // --- DAG stage 3: infer-receiver (provider hook) ---
+      // Synthesize implicit receivers for languages that omit them (e.g., Ruby bare-call).
+      // This hook runs AFTER the shared inference chain so explicit receivers /
+      // typed bindings always take precedence. Output (if non-null) overlays onto
+      // the ReceiverEnriched for the next stage.
+      let dispatchHint: string | undefined;
+      if (provider.inferImplicitReceiver) {
+        const override = provider.inferImplicitReceiver({
+          calledName,
+          callForm,
+          receiverName,
+          receiverTypeName,
+          callNode,
+          filePath: file.path,
+        });
+        if (override) {
+          callForm = override.callForm;
+          receiverName = override.receiverName;
+          receiverTypeName = override.receiverTypeName;
+          receiverSource = override.receiverSource;
+          dispatchHint = override.hint;
+        }
+      }
+
+      // --- DAG stage 4: select-dispatch (provider hook + default fallback) ---
+      // Decide which resolver path to try first (primary) and fallback strategy.
+      // Language providers can customize dispatch via selectDispatch hook; all
+      // others use the shared defaultDispatchDecision. Always non-null after this
+      // block so downstream resolvers are table-driven.
+      const dispatchDecision: DispatchDecision =
+        provider.selectDispatch?.({
+          calledName,
+          callForm,
+          receiverName,
+          receiverTypeName,
+          receiverSource,
+          hint: dispatchHint,
+        }) ?? defaultDispatchDecision(callForm);
+
       // Build overload hints for languages with inferLiteralType (Java/Kotlin/C#/C++).
       // Only used when multiple candidates survive arity filtering — ~1-3% of calls.
       const langConfig = provider.typeConfig;
@@ -1193,6 +1290,7 @@ export const processCalls = async (
         widenCache,
         undefined,
         heritageMap,
+        dispatchDecision,
       );
 
       if (!resolved) return;
@@ -1731,11 +1829,20 @@ const resolveCallTarget = (
   widenCache?: WidenCache,
   preComputedArgTypes?: (string | undefined)[],
   heritageMap?: HeritageMap,
+  dispatchDecision?: DispatchDecision,
 ): ResolveResult | null => {
   const tiered = ctx.resolve(call.calledName, currentFile);
   if (!tiered) return null;
 
-  if (call.callForm === 'free') {
+  // DAG dispatch: use decision.primary to pick the resolver branch.
+  // Callers that own the DAG (processCalls + crossFile deferred paths)
+  // pass a decision; other callers use the shared default ladder.
+  // Language-specific primary / fallback / ancestryView overrides come from
+  // the provider's `selectDispatch` hook.
+  const decision = dispatchDecision ?? defaultDispatchDecision(call.callForm);
+  const primary = decision.primary;
+
+  if (primary === 'free') {
     return resolveFreeCall(
       call.calledName,
       currentFile,
@@ -1746,7 +1853,7 @@ const resolveCallTarget = (
       preComputedArgTypes,
     );
   }
-  if (call.callForm === 'constructor') {
+  if (primary === 'constructor') {
     return (
       resolveStaticCall(
         call.calledName,
@@ -1759,6 +1866,7 @@ const resolveCallTarget = (
       ) ?? singleCandidate(tiered, call.argCount, 'constructor')
     );
   }
+  // primary === 'owner-scoped'
   if (call.receiverTypeName) {
     // Skip the owner-scoped MRO path when the tiered pool has genuine
     // overload ambiguity that needs D1-D4+E handling, not D0.
@@ -1766,6 +1874,15 @@ const resolveCallTarget = (
       (!!overloadHints || !!preComputedArgTypes) &&
       countCallableCandidates(tiered.candidates, call.argCount, call.callForm) > 1;
     // Try owner-scoped (resolveMemberCall) then file-scoped (resolveMemberCallByFile).
+    // DAG: dispatchDecision.ancestryView selects instance vs singleton ancestry
+    // for kind-aware MRO strategies. Ruby `Account.log` flows via 'singleton'.
+    //
+    // Singleton-ancestry miss MUST NOT degrade to the file-scoped fallback:
+    // resolveMemberCallByFile matches by ownerId and would happily pick an
+    // instance method defined on the same class, leaking instance dispatch
+    // onto what was declared a class-method call. For singleton dispatch,
+    // a miss either null-routes or falls through to `decision.fallback`.
+    const singletonDispatch = decision.ancestryView === 'singleton';
     const memberResult =
       (!skipMember
         ? resolveMemberCall(
@@ -1775,18 +1892,21 @@ const resolveCallTarget = (
             ctx,
             heritageMap,
             call.argCount,
+            decision.ancestryView,
           )
         : null) ??
-      resolveMemberCallByFile(
-        call.calledName,
-        call.receiverTypeName,
-        currentFile,
-        ctx,
-        call.argCount,
-        call.callForm,
-        overloadHints,
-        preComputedArgTypes,
-      );
+      (singletonDispatch
+        ? null
+        : resolveMemberCallByFile(
+            call.calledName,
+            call.receiverTypeName,
+            currentFile,
+            ctx,
+            call.argCount,
+            call.callForm,
+            overloadHints,
+            preComputedArgTypes,
+          ));
     if (memberResult) return memberResult;
 
     // Module-alias narrowing runs as a FALLBACK, after owner/file-scoped
@@ -1822,7 +1942,26 @@ const resolveCallTarget = (
     // hierarchy. When the type is NOT in the index (PHP `mixed`, dynamic
     // types, unresolvable aliases), the scoped resolvers had nothing to
     // work with and singleCandidate is the correct last resort.
+    //
+    // DAG fallback override: when `select-dispatch` returned
+    // `fallback: 'free-arity-narrowed'` (today: Ruby implicit-self bare
+    // calls whose enclosing class doesn't define the method), fall through
+    // to free-call resolution instead of null-routing. This preserves
+    // existing free-call arity-narrowing heuristics for bare calls that
+    // happen to target methods on unrelated classes.
     if (typeResolves && typeResolves.candidates.length > 0) {
+      if (decision.fallback === 'free-arity-narrowed') {
+        const free = resolveFreeCall(
+          call.calledName,
+          currentFile,
+          ctx,
+          call.argCount,
+          tiered,
+          overloadHints,
+          preComputedArgTypes,
+        );
+        if (free) return free;
+      }
       return null; // null-route: type resolved, no candidate matched
     }
     return singleCandidate(tiered, call.argCount, call.callForm);
@@ -2018,6 +2157,13 @@ const resolveMethodByOwner = (
   ctx: ResolutionContext,
   heritageMap?: HeritageMap,
   argCount?: number,
+  /**
+   * DAG-sourced ancestry selector. `'singleton'` routes through
+   * `heritageMap.getSingletonAncestry(owner)` for class-method dispatch
+   * (Ruby `Account.log` via `extend LoggerMixin`). Default / undefined
+   * uses the walker's instance-dispatch behavior.
+   */
+  ancestryView?: 'instance' | 'singleton',
 ): { def: SymbolDefinition; tier: ResolutionTier } | undefined => {
   const typeResolved = ctx.resolve(receiverTypeName, filePath);
   if (!typeResolved) return undefined;
@@ -2046,6 +2192,14 @@ const resolveMethodByOwner = (
   let ambiguous = false;
   for (const candidate of typeResolved.candidates) {
     if (!CLASS_LIKE_TYPES.has(candidate.type)) continue;
+    // Singleton dispatch: when the DAG decision requested the singleton
+    // ancestry view, pass `heritageMap.getSingletonAncestry` as the walker's
+    // ancestry override. Kind-aware strategies (e.g. MroStrategy 'ruby-mixin')
+    // honor the override by scanning it linearly in place of their default walk.
+    const singletonOverride =
+      ancestryView === 'singleton' && canWalkMRO && heritageMap
+        ? heritageMap.getSingletonAncestry(candidate.nodeId).map((e) => e.parentId)
+        : undefined;
     const def = canWalkMRO
       ? lookupMethodByOwnerWithMRO(
           candidate.nodeId,
@@ -2054,6 +2208,7 @@ const resolveMethodByOwner = (
           ctx.model,
           mroStrategy,
           argCount,
+          singletonOverride,
         )
       : ctx.model.methods.lookupMethodByOwner(candidate.nodeId, methodName, argCount);
     if (!def) continue;
@@ -2108,6 +2263,7 @@ export const resolveMemberCall = (
   ctx: ResolutionContext,
   heritageMap?: HeritageMap,
   argCount?: number,
+  ancestryView?: 'instance' | 'singleton',
 ): ResolveResult | null => {
   const resolved = resolveMethodByOwner(
     ownerType,
@@ -2116,6 +2272,7 @@ export const resolveMemberCall = (
     ctx,
     heritageMap,
     argCount,
+    ancestryView,
   );
   if (!resolved) return null;
   return toResolveResult(resolved.def, resolved.tier);
diff --git a/gitnexus/src/core/ingestion/call-routing.ts b/gitnexus/src/core/ingestion/call-routing.ts
index 3922c0c89..f9e60df10 100644
--- a/gitnexus/src/core/ingestion/call-routing.ts
+++ b/gitnexus/src/core/ingestion/call-routing.ts
@@ -1,10 +1,14 @@
 /**
  * Shared Ruby call routing logic.
  *
- * Ruby expresses imports, heritage (mixins), and property definitions as
- * method calls rather than syntax-level constructs. This module provides a
- * routing function used by the CLI call-processor, CLI parse-worker, and
- * the web call-processor so that the classification logic lives in one place.
+ * Ruby expresses imports and property definitions as method calls rather
+ * than syntax-level constructs. This module provides a routing function
+ * used by the CLI call-processor, CLI parse-worker, and the web
+ * call-processor so that the classification logic lives in one place.
+ *
+ * Heritage (mixins: include/extend/prepend) was previously routed here
+ * but is now handled by heritageExtractor.extractFromCall before the
+ * call router runs.  The router still returns 'skip' for these calls.
  *
  * NOTE: This file is intentionally duplicated in gitnexus-web/ because the
  * two packages have separate build targets (Node native vs WASM/browser).
@@ -30,17 +34,10 @@ export type CallRouter = (calledName: string, callNode: SyntaxNode) => CallRouti
 
 export type RubyCallRouting =
   | { kind: 'import'; importPath: string; isRelative: boolean }
-  | { kind: 'heritage'; items: RubyHeritageItem[] }
   | { kind: 'properties'; items: RubyPropertyItem[] }
   | { kind: 'call' }
   | { kind: 'skip' };
 
-export interface RubyHeritageItem {
-  enclosingClass: string;
-  mixinName: string;
-  heritageKind: 'include' | 'extend' | 'prepend';
-}
-
 export type RubyAccessorType = 'attr_accessor' | 'attr_reader' | 'attr_writer';
 
 export interface RubyPropertyItem {
@@ -56,9 +53,6 @@ export interface RubyPropertyItem {
 const CALL_RESULT: RubyCallRouting = { kind: 'call' };
 const SKIP_RESULT: RubyCallRouting = { kind: 'skip' };
 
-/** Max depth for parent-walking loops to prevent pathological AST traversals */
-const MAX_PARENT_DEPTH = 50;
-
 // ── Routing function ────────────────────────────────────────────────────────
 
 /**
@@ -88,35 +82,12 @@ export function routeRubyCall(calledName: string, callNode: SyntaxNode): RubyCal
     return { kind: 'import', importPath, isRelative };
   }
 
-  // ── include / extend / prepend → heritage (mixin) ──────────────────────
+  // ── include / extend / prepend — heritage (now handled by heritageExtractor) ─
+  // Call-based heritage is intercepted by heritageExtractor.extractFromCall
+  // before the call router runs.  Return SKIP_RESULT so these calls don't
+  // fall through to normal call processing.
   if (calledName === 'include' || calledName === 'extend' || calledName === 'prepend') {
-    let enclosingClass: string | null = null;
-    let current = callNode.parent;
-    let depth = 0;
-    while (current && ++depth <= MAX_PARENT_DEPTH) {
-      if (current.type === 'class' || current.type === 'module') {
-        const nameNode = current.childForFieldName?.('name');
-        if (nameNode) {
-          enclosingClass = nameNode.text;
-          break;
-        }
-      }
-      current = current.parent;
-    }
-    if (!enclosingClass) return SKIP_RESULT;
-
-    const items: RubyHeritageItem[] = [];
-    const argList = callNode.childForFieldName?.('arguments');
-    for (const arg of argList?.children ?? []) {
-      if (arg.type === 'constant' || arg.type === 'scope_resolution') {
-        items.push({
-          enclosingClass,
-          mixinName: arg.text,
-          heritageKind: calledName as 'include' | 'extend' | 'prepend',
-        });
-      }
-    }
-    return items.length > 0 ? { kind: 'heritage', items } : SKIP_RESULT;
+    return SKIP_RESULT;
   }
 
   // ── attr_accessor / attr_reader / attr_writer → property definitions ───
diff --git a/gitnexus/src/core/ingestion/call-sites/extract-language-call-site.ts b/gitnexus/src/core/ingestion/call-sites/extract-language-call-site.ts
deleted file mode 100644
index feed2cd70..000000000
--- a/gitnexus/src/core/ingestion/call-sites/extract-language-call-site.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-/** Non-generic @call shapes → { calledName, callForm, receiverName? } (used from call-processor / parse-worker). */
-
-import { SupportedLanguages } from '../../../config/supported-languages.js';
-import type { SyntaxNode } from '../utils/ast-helpers.js';
-import { parseJavaMethodReference } from './java.js';
-
-export type ParsedCallSite = {
-  calledName: string;
-  callForm: 'free' | 'member' | 'constructor';
-  receiverName?: string;
-};
-
-/** Non-null → seed replaces @call.name; null → use @call.name + inferCallForm / extractReceiverName. */
-export function extractParsedCallSite(
-  language: SupportedLanguages,
-  callNode: SyntaxNode,
-): ParsedCallSite | null {
-  switch (language) {
-    case SupportedLanguages.Java:
-      if (callNode.type === 'method_reference') {
-        const parsed = parseJavaMethodReference(callNode);
-        if (!parsed) return null;
-        return {
-          calledName: parsed.calledName,
-          callForm: parsed.callForm,
-          ...(parsed.receiverName !== undefined ? { receiverName: parsed.receiverName } : {}),
-        };
-      }
-      return null;
-    default:
-      return null;
-  }
-}
diff --git a/gitnexus/src/core/ingestion/call-sites/java.ts b/gitnexus/src/core/ingestion/call-sites/java.ts
deleted file mode 100644
index e22c71cca..000000000
--- a/gitnexus/src/core/ingestion/call-sites/java.ts
+++ /dev/null
@@ -1,41 +0,0 @@
-/** Java `method_reference` (`::`) nodes (tree-sitter-java). `super::` still lacks TypeEnv receiver typing. */
-
-import type { SyntaxNode } from '../utils/ast-helpers.js';
-
-export type ParsedJavaMethodReference = {
-  calledName: string;
-  callForm: 'member' | 'constructor';
-  receiverName?: string;
-};
-
-/** Parse `expr::method`, `Type::new`, `this::m`, `super::m`. */
-export const parseJavaMethodReference = (
-  callNode: SyntaxNode,
-): ParsedJavaMethodReference | null => {
-  if (callNode.type !== 'method_reference') return null;
-
-  const recv = callNode.namedChild(0);
-  if (!recv) return null;
-
-  for (const c of callNode.children) {
-    if (c.type === 'new') {
-      if (recv.type !== 'identifier') return null;
-      return { calledName: recv.text, callForm: 'constructor' };
-    }
-  }
-
-  const rhs = callNode.child(callNode.childCount - 1);
-  if (!rhs || rhs.type !== 'identifier') return null;
-  const methodName = rhs.text;
-
-  if (recv.type === 'identifier') {
-    return { calledName: methodName, callForm: 'member', receiverName: recv.text };
-  }
-  if (recv.type === 'this') {
-    return { calledName: methodName, callForm: 'member', receiverName: 'this' };
-  }
-  if (recv.type === 'super') {
-    return { calledName: methodName, callForm: 'member', receiverName: 'super' };
-  }
-  return null;
-};
diff --git a/gitnexus/src/core/ingestion/call-types.ts b/gitnexus/src/core/ingestion/call-types.ts
new file mode 100644
index 000000000..b42ecbf16
--- /dev/null
+++ b/gitnexus/src/core/ingestion/call-types.ts
@@ -0,0 +1,177 @@
+// gitnexus/src/core/ingestion/call-types.ts
+
+/**
+ * Types for the language-agnostic call extraction pipeline.
+ *
+ * Mirrors method-types.ts / field-types.ts: defines the domain interfaces
+ * consumed by createCallExtractor() and the per-language configs.
+ */
+
+import type { SupportedLanguages } from 'gitnexus-shared';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+import type { MixedChainStep } from './utils/call-analysis.js';
+
+// ---------------------------------------------------------------------------
+// Extracted result
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-node call extraction result.  The parse worker enriches this with
+ * file-level context (filePath, sourceId, TypeEnv lookups, arg types) to
+ * produce the final `ExtractedCall` that enters the resolution pipeline.
+ */
+export interface ExtractedCallSite {
+  calledName: string;
+  callForm?: 'free' | 'member' | 'constructor';
+  receiverName?: string;
+  argCount?: number;
+  /** Unified mixed chain for complex receivers (field + call chains). */
+  receiverMixedChain?: MixedChainStep[];
+  /** When true, the type-as-receiver heuristic applies: if receiverName
+   *  starts with an uppercase letter and has no TypeEnv binding, treat it
+   *  as a type name (e.g. Java `User::getName`). */
+  typeAsReceiverHeuristic?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Extractor interface (produced by createCallExtractor)
+// ---------------------------------------------------------------------------
+
+export interface CallExtractor {
+  readonly language: SupportedLanguages;
+  /**
+   * Extract a call site from captured AST nodes.
+   *
+   * @param callNode     The @call capture (call_expression, method_invocation, …)
+   * @param callNameNode The @call.name capture (identifier inside the call).
+   *                     May be undefined when the call shape has no name capture
+   *                     (e.g. Java method_reference via `::`).
+   * @returns Extracted call site, or null when no call can be derived.
+   */
+  extract(callNode: SyntaxNode, callNameNode: SyntaxNode | undefined): ExtractedCallSite | null;
+}
+
+// ---------------------------------------------------------------------------
+// Config interface (one per language / language group)
+// ---------------------------------------------------------------------------
+
+export interface CallExtractionConfig {
+  language: SupportedLanguages;
+
+  /**
+   * Language-specific call site extraction.  Called **before** the generic
+   * path.  If it returns non-null, the generic `inferCallForm` /
+   * `extractReceiverName` path is skipped entirely.
+   *
+   * Use this for call shapes that don't follow the standard `@call` /
+   * `@call.name` pattern (e.g. Java `method_reference` via `::`).
+   */
+  extractLanguageCallSite?: (callNode: SyntaxNode) => ExtractedCallSite | null;
+
+  /**
+   * Whether the type-as-receiver heuristic applies for this language.
+   * When true and the receiver name starts with an uppercase letter,
+   * the receiver is treated as a type name when no TypeEnv binding exists.
+   *
+   * Applies to JVM and C# languages where `Type.method()` and `Type::method`
+   * are common patterns.
+   */
+  typeAsReceiverHeuristic?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Call-resolution DAG types
+// ---------------------------------------------------------------------------
+//
+// The call-resolution pipeline is a typed DAG:
+//
+//   extract-call  ──▶  classify-form  ──▶  infer-receiver  ──▶  select-dispatch  ──▶  resolve-target  ──▶  emit-edge
+//
+// Provider hooks plug in at infer-receiver and select-dispatch; shared stages
+// stay language-agnostic. Stages 1-2 run in the parse worker; stages 3-6 run
+// on the main thread. DAG-internal types below are main-thread-only and never
+// serialize to the graph.
+
+/**
+ * DAG stage 3 output: call record with receiver type and source discriminant.
+ *
+ * `receiverTypeName` is resolved via TypeEnv → constructor-map → class-as-receiver →
+ * mixed-chain, or synthesized by `inferImplicitReceiver`. `receiverSource` tags
+ * which path won and drives MRO strategy selection in stage 4.
+ *
+ * Invariants:
+ * - `receiverSource` MUST match how `receiverTypeName` was resolved; every
+ *   discriminant must have a live reader and writer.
+ * - `hint` is opaque to shared stages; only the same provider's `selectDispatch` reads it.
+ *
+ * @see language-provider.ts § inferImplicitReceiver, selectDispatch
+ */
+export interface ReceiverEnriched {
+  readonly calledName: string;
+  readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+  readonly receiverName: string | undefined;
+  readonly receiverTypeName: string | undefined;
+  readonly receiverSource:
+    | 'none'
+    | 'typed-binding'
+    | 'constructor-map'
+    | 'class-as-receiver'
+    | 'mixed-chain'
+    | 'implicit-self';
+  /** Free-form hint from the provider hook; opaque to shared stages. */
+  readonly hint?: string;
+}
+
+/**
+ * Provider hook output for `LanguageProvider.inferImplicitReceiver` (DAG stage 3).
+ *
+ * Overlay applied to `ReceiverEnriched` when an implicit receiver is synthesized.
+ * Ruby example: bare `serialize` inside `Account#call_serialize` →
+ * `{ callForm: 'member', receiverName: 'self', receiverTypeName: 'Account',
+ *   receiverSource: 'implicit-self', hint: 'instance' }`
+ *
+ * Invariants:
+ * - `receiverSource` is always `'implicit-self'` — the only variant this type produces.
+ * - `callForm` is always `'member'` — the rewrite converts bare-call to method invocation.
+ * - `hint` is opaque to shared stages; consumed by the same language's `selectDispatch`.
+ */
+export interface ImplicitReceiverOverride {
+  readonly callForm: 'free' | 'member' | 'constructor';
+  readonly receiverName: string;
+  readonly receiverTypeName: string;
+  readonly receiverSource: Extract<ReceiverEnriched['receiverSource'], 'implicit-self'>;
+  /** Free-form language tag (e.g. Ruby sets 'singleton' for `def self.foo`
+   *  method bodies). Consumed by the same language's `selectDispatch` hook. */
+  readonly hint?: string;
+}
+
+/**
+ * DAG stage 4 output: dispatch strategy for resolving the target method.
+ *
+ * Encodes which resolver branch to try first and an optional fallback.
+ * Stage 5 delegates to `resolveMemberCall`, `resolveFreeCall`, or
+ * `resolveStaticCall` based on `primary`.
+ *
+ * - `primary`: `'owner-scoped'` = MRO walk, `'free'` = arity-tiered global lookup,
+ *   `'constructor'` = type instantiation.
+ * - `fallback`: Only `'free-arity-narrowed'` exists; used by Ruby implicit-self
+ *   to degrade to arity-tiered free lookup when the MRO walk misses.
+ * - `ancestryView`: Ruby `'ruby-mixin'` only. `'singleton'` walks extend providers
+ *   only; a miss NEVER falls through to file-scoped lookup (enforced in
+ *   resolveCallTarget). `'instance'` is the default.
+ *
+ * Common patterns:
+ *   - `{primary: 'constructor'}` — constructor call
+ *   - `{primary: 'owner-scoped'}` — member call with known type
+ *   - `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'instance'}` — Ruby implicit-self
+ *   - `{primary: 'owner-scoped', ancestryView: 'singleton'}` — Ruby class-method call
+ *
+ * @see language-provider.ts § selectDispatch
+ * @see call-processor.ts § defaultDispatchDecision, resolveCallTarget
+ */
+export interface DispatchDecision {
+  readonly primary: 'owner-scoped' | 'free' | 'constructor';
+  readonly fallback?: 'free-arity-narrowed';
+  readonly ancestryView?: 'instance' | 'singleton';
+  readonly hint?: string;
+}
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts b/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts
new file mode 100644
index 000000000..fcc1a22bf
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts
@@ -0,0 +1,15 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const cClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.C,
+  typeDeclarationNodes: ['struct_specifier', 'enum_specifier'],
+};
+
+export const cppClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.CPlusPlus,
+  typeDeclarationNodes: ['class_specifier', 'struct_specifier', 'enum_specifier'],
+  ancestorScopeNodeTypes: ['namespace_definition', 'class_specifier', 'struct_specifier'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/csharp.ts b/gitnexus/src/core/ingestion/class-extractors/configs/csharp.ts
new file mode 100644
index 000000000..59b7be617
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/csharp.ts
@@ -0,0 +1,24 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/csharp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const csharpClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.CSharp,
+  typeDeclarationNodes: [
+    'class_declaration',
+    'interface_declaration',
+    'struct_declaration',
+    'enum_declaration',
+    'record_declaration',
+  ],
+  fileScopeNodeTypes: ['file_scoped_namespace_declaration'],
+  ancestorScopeNodeTypes: [
+    'namespace_declaration',
+    'class_declaration',
+    'interface_declaration',
+    'struct_declaration',
+    'enum_declaration',
+    'record_declaration',
+  ],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/dart.ts b/gitnexus/src/core/ingestion/class-extractors/configs/dart.ts
new file mode 100644
index 000000000..c46c05533
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/dart.ts
@@ -0,0 +1,10 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/dart.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const dartClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Dart,
+  typeDeclarationNodes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+  ancestorScopeNodeTypes: ['class_definition', 'extension_declaration', 'enum_declaration'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/go.ts b/gitnexus/src/core/ingestion/class-extractors/configs/go.ts
new file mode 100644
index 000000000..58dade9fa
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/go.ts
@@ -0,0 +1,21 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/go.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const goClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Go,
+  typeDeclarationNodes: ['type_declaration'],
+  fileScopeNodeTypes: ['package_clause'],
+  extractName(node) {
+    const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
+    return typeSpec?.childForFieldName('name')?.text;
+  },
+  extractType(node) {
+    const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
+    const typeNode = typeSpec?.childForFieldName('type');
+    if (typeNode?.type === 'struct_type') return 'Struct';
+    if (typeNode?.type === 'interface_type') return 'Interface';
+    return undefined;
+  },
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/jvm.ts b/gitnexus/src/core/ingestion/class-extractors/configs/jvm.ts
new file mode 100644
index 000000000..fbd22f545
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/jvm.ts
@@ -0,0 +1,40 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/jvm.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+// ---------------------------------------------------------------------------
+// Java
+// ---------------------------------------------------------------------------
+
+export const javaClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Java,
+  typeDeclarationNodes: [
+    'class_declaration',
+    'interface_declaration',
+    'enum_declaration',
+    'record_declaration',
+  ],
+  fileScopeNodeTypes: ['package_declaration'],
+  ancestorScopeNodeTypes: [
+    'class_declaration',
+    'interface_declaration',
+    'enum_declaration',
+    'record_declaration',
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Kotlin
+// ---------------------------------------------------------------------------
+
+export const kotlinClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Kotlin,
+  typeDeclarationNodes: ['class_declaration', 'object_declaration', 'companion_object'],
+  fileScopeNodeTypes: ['package_header'],
+  ancestorScopeNodeTypes: ['class_declaration', 'object_declaration', 'companion_object'],
+  extractType(node) {
+    if (node.type !== 'class_declaration') return undefined;
+    return node.children.some((child) => child?.text === 'interface') ? 'Interface' : 'Class';
+  },
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/php.ts b/gitnexus/src/core/ingestion/class-extractors/configs/php.ts
new file mode 100644
index 000000000..850b415b4
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/php.ts
@@ -0,0 +1,10 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/php.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const phpClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.PHP,
+  typeDeclarationNodes: ['class_declaration', 'interface_declaration', 'enum_declaration'],
+  ancestorScopeNodeTypes: ['namespace_definition'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/python.ts b/gitnexus/src/core/ingestion/class-extractors/configs/python.ts
new file mode 100644
index 000000000..42761468e
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/python.ts
@@ -0,0 +1,10 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/python.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const pythonClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Python,
+  typeDeclarationNodes: ['class_definition'],
+  ancestorScopeNodeTypes: ['class_definition'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/ruby.ts b/gitnexus/src/core/ingestion/class-extractors/configs/ruby.ts
new file mode 100644
index 000000000..2c4c711bd
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/ruby.ts
@@ -0,0 +1,10 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/ruby.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const rubyClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Ruby,
+  typeDeclarationNodes: ['class'],
+  ancestorScopeNodeTypes: ['module', 'class'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/rust.ts b/gitnexus/src/core/ingestion/class-extractors/configs/rust.ts
new file mode 100644
index 000000000..7f3873802
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/rust.ts
@@ -0,0 +1,10 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/rust.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const rustClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Rust,
+  typeDeclarationNodes: ['struct_item', 'enum_item'],
+  ancestorScopeNodeTypes: ['mod_item', 'struct_item', 'enum_item'],
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/swift.ts b/gitnexus/src/core/ingestion/class-extractors/configs/swift.ts
new file mode 100644
index 000000000..713a02496
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/swift.ts
@@ -0,0 +1,17 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/swift.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+export const swiftClassConfig: ClassExtractionConfig = {
+  language: SupportedLanguages.Swift,
+  typeDeclarationNodes: ['class_declaration', 'protocol_declaration'],
+  ancestorScopeNodeTypes: ['class_declaration', 'protocol_declaration'],
+  extractType(node) {
+    if (node.type === 'protocol_declaration') return 'Interface';
+    if (node.type !== 'class_declaration') return undefined;
+    if (node.children.some((child) => child?.text === 'struct')) return 'Struct';
+    if (node.children.some((child) => child?.text === 'enum')) return 'Enum';
+    return 'Class';
+  },
+};
diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/typescript-javascript.ts b/gitnexus/src/core/ingestion/class-extractors/configs/typescript-javascript.ts
new file mode 100644
index 000000000..b2262432d
--- /dev/null
+++ b/gitnexus/src/core/ingestion/class-extractors/configs/typescript-javascript.ts
@@ -0,0 +1,34 @@
+// gitnexus/src/core/ingestion/class-extractors/configs/typescript-javascript.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ClassExtractionConfig } from '../../class-types.js';
+
+const shared: Omit<ClassExtractionConfig, 'language'> = {
+  typeDeclarationNodes: [
+    'class_declaration',
+    'abstract_class_declaration',
+    'interface_declaration',
+    'enum_declaration',
+  ],
+  ancestorScopeNodeTypes: [
+    'class_declaration',
+    'abstract_class_declaration',
+    'interface_declaration',
+    'enum_declaration',
+  ],
+};
+
+export const typescriptClassConfig: ClassExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.TypeScript,
+};
+
+export const javascriptClassConfig: ClassExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.JavaScript,
+};
+
+export const vueClassConfig: ClassExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.Vue,
+};
diff --git a/gitnexus/src/core/ingestion/emit-references.ts b/gitnexus/src/core/ingestion/emit-references.ts
new file mode 100644
index 000000000..1d2c4db5b
--- /dev/null
+++ b/gitnexus/src/core/ingestion/emit-references.ts
@@ -0,0 +1,299 @@
+/**
+ * Phase 5 of the RFC #909 ingestion lifecycle: drain `ReferenceIndex`
+ * into the knowledge graph as labeled edges with `confidence` and
+ * `evidence` properties (Ring 2 PKG #925).
+ *
+ * The resolution phase (future PR) writes `Reference` records into
+ * `model.scopes.referenceSites`-derived `ReferenceIndex`; this module
+ * materializes those records as `GraphRelationship`s via
+ * `graph.addRelationship`. Every emitted edge carries:
+ *
+ *   - `type`: one of `'CALLS' | 'ACCESSES' | 'INHERITS' | 'USES'`
+ *     (mapped from `Reference.kind` — `'read'` and `'write'` both route
+ *     to `ACCESSES`; `'type-reference'` and `'import-use'` route to
+ *     `USES`; `'call'` stays `CALLS`; `'inherits'` stays `INHERITS`).
+ *   - `confidence`: the pre-computed confidence from the Reference record.
+ *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
+ *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
+ *     property (see `GraphRelationship.evidence` in gitnexus-shared),
+ *     so queries that don't know about it are unaffected.
+ *   - `step`: carries the reference's access-kind discriminant when
+ *     available (`1` for read, `2` for write) so `ACCESSES` edges retain
+ *     the read/write distinction without forcing a new edge type.
+ *
+ * ## Optional scope-tree flush
+ *
+ * When `INGESTION_EMIT_SCOPES=1` is set, this module also emits:
+ *
+ *   - `Scope` nodes for every `Scope` in the tree
+ *   - `CONTAINS` edges from parent scope to child scope
+ *   - `DEFINES` edges from scope to its `ownedDefs` members
+ *   - `IMPORTS` edges from scope to `targetModuleScope` of each finalized
+ *     `ImportEdge` that carries one
+ *
+ * Off by default — existing queries that don't know about `Scope` nodes
+ * continue to work, and the storage cost is opt-in.
+ *
+ * ## Source-of-truth: the caller def for a reference
+ *
+ * A `Reference` says "some code inside `fromScope` references `toDef`".
+ * The graph wants `(callerNodeId, calleeNodeId)`. We resolve the caller
+ * by walking up the scope tree from `fromScope` until we find a scope
+ * whose `ownedDefs` contains a Function-like def. If no such ancestor
+ * exists, the edge is attributed to the first def owned by the innermost
+ * ancestor scope, and if THAT produces nothing either the edge is
+ * skipped (with a count returned in `EmitStats.skippedNoCaller`).
+ */
+
+import type {
+  NodeLabel,
+  RelationshipType,
+  Reference,
+  ReferenceIndex,
+  ResolutionEvidence,
+  Scope,
+  ScopeId,
+  SymbolDefinition,
+} from 'gitnexus-shared';
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+export interface EmitStats {
+  readonly edgesEmitted: number;
+  /** References dropped because no caller def could be resolved. */
+  readonly skippedNoCaller: number;
+  /** References dropped because `toDef` was not found in the DefIndex. */
+  readonly skippedMissingTarget: number;
+  /** Scope nodes emitted — `0` unless `INGESTION_EMIT_SCOPES=1`. */
+  readonly scopeNodesEmitted: number;
+  /** Scope-tree structural edges emitted — `0` unless `INGESTION_EMIT_SCOPES=1`. */
+  readonly scopeEdgesEmitted: number;
+}
+
+export interface EmitReferencesInput {
+  readonly graph: KnowledgeGraph;
+  readonly scopes: ScopeResolutionIndexes;
+  readonly referenceIndex: ReferenceIndex;
+  /** Human-consumable label for the `reason` prefix. Defaults to `'scope-resolution'`. */
+  readonly sourceLabel?: string;
+}
+
+/**
+ * Drain `referenceIndex.bySourceScope` into graph edges.
+ *
+ * The scope-tree flush is controlled separately by
+ * `INGESTION_EMIT_SCOPES` — callers can run `emitReferencesToGraph`
+ * without scope-node emission or layer the two calls as needed.
+ */
+export function emitReferencesToGraph(input: EmitReferencesInput): EmitStats {
+  const { graph, scopes, referenceIndex } = input;
+  const sourceLabel = input.sourceLabel ?? 'scope-resolution';
+
+  let edgesEmitted = 0;
+  let skippedNoCaller = 0;
+  let skippedMissingTarget = 0;
+
+  for (const [fromScope, refs] of referenceIndex.bySourceScope) {
+    for (const ref of refs) {
+      const targetDef = scopes.defs.get(ref.toDef);
+      if (targetDef === undefined) {
+        skippedMissingTarget++;
+        continue;
+      }
+      const callerId = resolveCallerNodeId(fromScope, scopes);
+      if (callerId === undefined) {
+        skippedNoCaller++;
+        continue;
+      }
+      graph.addRelationship(buildRelationship(ref, callerId, targetDef, sourceLabel));
+      edgesEmitted++;
+    }
+  }
+
+  const scopeStats = isScopeEmissionEnabled()
+    ? emitScopeGraph({ graph, scopes })
+    : { scopeNodesEmitted: 0, scopeEdgesEmitted: 0 };
+
+  return { edgesEmitted, skippedNoCaller, skippedMissingTarget, ...scopeStats };
+}
+
+/**
+ * Emit `Scope` nodes + `CONTAINS`/`DEFINES`/`IMPORTS` edges representing
+ * the lexical scope tree itself. Skipped unless `INGESTION_EMIT_SCOPES=1`
+ * at the public entry point; exported here for tests that want to
+ * exercise the path directly.
+ */
+export function emitScopeGraph(input: {
+  readonly graph: KnowledgeGraph;
+  readonly scopes: ScopeResolutionIndexes;
+}): { readonly scopeNodesEmitted: number; readonly scopeEdgesEmitted: number } {
+  const { graph, scopes } = input;
+  let scopeNodesEmitted = 0;
+  let scopeEdgesEmitted = 0;
+
+  for (const scope of scopes.scopeTree.byId.values()) {
+    graph.addNode({
+      id: scope.id,
+      label: 'CodeElement' as NodeLabel, // the generic bucket for non-symbol graph nodes
+      properties: {
+        name: scope.kind,
+        filePath: scope.filePath,
+        startLine: scope.range.startLine,
+        endLine: scope.range.endLine,
+        description: `Scope: ${scope.kind}`,
+      } as unknown as Parameters<KnowledgeGraph['addNode']>[0]['properties'],
+    });
+    scopeNodesEmitted++;
+
+    if (scope.parent !== null) {
+      graph.addRelationship({
+        id: `rel:contains:${scope.parent}->${scope.id}`,
+        sourceId: scope.parent,
+        targetId: scope.id,
+        type: 'CONTAINS',
+        confidence: 1,
+        reason: 'scope-tree parent/child',
+      });
+      scopeEdgesEmitted++;
+    }
+
+    for (const def of scope.ownedDefs) {
+      graph.addRelationship({
+        id: `rel:defines:${scope.id}->${def.nodeId}`,
+        sourceId: scope.id,
+        targetId: def.nodeId,
+        type: 'DEFINES',
+        confidence: 1,
+        reason: 'scope.ownedDefs',
+      });
+      scopeEdgesEmitted++;
+    }
+  }
+
+  for (const [scopeId, edges] of scopes.imports) {
+    for (const edge of edges) {
+      if (edge.targetModuleScope === undefined) continue;
+      graph.addRelationship({
+        id: `rel:imports:${scopeId}->${edge.targetModuleScope}:${edge.localName}`,
+        sourceId: scopeId,
+        targetId: edge.targetModuleScope,
+        type: 'IMPORTS',
+        confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,
+        reason: `import ${edge.kind} ${edge.localName}`,
+      });
+      scopeEdgesEmitted++;
+    }
+  }
+
+  return { scopeNodesEmitted, scopeEdgesEmitted };
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+/** Accepted truthy values for `INGESTION_EMIT_SCOPES`. */
+const TRUTHY: ReadonlySet<string> = new Set(['true', '1', 'yes']);
+
+function isScopeEmissionEnabled(): boolean {
+  const raw = process.env['INGESTION_EMIT_SCOPES'];
+  if (raw === undefined) return false;
+  return TRUTHY.has(raw.trim().toLowerCase());
+}
+
+/**
+ * Walk up from `startScope` looking for the first ancestor scope whose
+ * `ownedDefs` contains a Function-like def (Function / Method /
+ * Constructor). Fall back to the innermost ancestor's first `ownedDef`
+ * if none is found; return `undefined` if all ancestors have no defs.
+ */
+function resolveCallerNodeId(
+  startScope: ScopeId,
+  scopes: ScopeResolutionIndexes,
+): string | undefined {
+  const tree = scopes.scopeTree;
+  let current: ScopeId | null = startScope;
+  const visited = new Set<ScopeId>();
+  let firstOwnedFallback: string | undefined;
+
+  while (current !== null) {
+    if (visited.has(current)) break;
+    visited.add(current);
+
+    const scope: Scope | undefined = tree.getScope(current);
+    if (scope === undefined) break;
+
+    // Prefer a Function-like owner.
+    const fnDef = scope.ownedDefs.find((d) => isFunctionLike(d.type));
+    if (fnDef !== undefined) return fnDef.nodeId;
+
+    // Stash the first owned def we see as a conservative fallback.
+    if (firstOwnedFallback === undefined && scope.ownedDefs.length > 0) {
+      firstOwnedFallback = scope.ownedDefs[0]!.nodeId;
+    }
+
+    current = scope.parent;
+  }
+
+  return firstOwnedFallback;
+}
+
+function isFunctionLike(type: NodeLabel): boolean {
+  return type === 'Function' || type === 'Method' || type === 'Constructor';
+}
+
+function buildRelationship(
+  ref: Reference,
+  callerId: string,
+  targetDef: SymbolDefinition,
+  sourceLabel: string,
+): Parameters<KnowledgeGraph['addRelationship']>[0] {
+  const type = mapKindToType(ref.kind);
+  const reason = `${sourceLabel}: ${ref.kind} | confidence ${ref.confidence.toFixed(3)}`;
+  // `step` encodes read/write discriminator for ACCESSES edges (1=read, 2=write).
+  // Other kinds omit `step`.
+  const step = ref.kind === 'read' ? 1 : ref.kind === 'write' ? 2 : undefined;
+  return {
+    id: `rel:${type}:${callerId}->${targetDef.nodeId}:${ref.atRange.startLine}:${ref.atRange.startCol}`,
+    sourceId: callerId,
+    targetId: targetDef.nodeId,
+    type,
+    confidence: ref.confidence,
+    reason,
+    evidence: ref.evidence.map(serializeEvidence),
+    ...(step !== undefined ? { step } : {}),
+  };
+}
+
+/**
+ * Map a `Reference.kind` to an existing `RelationshipType`. Read/write
+ * both fold into `ACCESSES`; `type-reference` + `import-use` both fold
+ * into `USES`. This keeps the graph schema additive — no new
+ * RelationshipType values are introduced by this module.
+ */
+function mapKindToType(kind: Reference['kind']): RelationshipType {
+  switch (kind) {
+    case 'call':
+      return 'CALLS';
+    case 'read':
+    case 'write':
+      return 'ACCESSES';
+    case 'inherits':
+      return 'INHERITS';
+    case 'type-reference':
+    case 'import-use':
+      return 'USES';
+  }
+}
+
+function serializeEvidence(e: ResolutionEvidence): {
+  readonly kind: string;
+  readonly weight: number;
+  readonly note?: string;
+} {
+  return {
+    kind: e.kind,
+    weight: e.weight,
+    ...(e.note !== undefined ? { note: e.note } : {}),
+  };
+}
diff --git a/gitnexus/src/core/ingestion/field-types.ts b/gitnexus/src/core/ingestion/field-types.ts
index 8dd1a9f6c..7867ae8a6 100644
--- a/gitnexus/src/core/ingestion/field-types.ts
+++ b/gitnexus/src/core/ingestion/field-types.ts
@@ -1,7 +1,7 @@
 // gitnexus/src/core/ingestion/field-types.ts
 
 import type { TypeEnvironment } from './type-env.js';
-import type { SymbolTableReader } from './model/symbol-table.js';
+import type { SymbolTableReader } from './model/index.js';
 import { SupportedLanguages } from 'gitnexus-shared';
 
 /**
diff --git a/gitnexus/src/core/ingestion/finalize-orchestrator.ts b/gitnexus/src/core/ingestion/finalize-orchestrator.ts
new file mode 100644
index 000000000..8541e58aa
--- /dev/null
+++ b/gitnexus/src/core/ingestion/finalize-orchestrator.ts
@@ -0,0 +1,196 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `gitnexus-shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+
+import type {
+  BindingRef,
+  FinalizeFile,
+  FinalizeHooks,
+  ParsedFile,
+  Scope,
+  ScopeId,
+  SymbolDefinition,
+  WorkspaceIndex,
+} from 'gitnexus-shared';
+import {
+  buildDefIndex,
+  buildMethodDispatchIndex,
+  buildModuleScopeIndex,
+  buildQualifiedNameIndex,
+  buildScopeTree,
+  finalize,
+} from 'gitnexus-shared';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+
+// ─── Public entry point ─────────────────────────────────────────────────────
+
+/**
+ * Options forwarded to the orchestrator. All fields optional so callers
+ * that don't yet have per-language hooks (today) get sensible defaults;
+ * #922 will populate `hooks.resolveImportTarget` + friends per language.
+ */
+export interface FinalizeOrchestratorOptions {
+  /**
+   * Hooks forwarded to shared `finalize()`. Any omitted field gets a
+   * no-op default: unresolved targets, empty wildcard expansion, append
+   * merge for bindings.
+   */
+  readonly hooks?: Partial<FinalizeHooks>;
+  /**
+   * Opaque workspace context forwarded to hooks. `undefined` today; Ring
+   * 2 PKG #922 populates this with a real cross-file index for the
+   * per-language resolvers.
+   */
+  readonly workspaceIndex?: WorkspaceIndex;
+}
+
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export function finalizeScopeModel(
+  parsedFiles: readonly ParsedFile[],
+  options: FinalizeOrchestratorOptions = {},
+): ScopeResolutionIndexes {
+  const hooks = withDefaultHooks(options.hooks ?? {});
+  const workspaceIndex: WorkspaceIndex = options.workspaceIndex ?? undefined;
+
+  // ── Step 1: Shared finalize — runs SCC-aware cross-file link + binding
+  // materialization. Returns linked imports + merged bindings per module
+  // scope + SCC condensation + stats.
+  const finalizeInput = {
+    files: parsedFiles.map(toFinalizeFile),
+    workspaceIndex,
+  };
+  const finalizeOut = finalize(finalizeInput, hooks);
+
+  // ── Step 2: Workspace-wide indexes built from the per-file unions.
+  // These are pure aggregations — no algorithm beyond what the builders
+  // in gitnexus-shared already encapsulate (first-write-wins, qname
+  // collision buckets, etc.).
+
+  const allScopes: Scope[] = [];
+  const allDefs: SymbolDefinition[] = [];
+  const moduleEntries: { filePath: string; moduleScopeId: ScopeId }[] = [];
+  const allReferenceSites = [] as ReturnType<typeof collectReferenceSites>;
+
+  for (const file of parsedFiles) {
+    for (const s of file.scopes) allScopes.push(s);
+    for (const d of file.localDefs) allDefs.push(d);
+    moduleEntries.push({ filePath: file.filePath, moduleScopeId: file.moduleScope });
+  }
+  // References kept out of the loop above to centralize list-init.
+  allReferenceSites.push(...collectReferenceSites(parsedFiles));
+
+  const scopeTree = buildScopeTree(allScopes);
+  const defs = buildDefIndex(allDefs);
+  const qualifiedNames = buildQualifiedNameIndex(allDefs);
+  const moduleScopes = buildModuleScopeIndex(moduleEntries);
+
+  // ── Step 3: MethodDispatchIndex. Today we lack per-language MRO
+  // strategies wired into this orchestrator (that belongs with the
+  // HeritageMap bridge, a separate piece of work). Ship an EMPTY index
+  // so the bundle shape is consistent; the callbacks return `[]` for
+  // every owner and `implementsOf` returns `[]`. Populating this
+  // properly is tracked alongside the per-language provider hooks.
+  const methodDispatch = buildMethodDispatchIndex({
+    owners: [], // empty → no MRO entries; `mroFor(x)` returns the frozen empty array
+    computeMro: () => [],
+    implementsOf: () => [],
+  });
+
+  return {
+    scopeTree,
+    defs,
+    qualifiedNames,
+    moduleScopes,
+    methodDispatch,
+    imports: finalizeOut.imports,
+    bindings: finalizeOut.bindings,
+    referenceSites: Object.freeze([...allReferenceSites]),
+    sccs: finalizeOut.sccs,
+    stats: finalizeOut.stats,
+  };
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+/** Shape-reduce a `ParsedFile` to the narrower `FinalizeFile` the shared
+ *  algorithm reads. The subset is stable — `FinalizeFile` is a proper
+ *  subset of `ParsedFile`. */
+function toFinalizeFile(file: ParsedFile): FinalizeFile {
+  return {
+    filePath: file.filePath,
+    moduleScope: file.moduleScope,
+    parsedImports: file.parsedImports,
+    localDefs: file.localDefs,
+  };
+}
+
+/** Flatten every file's reference sites into one list. Order reflects
+ *  input-file order, then capture order inside each file. Deterministic. */
+function collectReferenceSites(parsedFiles: readonly ParsedFile[]) {
+  const out: ParsedFile['referenceSites'][number][] = [];
+  for (const file of parsedFiles) {
+    for (const site of file.referenceSites) out.push(site);
+  }
+  return out;
+}
+
+/**
+ * Fill in no-op defaults for any omitted hook. Keeps `finalize()`
+ * behavior well-defined for the zero-provider case today:
+ *
+ *   - `resolveImportTarget: () => null` — every import edge ends up
+ *     `linkStatus: 'unresolved'` (or dynamic-unresolved pass-through).
+ *   - `expandsWildcardTo: () => []` — wildcards don't materialize.
+ *   - `mergeBindings: (existing, incoming) => [...existing, ...incoming]`
+ *     — append without precedence; providers override to implement local-
+ *     shadows-import and similar rules.
+ */
+function withDefaultHooks(partial: Partial<FinalizeHooks>): FinalizeHooks {
+  return {
+    resolveImportTarget: partial.resolveImportTarget ?? (() => null),
+    expandsWildcardTo: partial.expandsWildcardTo ?? (() => []),
+    mergeBindings:
+      partial.mergeBindings ??
+      ((
+        existing: readonly BindingRef[],
+        incoming: readonly BindingRef[],
+      ): readonly BindingRef[] => [...existing, ...incoming]),
+  };
+}
diff --git a/gitnexus/src/core/ingestion/framework-detection.ts b/gitnexus/src/core/ingestion/framework-detection.ts
index 9ea43800c..739f22967 100644
--- a/gitnexus/src/core/ingestion/framework-detection.ts
+++ b/gitnexus/src/core/ingestion/framework-detection.ts
@@ -34,10 +34,14 @@ export interface FrameworkHint {
  */
 export function detectFrameworkFromPath(filePath: string): FrameworkHint | null {
   // Normalize path separators and ensure leading slash for consistent matching
-  let p = filePath.toLowerCase().replace(/\\/g, '/');
+  const originalPath = filePath.replace(/\\/g, '/');
+  let p = originalPath.toLowerCase();
   if (!p.startsWith('/')) {
     p = '/' + p; // Add leading slash so patterns like '/app/' match 'app/...'
   }
+  const originalPathWithLeadingSlash = originalPath.startsWith('/')
+    ? originalPath
+    : `/${originalPath}`;
 
   // ========== JAVASCRIPT / TYPESCRIPT FRAMEWORKS ==========
 
@@ -128,7 +132,7 @@ export function detectFrameworkFromPath(filePath: string): FrameworkHint | null
     (p.endsWith('.tsx') || p.endsWith('.jsx'))
   ) {
     // Only boost if PascalCase filename (likely a component, not util)
-    const fileName = p.split('/').pop() || '';
+    const fileName = originalPathWithLeadingSlash.split('/').pop() || '';
     if (/^[A-Z]/.test(fileName)) {
       return { framework: 'react', entryPointMultiplier: 1.5, reason: 'react-component' };
     }
diff --git a/gitnexus/src/core/ingestion/heritage-extractors/configs/go.ts b/gitnexus/src/core/ingestion/heritage-extractors/configs/go.ts
new file mode 100644
index 000000000..63768172d
--- /dev/null
+++ b/gitnexus/src/core/ingestion/heritage-extractors/configs/go.ts
@@ -0,0 +1,24 @@
+// gitnexus/src/core/ingestion/heritage-extractors/configs/go.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { HeritageExtractionConfig } from '../../heritage-types.js';
+
+/**
+ * Go heritage extraction config.
+ *
+ * Go struct embedding: the tree-sitter query matches ALL field_declarations
+ * with type_identifier, but only anonymous fields (no name) are embedded.
+ * Named fields like `Breed string` also match — skip them.
+ *
+ * The shouldSkipExtends hook checks if the extends node's parent is a
+ * field_declaration with a named field child, indicating a regular
+ * (non-embedded) field that should not produce a heritage record.
+ */
+export const goHeritageConfig: HeritageExtractionConfig = {
+  language: SupportedLanguages.Go,
+
+  shouldSkipExtends(extendsNode) {
+    const fieldDecl = extendsNode.parent;
+    return fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName?.('name') != null;
+  },
+};
diff --git a/gitnexus/src/core/ingestion/heritage-extractors/configs/ruby.ts b/gitnexus/src/core/ingestion/heritage-extractors/configs/ruby.ts
new file mode 100644
index 000000000..41bca1ff2
--- /dev/null
+++ b/gitnexus/src/core/ingestion/heritage-extractors/configs/ruby.ts
@@ -0,0 +1,73 @@
+// gitnexus/src/core/ingestion/heritage-extractors/configs/ruby.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { HeritageExtractionConfig, HeritageInfo } from '../../heritage-types.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Maximum parent depth for enclosing class/module walk.
+ * Prevents runaway walks on malformed/deeply-nested ASTs.
+ */
+const MAX_PARENT_DEPTH = 50;
+
+/**
+ * Walk up the AST from a call node to find the enclosing class or module name.
+ * Ruby include/extend/prepend calls must be inside a class or module body.
+ */
+function findEnclosingClassName(callNode: SyntaxNode): string | null {
+  let current = callNode.parent;
+  let depth = 0;
+  while (current && ++depth <= MAX_PARENT_DEPTH) {
+    if (current.type === 'class' || current.type === 'module') {
+      const nameNode = current.childForFieldName?.('name');
+      if (nameNode) return nameNode.text;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+/** Ruby heritage call names that express mixin inclusion. */
+const RUBY_HERITAGE_CALL_NAMES: ReadonlySet<string> = new Set(['include', 'extend', 'prepend']);
+
+/**
+ * Ruby heritage extraction config.
+ *
+ * Ruby expresses inheritance in two ways, and only one of them has
+ * dedicated tree-sitter heritage captures:
+ *
+ * 1. Class inheritance (`class A < B`) produces standard
+ *    `@heritage.extends` captures and flows through the generic
+ *    capture-based `extract` hook (not defined here — the factory
+ *    handles it).
+ * 2. Mixin calls (`include`/`extend`/`prepend`) have no dedicated
+ *    heritage captures; they surface as ordinary call sites. The
+ *    `callBasedHeritage` hook below intercepts them before the call
+ *    router, absorbing the mixin routing logic that previously lived
+ *    in call-routing.ts (routeRubyCall).
+ */
+export const rubyHeritageConfig: HeritageExtractionConfig = {
+  language: SupportedLanguages.Ruby,
+
+  callBasedHeritage: {
+    callNames: RUBY_HERITAGE_CALL_NAMES,
+
+    extract(calledName, callNode, _filePath): HeritageInfo[] {
+      const enclosingClass = findEnclosingClassName(callNode);
+      if (!enclosingClass) return [];
+
+      const results: HeritageInfo[] = [];
+      const argList = callNode.childForFieldName?.('arguments');
+      for (const arg of argList?.children ?? []) {
+        if (arg.type === 'constant' || arg.type === 'scope_resolution') {
+          results.push({
+            className: enclosingClass,
+            parentName: arg.text,
+            kind: calledName, // 'include' | 'extend' | 'prepend'
+          });
+        }
+      }
+      return results;
+    },
+  },
+};
diff --git a/gitnexus/src/core/ingestion/heritage-extractors/generic.ts b/gitnexus/src/core/ingestion/heritage-extractors/generic.ts
new file mode 100644
index 000000000..39c3d34c8
--- /dev/null
+++ b/gitnexus/src/core/ingestion/heritage-extractors/generic.ts
@@ -0,0 +1,84 @@
+// gitnexus/src/core/ingestion/heritage-extractors/generic.ts
+
+/**
+ * Generic table-driven heritage extractor factory.
+ *
+ * Follows the same config+factory pattern as method-extractors/generic.ts,
+ * field-extractors/generic.ts, call-extractors/generic.ts, and
+ * variable-extractors/generic.ts.
+ *
+ * Languages with custom extraction hooks (Go: shouldSkipExtends, Ruby:
+ * callBasedHeritage) pass a full HeritageExtractionConfig.  Languages
+ * that use the default capture-based extraction can pass just the
+ * SupportedLanguages enum value — no per-language config file needed.
+ */
+
+import type { SupportedLanguages } from 'gitnexus-shared';
+import type { CaptureMap } from '../language-provider.js';
+import type {
+  HeritageExtractionConfig,
+  HeritageExtractor,
+  HeritageExtractorContext,
+  HeritageInfo,
+} from '../heritage-types.js';
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+
+/**
+ * Create a HeritageExtractor from a declarative config or a language enum.
+ *
+ * When a full HeritageExtractionConfig is provided, custom hooks
+ * (shouldSkipExtends, callBasedHeritage) drive the extraction.
+ * When only a SupportedLanguages value is provided, the factory produces
+ * a default extractor that handles the standard @heritage.* captures.
+ */
+export function createHeritageExtractor(
+  config: HeritageExtractionConfig | SupportedLanguages,
+): HeritageExtractor {
+  const actualConfig: HeritageExtractionConfig =
+    typeof config === 'string' ? { language: config } : config;
+  const callNameSet = actualConfig.callBasedHeritage?.callNames;
+
+  return {
+    language: actualConfig.language,
+
+    extract(captureMap: CaptureMap, context: HeritageExtractorContext): HeritageInfo[] {
+      const classNode = captureMap['heritage.class'];
+      if (!classNode) return [];
+
+      const className = classNode.text;
+      const results: HeritageInfo[] = [];
+
+      const extendsNode = captureMap['heritage.extends'];
+      if (extendsNode) {
+        if (!actualConfig.shouldSkipExtends?.(extendsNode)) {
+          results.push({ className, parentName: extendsNode.text, kind: 'extends' });
+        }
+      }
+
+      const implementsNode = captureMap['heritage.implements'];
+      if (implementsNode) {
+        results.push({ className, parentName: implementsNode.text, kind: 'implements' });
+      }
+
+      const traitNode = captureMap['heritage.trait'];
+      if (traitNode) {
+        results.push({ className, parentName: traitNode.text, kind: 'trait-impl' });
+      }
+
+      return results;
+    },
+
+    ...(callNameSet
+      ? {
+          extractFromCall(
+            calledName: string,
+            callNode: SyntaxNode,
+            context: HeritageExtractorContext,
+          ): HeritageInfo[] | null {
+            if (!callNameSet.has(calledName)) return null;
+            return actualConfig.callBasedHeritage!.extract(calledName, callNode, context.filePath);
+          },
+        }
+      : {}),
+  };
+}
diff --git a/gitnexus/src/core/ingestion/heritage-processor.ts b/gitnexus/src/core/ingestion/heritage-processor.ts
index bc8628fa5..6692d1c95 100644
--- a/gitnexus/src/core/ingestion/heritage-processor.ts
+++ b/gitnexus/src/core/ingestion/heritage-processor.ts
@@ -19,7 +19,7 @@ import { ASTCache } from './ast-cache.js';
 import Parser from 'tree-sitter';
 import { isLanguageAvailable, loadParser, loadLanguage } from '../tree-sitter/parser-loader.js';
 import { generateId } from '../../lib/utils.js';
-import { getLanguageFromFilename, type SupportedLanguages } from 'gitnexus-shared';
+import { getLanguageFromFilename, type NodeLabel, type SupportedLanguages } from 'gitnexus-shared';
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import { yieldToEventLoop } from './utils/event-loop.js';
 import { getProvider } from './languages/index.js';
@@ -32,6 +32,7 @@ import type {
 import { resolveExtendsType } from './model/heritage-map.js';
 import type { ResolutionContext } from './model/resolution-context.js';
 import { TIER_CONFIDENCE } from './model/resolution-context.js';
+import type { HeritageInfo } from './heritage-types.js';
 
 /**
  * Derive the heritage-resolution strategy for a language from its
@@ -83,6 +84,103 @@ const resolveHeritageId = (
   };
 };
 
+/**
+ * Resolve a single HeritageInfo to a graph edge, using the same resolution
+ * logic as processHeritageFromExtracted.  This bridges the heritage extractor
+ * output format to the graph-resolution side.
+ */
+const resolveAndAddHeritageEdge = (
+  graph: KnowledgeGraph,
+  item: HeritageInfo,
+  filePath: string,
+  language: SupportedLanguages,
+  ctx: ResolutionContext,
+): void => {
+  if (item.kind === 'extends') {
+    const { type: relType, idPrefix } = resolveExtendsType(
+      item.parentName,
+      filePath,
+      ctx,
+      getHeritageStrategyForLanguage(language),
+    );
+
+    const child = resolveHeritageId(
+      item.className,
+      filePath,
+      ctx,
+      'Class',
+      `${filePath}:${item.className}`,
+    );
+    const parent = resolveHeritageId(item.parentName, filePath, ctx, idPrefix);
+
+    if (child.id && parent.id && child.id !== parent.id) {
+      graph.addRelationship({
+        id: generateId(relType, `${child.id}->${parent.id}`),
+        sourceId: child.id,
+        targetId: parent.id,
+        type: relType,
+        confidence: Math.sqrt(child.confidence * parent.confidence),
+        reason: '',
+      });
+    }
+  } else if (item.kind === 'implements') {
+    const cls = resolveHeritageId(
+      item.className,
+      filePath,
+      ctx,
+      'Class',
+      `${filePath}:${item.className}`,
+    );
+    const iface = resolveHeritageId(item.parentName, filePath, ctx, 'Interface');
+
+    if (cls.id && iface.id) {
+      graph.addRelationship({
+        id: generateId('IMPLEMENTS', `${cls.id}->${iface.id}`),
+        sourceId: cls.id,
+        targetId: iface.id,
+        type: 'IMPLEMENTS',
+        confidence: Math.sqrt(cls.confidence * iface.confidence),
+        reason: '',
+      });
+    }
+  } else if (
+    item.kind === 'trait-impl' ||
+    item.kind === 'include' ||
+    item.kind === 'extend' ||
+    item.kind === 'prepend'
+  ) {
+    // Fallback label for an unresolved child name. Rust `trait-impl` children
+    // are structs; Ruby mixin children are classes or modules (Trait). For
+    // Ruby mixin kinds the common case resolves through the type registry
+    // post-plan-001, so the fallback only fires for true-unresolved references
+    // (e.g. mixin inside a singleton_class). `Class` is strictly better than
+    // `Struct` there because it matches the label the structure phase would
+    // emit for a Ruby `class` — the dominant shape. Ruby modules that fail
+    // to resolve still lose their `Trait` label in the synthesized id, but
+    // they fail to resolve rarely and the tradeoff is documented.
+    const childFallbackLabel: NodeLabel = item.kind === 'trait-impl' ? 'Struct' : 'Class';
+    const strct = resolveHeritageId(
+      item.className,
+      filePath,
+      ctx,
+      childFallbackLabel,
+      `${filePath}:${item.className}`,
+    );
+    const trait = resolveHeritageId(item.parentName, filePath, ctx, 'Trait');
+
+    if (strct.id && trait.id) {
+      graph.addRelationship({
+        id: generateId('IMPLEMENTS', `${strct.id}->${trait.id}:${item.kind}`),
+        sourceId: strct.id,
+        targetId: trait.id,
+        type: 'IMPLEMENTS',
+        confidence: Math.sqrt(strct.confidence * trait.confidence),
+        reason: item.kind,
+      });
+    }
+  }
+};
+
 export const processHeritage = async (
   graph: KnowledgeGraph,
   files: { path: string; content: string }[],
@@ -135,112 +233,32 @@ export const processHeritage = async (
     let query;
     let matches;
     try {
-      const language = parser.getLanguage();
-      query = new Parser.Query(language, queryStr);
+      const treeSitterLang = parser.getLanguage();
+      query = new Parser.Query(treeSitterLang, queryStr);
       matches = query.matches(tree.rootNode);
     } catch (queryError) {
       console.warn(`Heritage query error for ${file.path}:`, queryError);
       continue;
     }
 
-    // 4. Process heritage matches
+    // 4. Process heritage matches via provider heritage extractor
+    const heritageExtractor = provider.heritageExtractor;
     matches.forEach((match) => {
       const captureMap: Record<string, any> = {};
       match.captures.forEach((c) => {
         captureMap[c.name] = c.node;
       });
 
-      // EXTENDS or IMPLEMENTS: resolve via symbol table for languages where
-      // the tree-sitter query can't distinguish classes from interfaces (C#, Java)
-      if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
-        // Go struct embedding: skip named fields (only anonymous fields are embedded)
-        const extendsNode = captureMap['heritage.extends'];
-        const fieldDecl = extendsNode.parent;
-        if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name')) {
-          return; // Named field, not struct embedding
-        }
+      if (!captureMap['heritage.class']) return;
+      if (!heritageExtractor) return;
 
-        const className = captureMap['heritage.class'].text;
-        const parentClassName = captureMap['heritage.extends'].text;
+      const heritageItems = heritageExtractor.extract(captureMap, {
+        filePath: file.path,
+        language,
+      });
 
-        const { type: relType, idPrefix } = resolveExtendsType(
-          parentClassName,
-          file.path,
-          ctx,
-          getHeritageStrategyForLanguage(language),
-        );
-
-        const child = resolveHeritageId(
-          className,
-          file.path,
-          ctx,
-          'Class',
-          `${file.path}:${className}`,
-        );
-        const parent = resolveHeritageId(parentClassName, file.path, ctx, idPrefix);
-
-        if (child.id && parent.id && child.id !== parent.id) {
-          graph.addRelationship({
-            id: generateId(relType, `${child.id}->${parent.id}`),
-            sourceId: child.id,
-            targetId: parent.id,
-            type: relType,
-            confidence: Math.sqrt(child.confidence * parent.confidence),
-            reason: '',
-          });
-        }
-      }
-
-      // IMPLEMENTS: Class implements Interface (TypeScript only)
-      if (captureMap['heritage.class'] && captureMap['heritage.implements']) {
-        const className = captureMap['heritage.class'].text;
-        const interfaceName = captureMap['heritage.implements'].text;
-
-        const cls = resolveHeritageId(
-          className,
-          file.path,
-          ctx,
-          'Class',
-          `${file.path}:${className}`,
-        );
-        const iface = resolveHeritageId(interfaceName, file.path, ctx, 'Interface');
-
-        if (cls.id && iface.id) {
-          graph.addRelationship({
-            id: generateId('IMPLEMENTS', `${cls.id}->${iface.id}`),
-            sourceId: cls.id,
-            targetId: iface.id,
-            type: 'IMPLEMENTS',
-            confidence: Math.sqrt(cls.confidence * iface.confidence),
-            reason: '',
-          });
-        }
-      }
-
-      // IMPLEMENTS (Rust): impl Trait for Struct
-      if (captureMap['heritage.trait'] && captureMap['heritage.class']) {
-        const structName = captureMap['heritage.class'].text;
-        const traitName = captureMap['heritage.trait'].text;
-
-        const strct = resolveHeritageId(
-          structName,
-          file.path,
-          ctx,
-          'Struct',
-          `${file.path}:${structName}`,
-        );
-        const trait = resolveHeritageId(traitName, file.path, ctx, 'Trait');
-
-        if (strct.id && trait.id) {
-          graph.addRelationship({
-            id: generateId('IMPLEMENTS', `${strct.id}->${trait.id}`),
-            sourceId: strct.id,
-            targetId: trait.id,
-            type: 'IMPLEMENTS',
-            confidence: Math.sqrt(strct.confidence * trait.confidence),
-            reason: 'trait-impl',
-          });
-        }
+      for (const item of heritageItems) {
+        resolveAndAddHeritageEdge(graph, item, file.path, language, ctx);
       }
     });
 
@@ -331,11 +349,15 @@ export const processHeritageFromExtracted = async (
       h.kind === 'extend' ||
       h.kind === 'prepend'
     ) {
+      // See the per-item call above (processHeritageFromExtractedItem) for
+      // rationale: `Class` is the correct fallback for Ruby mixin kinds,
+      // `Struct` stays the Rust `trait-impl` default.
+      const childFallbackLabel: NodeLabel = h.kind === 'trait-impl' ? 'Struct' : 'Class';
       const strct = resolveHeritageId(
         h.className,
         h.filePath,
         ctx,
-        'Struct',
+        childFallbackLabel,
         `${h.filePath}:${h.className}`,
       );
       const trait = resolveHeritageId(h.parentName, h.filePath, ctx, 'Trait');
@@ -361,6 +383,15 @@ export const processHeritageFromExtracted = async (
  * {@link ExtractedHeritage} rows without mutating the graph. Used on the
  * sequential pipeline path so `buildHeritageMap(..., ctx)` can run before
  * `processCalls` (worker path defers calls until heritage from all chunks exists).
+ *
+ * This prepass extracts BOTH capture-based heritage (`@heritage.*` — extends /
+ * implements / trait-impl) AND call-based heritage (`@call.name` routed through
+ * `heritageExtractor.extractFromCall` — Ruby `include` / `extend` / `prepend`).
+ * Without the second pass, sequential-mode `sequentialHeritageMap` would not
+ * know about Ruby mixin ancestry before `processCalls` resolves calls against
+ * it, silently dropping mixed-in methods from the graph. This function stays
+ * read-only — `processCalls` still owns emission of heritage graph edges via
+ * its `rubyHeritage` return path.
  */
 export async function extractExtractedHeritageFromFiles(
   files: { path: string; content: string }[],
@@ -400,6 +431,8 @@ export async function extractExtractedHeritageFromFiles(
       continue;
     }
 
+    const callBasedEnabled = !!provider.heritageExtractor?.extractFromCall;
+
     for (const match of matches) {
       const captureMap: Record<string, any> = {};
       match.captures.forEach((c) => {
@@ -407,35 +440,44 @@ export async function extractExtractedHeritageFromFiles(
       });
 
       if (captureMap['heritage.class']) {
-        if (captureMap['heritage.extends']) {
-          const extendsNode = captureMap['heritage.extends'];
-          const fieldDecl = extendsNode.parent;
-          const isNamedField =
-            fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name');
-          if (!isNamedField) {
+        if (provider.heritageExtractor) {
+          const heritageItems = provider.heritageExtractor.extract(captureMap, {
+            filePath: file.path,
+            language,
+          });
+          for (const item of heritageItems) {
             out.push({
               filePath: file.path,
-              className: captureMap['heritage.class'].text,
-              parentName: captureMap['heritage.extends'].text,
-              kind: 'extends',
+              className: item.className,
+              parentName: item.parentName,
+              kind: item.kind,
             });
           }
         }
-        if (captureMap['heritage.implements']) {
-          out.push({
-            filePath: file.path,
-            className: captureMap['heritage.class'].text,
-            parentName: captureMap['heritage.implements'].text,
-            kind: 'implements',
-          });
-        }
-        if (captureMap['heritage.trait']) {
-          out.push({
-            filePath: file.path,
-            className: captureMap['heritage.class'].text,
-            parentName: captureMap['heritage.trait'].text,
-            kind: 'trait-impl',
-          });
+        continue;
+      }
+
+      // Call-based heritage (e.g. Ruby include/extend/prepend). Matches the
+      // routing the worker path performs inline in parse-worker.ts — see the
+      // `provider.heritageExtractor?.extractFromCall` branch there. We only
+      // need call-based records here; other @call captures are consumed by
+      // processCalls later in the sequential loop.
+      if (callBasedEnabled && captureMap['call'] && captureMap['call.name']) {
+        const calledName: string = captureMap['call.name'].text;
+        const heritageItems = provider.heritageExtractor!.extractFromCall!(
+          calledName,
+          captureMap['call'],
+          { filePath: file.path, language },
+        );
+        if (heritageItems) {
+          for (const item of heritageItems) {
+            out.push({
+              filePath: file.path,
+              className: item.className,
+              parentName: item.parentName,
+              kind: item.kind,
+            });
+          }
         }
       }
     }
diff --git a/gitnexus/src/core/ingestion/heritage-types.ts b/gitnexus/src/core/ingestion/heritage-types.ts
new file mode 100644
index 000000000..82b6bbfad
--- /dev/null
+++ b/gitnexus/src/core/ingestion/heritage-types.ts
@@ -0,0 +1,104 @@
+// gitnexus/src/core/ingestion/heritage-types.ts
+
+/**
+ * Types for the language-agnostic heritage extraction pipeline.
+ *
+ * Follows the same pattern as call-types.ts, variable-types.ts, and
+ * method-types.ts: defines the domain interfaces consumed by
+ * createHeritageExtractor() and the per-language configs.
+ *
+ * Heritage extraction handles extends/implements/trait-impl captures from
+ * tree-sitter queries, plus call-based heritage for languages like Ruby
+ * (include/extend/prepend expressed as method calls).
+ */
+
+import type { SupportedLanguages } from 'gitnexus-shared';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+import type { CaptureMap } from './language-provider.js';
+
+// ---------------------------------------------------------------------------
+// Extracted result
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-match heritage extraction result.  The parse worker adds filePath to
+ * produce the final {@link ExtractedHeritage} that enters the resolution
+ * pipeline (heritage-processor.ts / heritage-map.ts).
+ */
+export interface HeritageInfo {
+  className: string;
+  parentName: string;
+  /** 'extends' | 'implements' | 'trait-impl' | 'include' | 'extend' | 'prepend' */
+  kind: string;
+}
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+export interface HeritageExtractorContext {
+  filePath: string;
+  language: SupportedLanguages;
+}
+
+// ---------------------------------------------------------------------------
+// Extractor interface (produced by createHeritageExtractor)
+// ---------------------------------------------------------------------------
+
+export interface HeritageExtractor {
+  readonly language: SupportedLanguages;
+
+  /**
+   * Extract heritage records from tree-sitter @heritage.* captures.
+   *
+   * @param captureMap  The capture map from a single tree-sitter match
+   * @param context     File path and language context
+   * @returns Array of heritage records (may be empty if captures don't match)
+   */
+  extract(captureMap: CaptureMap, context: HeritageExtractorContext): HeritageInfo[];
+
+  /**
+   * Extract heritage from a call node (for languages where heritage is
+   * expressed as method calls, e.g., Ruby include/extend/prepend).
+   *
+   * @param calledName  The method name (e.g. 'include', 'extend', 'prepend')
+   * @param callNode    The tree-sitter call AST node
+   * @param context     File path and language context
+   * @returns Heritage records if the call is heritage-related, or null to
+   *          fall through to the call router / normal call handling.
+   */
+  extractFromCall?(
+    calledName: string,
+    callNode: SyntaxNode,
+    context: HeritageExtractorContext,
+  ): HeritageInfo[] | null;
+}
+
+// ---------------------------------------------------------------------------
+// Config interface (one per language / language group)
+// ---------------------------------------------------------------------------
+
+export interface HeritageExtractionConfig {
+  language: SupportedLanguages;
+
+  /**
+   * Called for heritage.extends captures.  Return true to skip this extends
+   * capture.  Used by Go to skip named struct fields that match the
+   * field_declaration pattern but are not anonymous embeddings.
+   *
+   * Default: never skip (all extends captures are valid).
+   */
+  shouldSkipExtends?: (extendsNode: SyntaxNode) => boolean;
+
+  /**
+   * Call-based heritage extraction for languages where heritage is expressed
+   * as method calls (e.g., Ruby include/extend/prepend).
+   *
+   * callNames: set of method names that trigger heritage extraction.
+   * extract:   extract heritage items from the call node + method name.
+   */
+  callBasedHeritage?: {
+    readonly callNames: ReadonlySet<string>;
+    extract(calledName: string, callNode: SyntaxNode, filePath: string): HeritageInfo[];
+  };
+}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/c-cpp.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/c-cpp.ts
new file mode 100644
index 000000000..bcfddee0b
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/c-cpp.ts
@@ -0,0 +1,18 @@
+/**
+ * C / C++ import resolution configs.
+ * Both use standard resolution for #include directives.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+
+export const cImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.C,
+  strategies: [createStandardStrategy(SupportedLanguages.C)],
+};
+
+export const cppImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.CPlusPlus,
+  strategies: [createStandardStrategy(SupportedLanguages.CPlusPlus)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/csharp.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/csharp.ts
new file mode 100644
index 000000000..cb5f77145
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/csharp.ts
@@ -0,0 +1,36 @@
+/**
+ * C# import resolution config.
+ * Namespace-based strategy via .csproj configs, then standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+import { resolveCSharpImportInternal, resolveCSharpNamespaceDir } from '../csharp.js';
+
+/** C# namespace-based resolution strategy via .csproj configs. */
+export const csharpNamespaceStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  const csharpConfigs = ctx.configs.csharpConfigs;
+  if (csharpConfigs.length > 0) {
+    const resolvedFiles = resolveCSharpImportInternal(
+      rawImportPath,
+      csharpConfigs,
+      ctx.normalizedFileList,
+      ctx.allFileList,
+      ctx.index,
+    );
+    if (resolvedFiles.length > 1) {
+      const dirSuffix = resolveCSharpNamespaceDir(rawImportPath, csharpConfigs);
+      if (dirSuffix) {
+        return { kind: 'package', files: resolvedFiles, dirSuffix };
+      }
+    }
+    if (resolvedFiles.length > 0) return { kind: 'files', files: resolvedFiles };
+  }
+  return null;
+};
+
+export const csharpImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.CSharp,
+  strategies: [csharpNamespaceStrategy, createStandardStrategy(SupportedLanguages.CSharp)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/dart.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/dart.ts
new file mode 100644
index 000000000..06dcea98a
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/dart.ts
@@ -0,0 +1,58 @@
+/**
+ * Dart import resolution config.
+ * SDK/package strategy first, then relative import strategy (with ./ prepending).
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { resolveStandard } from '../standard.js';
+
+/**
+ * Dart SDK and package: import strategy.
+ * Absorbs dart: SDK imports and external packages (returns empty result to stop chain).
+ * Returns null for relative imports to let the next strategy handle them.
+ */
+export const dartPackageStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  // Strip surrounding quotes from configurable_uri capture
+  const stripped = rawImportPath.replace(/^['"]|['"]$/g, '');
+
+  // Skip dart: SDK imports (dart:async, dart:io, etc.)
+  if (stripped.startsWith('dart:')) return { kind: 'files', files: [] };
+
+  // Local package: imports → resolve to lib/<path>
+  if (stripped.startsWith('package:')) {
+    const slashIdx = stripped.indexOf('/');
+    if (slashIdx === -1) return { kind: 'files', files: [] };
+    const relPath = stripped.slice(slashIdx + 1);
+    const candidates = [`lib/${relPath}`, relPath];
+    const files: string[] = [];
+    for (const candidate of candidates) {
+      for (const fp of ctx.allFileList) {
+        if (fp.endsWith('/' + candidate) || fp === candidate) {
+          files.push(fp);
+          break;
+        }
+      }
+      if (files.length > 0) break;
+    }
+    if (files.length > 0) return { kind: 'files', files };
+    return { kind: 'files', files: [] }; // external package
+  }
+
+  return null;
+};
+
+/**
+ * Dart relative import strategy — prepends "./" for bare relative paths,
+ * then delegates to standard resolution.
+ */
+export const dartRelativeStrategy: ImportResolverStrategy = (rawImportPath, filePath, ctx) => {
+  const stripped = rawImportPath.replace(/^['"]|['"]$/g, '');
+  const relPath = stripped.startsWith('.') ? stripped : './' + stripped;
+  return resolveStandard(relPath, filePath, ctx, SupportedLanguages.Dart);
+};
+
+export const dartImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Dart,
+  strategies: [dartPackageStrategy, dartRelativeStrategy],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/go.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/go.ts
new file mode 100644
index 000000000..7eee17988
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/go.ts
@@ -0,0 +1,35 @@
+/**
+ * Go import resolution config.
+ * Go-specific package strategy (go.mod), then standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+import { resolveGoPackageDir, resolveGoPackage } from '../go.js';
+
+/** Go-specific package resolution strategy — resolves go.mod-based package imports. */
+export const goPackageStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  const goModule = ctx.configs.goModule;
+  if (goModule && rawImportPath.startsWith(goModule.modulePath)) {
+    const pkgSuffix = resolveGoPackageDir(rawImportPath, goModule);
+    if (pkgSuffix) {
+      const pkgFiles = resolveGoPackage(
+        rawImportPath,
+        goModule,
+        ctx.normalizedFileList,
+        ctx.allFileList,
+      );
+      if (pkgFiles.length > 0) {
+        return { kind: 'package', files: pkgFiles, dirSuffix: pkgSuffix };
+      }
+    }
+    // Fall through if no files found (package might be external)
+  }
+  return null;
+};
+
+export const goImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Go,
+  strategies: [goPackageStrategy, createStandardStrategy(SupportedLanguages.Go)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/jvm.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/jvm.ts
new file mode 100644
index 000000000..47e590fe8
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/jvm.ts
@@ -0,0 +1,115 @@
+/**
+ * Java / Kotlin import resolution configs.
+ * JVM-specific wildcard/member strategy, then standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+import { resolveJvmWildcard, resolveJvmMemberImport, KOTLIN_EXTENSIONS } from '../jvm.js';
+
+/** Java JVM resolution strategy — wildcard and member import resolution. */
+export const javaJvmStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  if (rawImportPath.endsWith('.*')) {
+    const matchedFiles = resolveJvmWildcard(
+      rawImportPath,
+      ctx.normalizedFileList,
+      ctx.allFileList,
+      ['.java'],
+      ctx.index,
+    );
+    if (matchedFiles.length > 0) return { kind: 'files', files: matchedFiles };
+  } else {
+    const memberResolved = resolveJvmMemberImport(
+      rawImportPath,
+      ctx.normalizedFileList,
+      ctx.allFileList,
+      ['.java'],
+      ctx.index,
+    );
+    if (memberResolved) return { kind: 'files', files: [memberResolved] };
+  }
+  return null;
+};
+
+/**
+ * Kotlin JVM resolution strategy — wildcard/member with Java-interop + top-level function imports.
+ */
+export const kotlinJvmStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  if (rawImportPath.endsWith('.*')) {
+    const matchedFiles = resolveJvmWildcard(
+      rawImportPath,
+      ctx.normalizedFileList,
+      ctx.allFileList,
+      KOTLIN_EXTENSIONS,
+      ctx.index,
+    );
+    if (matchedFiles.length === 0) {
+      const javaMatches = resolveJvmWildcard(
+        rawImportPath,
+        ctx.normalizedFileList,
+        ctx.allFileList,
+        ['.java'],
+        ctx.index,
+      );
+      if (javaMatches.length > 0) return { kind: 'files', files: javaMatches };
+    }
+    if (matchedFiles.length > 0) return { kind: 'files', files: matchedFiles };
+  } else {
+    let memberResolved = resolveJvmMemberImport(
+      rawImportPath,
+      ctx.normalizedFileList,
+      ctx.allFileList,
+      KOTLIN_EXTENSIONS,
+      ctx.index,
+    );
+    if (!memberResolved) {
+      memberResolved = resolveJvmMemberImport(
+        rawImportPath,
+        ctx.normalizedFileList,
+        ctx.allFileList,
+        ['.java'],
+        ctx.index,
+      );
+    }
+    if (memberResolved) return { kind: 'files', files: [memberResolved] };
+
+    // Kotlin: top-level function imports (e.g. import models.getUser) have only 2 segments,
+    // which resolveJvmMemberImport skips (requires >=3). Fall back to package-directory scan
+    // for lowercase last segments (function/property imports). Uppercase last segments
+    // (class imports like models.User) fall through to standard suffix resolution.
+    const segments = rawImportPath.split('.');
+    const lastSeg = segments[segments.length - 1];
+    if (segments.length >= 2 && lastSeg[0] && lastSeg[0] === lastSeg[0].toLowerCase()) {
+      const pkgWildcard = segments.slice(0, -1).join('.') + '.*';
+      let dirFiles = resolveJvmWildcard(
+        pkgWildcard,
+        ctx.normalizedFileList,
+        ctx.allFileList,
+        KOTLIN_EXTENSIONS,
+        ctx.index,
+      );
+      if (dirFiles.length === 0) {
+        dirFiles = resolveJvmWildcard(
+          pkgWildcard,
+          ctx.normalizedFileList,
+          ctx.allFileList,
+          ['.java'],
+          ctx.index,
+        );
+      }
+      if (dirFiles.length > 0) return { kind: 'files', files: dirFiles };
+    }
+  }
+  return null;
+};
+
+export const javaImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Java,
+  strategies: [javaJvmStrategy, createStandardStrategy(SupportedLanguages.Java)],
+};
+
+export const kotlinImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Kotlin,
+  strategies: [kotlinJvmStrategy, createStandardStrategy(SupportedLanguages.Kotlin)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/php.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/php.ts
new file mode 100644
index 000000000..5a8446f25
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/php.ts
@@ -0,0 +1,26 @@
+/**
+ * PHP import resolution config.
+ * PSR-4 strategy via composer.json — no standard fallback (PSR-4 includes its own suffix matching).
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { resolvePhpImportInternal } from '../php.js';
+
+/** PHP PSR-4 resolution strategy via composer.json autoload mappings. */
+export const phpPsr4Strategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  const resolved = resolvePhpImportInternal(
+    rawImportPath,
+    ctx.configs.composerConfig,
+    ctx.allFilePaths,
+    ctx.normalizedFileList,
+    ctx.allFileList,
+    ctx.index,
+  );
+  return resolved ? { kind: 'files', files: [resolved] } : null;
+};
+
+export const phpImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.PHP,
+  strategies: [phpPsr4Strategy],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/python.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/python.ts
new file mode 100644
index 000000000..d98304561
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/python.ts
@@ -0,0 +1,47 @@
+/**
+ * Python import resolution config.
+ * PEP 328 relative + proximity-based strategy, then standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+import { resolvePythonImportInternal } from '../python.js';
+
+/**
+ * Python import resolution strategy — PEP 328 relative + proximity-based bare imports.
+ * Returns null to continue chain for non-relative imports.
+ * Absorbs unresolved relative imports (returns empty result to stop the chain).
+ */
+export const pythonImportStrategy: ImportResolverStrategy = (rawImportPath, filePath, ctx) => {
+  const resolved = resolvePythonImportInternal(filePath, rawImportPath, ctx.allFilePaths);
+  if (resolved) {
+    ctx.resolveCache.set(`${filePath}::${rawImportPath}`, resolved);
+    return { kind: 'files', files: [resolved] };
+  }
+  // PEP 328: unresolved relative imports should not fall through to suffix matching
+  if (rawImportPath.startsWith('.')) return { kind: 'files', files: [] };
+
+  // External dotted imports like `django.apps` should not fall through to generic
+  // suffix matching when the repo has unrelated local files such as `accounts/apps.py`.
+  // Keep suffix fallback only when the leading segment appears somewhere in-repo,
+  // which preserves existing internal absolute-import behavior like `accounts.models`.
+  const pathLike = rawImportPath.replace(/\./g, '/');
+  if (pathLike.includes('/')) {
+    const [leadingSegment] = pathLike.split('/').filter(Boolean);
+    const hasRepoCandidate =
+      !!leadingSegment &&
+      (ctx.index.get(`${leadingSegment}.py`) !== undefined ||
+        ctx.index.get(`${leadingSegment}/__init__.py`) !== undefined ||
+        ctx.index.getFilesInDir(leadingSegment, '.py').length > 0);
+
+    if (!hasRepoCandidate) return { kind: 'files', files: [] };
+  }
+
+  return null;
+};
+
+export const pythonImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Python,
+  strategies: [pythonImportStrategy, createStandardStrategy(SupportedLanguages.Python)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/ruby.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/ruby.ts
new file mode 100644
index 000000000..bf2507f70
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/ruby.ts
@@ -0,0 +1,20 @@
+/**
+ * Ruby import resolution config.
+ * Require/require_relative suffix matching — no standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { suffixResolve } from '../utils.js';
+
+/** Ruby require/require_relative resolution strategy. */
+export const rubyRequireStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
+  const pathParts = rawImportPath.replace(/^\.\//, '').split('/').filter(Boolean);
+  const resolved = suffixResolve(pathParts, ctx.normalizedFileList, ctx.allFileList, ctx.index);
+  return resolved ? { kind: 'files', files: [resolved] } : null;
+};
+
+export const rubyImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Ruby,
+  strategies: [rubyRequireStrategy],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/rust.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/rust.ts
new file mode 100644
index 000000000..daa2173e7
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/rust.ts
@@ -0,0 +1,56 @@
+/**
+ * Rust import resolution config.
+ * Rust module strategy (grouped imports, crate/super/self paths), then standard fallback.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+import { resolveRustImportInternal } from '../rust.js';
+
+/** Rust module resolution strategy — handles grouped imports and crate/super/self paths. */
+export const rustModuleStrategy: ImportResolverStrategy = (rawImportPath, filePath, ctx) => {
+  // Top-level grouped: use {crate::a, crate::b}
+  if (rawImportPath.startsWith('{') && rawImportPath.endsWith('}')) {
+    const inner = rawImportPath.slice(1, -1);
+    const parts = inner
+      .split(',')
+      .map((p) => p.trim())
+      .filter(Boolean);
+    const resolved: string[] = [];
+    for (const part of parts) {
+      const r = resolveRustImportInternal(filePath, part, ctx.allFilePaths);
+      if (r) resolved.push(r);
+    }
+    return resolved.length > 0 ? { kind: 'files', files: resolved } : null;
+  }
+
+  // Scoped grouped: use crate::models::{User, Repo}
+  const braceIdx = rawImportPath.indexOf('::{');
+  if (braceIdx !== -1 && rawImportPath.endsWith('}')) {
+    const pathPrefix = rawImportPath.substring(0, braceIdx);
+    const braceContent = rawImportPath.substring(braceIdx + 3, rawImportPath.length - 1);
+    const items = braceContent
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const resolved: string[] = [];
+    for (const item of items) {
+      // Handle `use crate::models::{User, Repo as R}` — strip alias for resolution
+      const itemName = item.includes(' as ') ? item.split(' as ')[0].trim() : item;
+      const r = resolveRustImportInternal(filePath, `${pathPrefix}::${itemName}`, ctx.allFilePaths);
+      if (r) resolved.push(r);
+    }
+    if (resolved.length > 0) return { kind: 'files', files: resolved };
+    // Fallback: resolve the prefix path itself (e.g. crate::models -> models.rs)
+    const prefixResult = resolveRustImportInternal(filePath, pathPrefix, ctx.allFilePaths);
+    if (prefixResult) return { kind: 'files', files: [prefixResult] };
+  }
+
+  return null;
+};
+
+export const rustImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Rust,
+  strategies: [rustModuleStrategy, createStandardStrategy(SupportedLanguages.Rust)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/swift.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/swift.ts
similarity index 53%
rename from gitnexus/src/core/ingestion/import-resolvers/swift.ts
rename to gitnexus/src/core/ingestion/import-resolvers/configs/swift.ts
index 7ccc10458..f7d9ec195 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/swift.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/swift.ts
@@ -1,16 +1,13 @@
 /**
- * Swift module import resolution.
- * Handles module imports via Package.swift target map.
+ * Swift import resolution config.
+ * Package.swift target map strategy — no standard fallback (unresolved = external framework).
  */
 
-import type { ImportResult, ResolveCtx } from './types.js';
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig, ImportResolverStrategy } from '../types.js';
 
-/** Swift: module imports via Package.swift target map. */
-export function resolveSwiftImport(
-  rawImportPath: string,
-  _filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
+/** Swift Package.swift target map resolution strategy. */
+export const swiftPackageStrategy: ImportResolverStrategy = (rawImportPath, _filePath, ctx) => {
   const swiftPackageConfig = ctx.configs.swiftPackageConfig;
   if (swiftPackageConfig) {
     const targetDir = swiftPackageConfig.targets.get(rawImportPath);
@@ -29,4 +26,9 @@ export function resolveSwiftImport(
     }
   }
   return null; // External framework (Foundation, UIKit, etc.)
-}
+};
+
+export const swiftImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Swift,
+  strategies: [swiftPackageStrategy],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/configs/typescript-javascript.ts b/gitnexus/src/core/ingestion/import-resolvers/configs/typescript-javascript.ts
new file mode 100644
index 000000000..b86b365fd
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/configs/typescript-javascript.ts
@@ -0,0 +1,28 @@
+/**
+ * TypeScript / JavaScript / Vue import resolution configs.
+ * All use standard resolution — TS/JS with tsconfig path aliases,
+ * Vue delegates to TypeScript's resolver.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { ImportResolutionConfig } from '../types.js';
+import { createStandardStrategy } from '../standard.js';
+
+export const typescriptImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.TypeScript,
+  strategies: [createStandardStrategy(SupportedLanguages.TypeScript)],
+};
+
+export const javascriptImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.JavaScript,
+  strategies: [createStandardStrategy(SupportedLanguages.JavaScript)],
+};
+
+// Vue SFCs are preprocessed into TypeScript upstream of import resolution,
+// so the resolver intentionally runs as TypeScript. `language: Vue` here is
+// documentation-only metadata (see `ImportResolutionConfig.language` JSDoc
+// and ARCHITECTURE.md §Vue); it is not consumed by `createImportResolver`.
+export const vueImportConfig: ImportResolutionConfig = {
+  language: SupportedLanguages.Vue,
+  strategies: [createStandardStrategy(SupportedLanguages.TypeScript)],
+};
diff --git a/gitnexus/src/core/ingestion/import-resolvers/csharp.ts b/gitnexus/src/core/ingestion/import-resolvers/csharp.ts
index 33cc9c828..79548d7f6 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/csharp.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/csharp.ts
@@ -1,13 +1,12 @@
 /**
- * C# namespace import resolution.
- * Handles using-directive resolution via .csproj root namespace stripping.
+ * C# namespace import resolution — internal helpers.
+ *
+ * Strategy lives in configs/csharp.ts.
+ * This file contains shared helpers for namespace-based resolution.
  */
 
 import type { SuffixIndex } from './utils.js';
 import { suffixResolve } from './utils.js';
-import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
 import type { CSharpProjectConfig } from '../language-config.js';
 
 /**
@@ -126,29 +125,3 @@ export function resolveCSharpNamespaceDir(
 
   return null;
 }
-
-/** C#: namespace-based resolution via .csproj configs, with suffix-match fallback. */
-export function resolveCSharpImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  const csharpConfigs = ctx.configs.csharpConfigs;
-  if (csharpConfigs.length > 0) {
-    const resolvedFiles = resolveCSharpImportInternal(
-      rawImportPath,
-      csharpConfigs,
-      ctx.normalizedFileList,
-      ctx.allFileList,
-      ctx.index,
-    );
-    if (resolvedFiles.length > 1) {
-      const dirSuffix = resolveCSharpNamespaceDir(rawImportPath, csharpConfigs);
-      if (dirSuffix) {
-        return { kind: 'package', files: resolvedFiles, dirSuffix };
-      }
-    }
-    if (resolvedFiles.length > 0) return { kind: 'files', files: resolvedFiles };
-  }
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.CSharp);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/dart.ts b/gitnexus/src/core/ingestion/import-resolvers/dart.ts
deleted file mode 100644
index 2a3cf3f6b..000000000
--- a/gitnexus/src/core/ingestion/import-resolvers/dart.ts
+++ /dev/null
@@ -1,50 +0,0 @@
-/**
- * Dart import resolution.
- * Handles package: imports (local packages) and relative imports.
- * SDK imports (dart:*) and external packages are skipped.
- */
-
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
-import { SupportedLanguages } from 'gitnexus-shared';
-
-export function resolveDartImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  // Strip surrounding quotes from configurable_uri capture
-  const stripped = rawImportPath.replace(/^['"]|['"]$/g, '');
-
-  // Skip dart: SDK imports (dart:async, dart:io, etc.)
-  if (stripped.startsWith('dart:')) return null;
-
-  // Local package: imports → resolve to lib/<path>
-  if (stripped.startsWith('package:')) {
-    const slashIdx = stripped.indexOf('/');
-    if (slashIdx === -1) return null;
-    const relPath = stripped.slice(slashIdx + 1);
-    const candidates = [`lib/${relPath}`, relPath];
-    const files: string[] = [];
-    for (const candidate of candidates) {
-      for (const fp of ctx.allFileList) {
-        if (fp.endsWith('/' + candidate) || fp === candidate) {
-          files.push(fp);
-          break;
-        }
-      }
-      if (files.length > 0) break;
-    }
-    if (files.length > 0) return { kind: 'files', files };
-    return null;
-  }
-
-  // Relative imports — use standard resolution.
-  // Dart relative imports don't require a leading "./" (e.g. `import 'models.dart'`).
-  // The standard resolver only recognises paths starting with "." as relative, so
-  // prepend "./" when the path doesn't already start with "." to ensure correct
-  // same-directory resolution (without this, "models.dart" would be mangled by the
-  // generic dot-to-slash conversion intended for Java-style package imports).
-  const relPath = stripped.startsWith('.') ? stripped : './' + stripped;
-  return resolveStandard(relPath, filePath, ctx, SupportedLanguages.Dart);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/go.ts b/gitnexus/src/core/ingestion/import-resolvers/go.ts
index 1b1eb3ebc..c33c46422 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/go.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/go.ts
@@ -1,11 +1,10 @@
 /**
- * Go package import resolution.
- * Handles Go module path-based package imports.
+ * Go package import resolution — internal helpers.
+ *
+ * Strategy lives in configs/go.ts.
+ * This file contains the shared helpers used by the strategy.
  */
 
-import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
 import type { GoModuleConfig } from '../language-config.js';
 
 /**
@@ -56,28 +55,3 @@ export function resolveGoPackage(
 
   return matches;
 }
-
-/** Go: package-level imports via go.mod module path. */
-export function resolveGoImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  const goModule = ctx.configs.goModule;
-  if (goModule && rawImportPath.startsWith(goModule.modulePath)) {
-    const pkgSuffix = resolveGoPackageDir(rawImportPath, goModule);
-    if (pkgSuffix) {
-      const pkgFiles = resolveGoPackage(
-        rawImportPath,
-        goModule,
-        ctx.normalizedFileList,
-        ctx.allFileList,
-      );
-      if (pkgFiles.length > 0) {
-        return { kind: 'package', files: pkgFiles, dirSuffix: pkgSuffix };
-      }
-    }
-    // Fall through if no files found (package might be external)
-  }
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.Go);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/jvm.ts b/gitnexus/src/core/ingestion/import-resolvers/jvm.ts
index 2dd7636ab..194cfdac8 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/jvm.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/jvm.ts
@@ -1,13 +1,13 @@
 /**
- * JVM import resolution (Java + Kotlin).
- * Handles wildcard imports, member/static imports, and Kotlin-specific patterns.
+ * JVM import resolution — internal helpers (Java + Kotlin).
+ *
+ * Strategies live in configs/jvm.ts.
+ * This file contains shared helpers for wildcard/member resolution
+ * and the Kotlin wildcard preprocessor.
  */
 
 import type { SuffixIndex } from './utils.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
-import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
 
 /** Kotlin file extensions for JVM resolver reuse */
 export const KOTLIN_EXTENSIONS: readonly string[] = ['.kt', '.kts'];
@@ -125,108 +125,3 @@ export function resolveJvmMemberImport(
 
   return null;
 }
-
-/** Java: JVM wildcard -> member import -> standard fallthrough */
-export function resolveJavaImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  if (rawImportPath.endsWith('.*')) {
-    const matchedFiles = resolveJvmWildcard(
-      rawImportPath,
-      ctx.normalizedFileList,
-      ctx.allFileList,
-      ['.java'],
-      ctx.index,
-    );
-    if (matchedFiles.length > 0) return { kind: 'files', files: matchedFiles };
-  } else {
-    const memberResolved = resolveJvmMemberImport(
-      rawImportPath,
-      ctx.normalizedFileList,
-      ctx.allFileList,
-      ['.java'],
-      ctx.index,
-    );
-    if (memberResolved) return { kind: 'files', files: [memberResolved] };
-  }
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.Java);
-}
-
-/**
- * Kotlin: JVM wildcard/member with Java-interop fallback -> top-level function imports -> standard.
- * Kotlin can import from .kt/.kts files OR from .java files (Java interop).
- */
-export function resolveKotlinImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  if (rawImportPath.endsWith('.*')) {
-    const matchedFiles = resolveJvmWildcard(
-      rawImportPath,
-      ctx.normalizedFileList,
-      ctx.allFileList,
-      KOTLIN_EXTENSIONS,
-      ctx.index,
-    );
-    if (matchedFiles.length === 0) {
-      const javaMatches = resolveJvmWildcard(
-        rawImportPath,
-        ctx.normalizedFileList,
-        ctx.allFileList,
-        ['.java'],
-        ctx.index,
-      );
-      if (javaMatches.length > 0) return { kind: 'files', files: javaMatches };
-    }
-    if (matchedFiles.length > 0) return { kind: 'files', files: matchedFiles };
-  } else {
-    let memberResolved = resolveJvmMemberImport(
-      rawImportPath,
-      ctx.normalizedFileList,
-      ctx.allFileList,
-      KOTLIN_EXTENSIONS,
-      ctx.index,
-    );
-    if (!memberResolved) {
-      memberResolved = resolveJvmMemberImport(
-        rawImportPath,
-        ctx.normalizedFileList,
-        ctx.allFileList,
-        ['.java'],
-        ctx.index,
-      );
-    }
-    if (memberResolved) return { kind: 'files', files: [memberResolved] };
-
-    // Kotlin: top-level function imports (e.g. import models.getUser) have only 2 segments,
-    // which resolveJvmMemberImport skips (requires >=3). Fall back to package-directory scan
-    // for lowercase last segments (function/property imports). Uppercase last segments
-    // (class imports like models.User) fall through to standard suffix resolution.
-    const segments = rawImportPath.split('.');
-    const lastSeg = segments[segments.length - 1];
-    if (segments.length >= 2 && lastSeg[0] && lastSeg[0] === lastSeg[0].toLowerCase()) {
-      const pkgWildcard = segments.slice(0, -1).join('.') + '.*';
-      let dirFiles = resolveJvmWildcard(
-        pkgWildcard,
-        ctx.normalizedFileList,
-        ctx.allFileList,
-        KOTLIN_EXTENSIONS,
-        ctx.index,
-      );
-      if (dirFiles.length === 0) {
-        dirFiles = resolveJvmWildcard(
-          pkgWildcard,
-          ctx.normalizedFileList,
-          ctx.allFileList,
-          ['.java'],
-          ctx.index,
-        );
-      }
-      if (dirFiles.length > 0) return { kind: 'files', files: dirFiles };
-    }
-  }
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.Kotlin);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/php.ts b/gitnexus/src/core/ingestion/import-resolvers/php.ts
index 20517bbed..303bf5546 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/php.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/php.ts
@@ -1,11 +1,12 @@
 /**
- * PHP PSR-4 import resolution.
- * Handles use-statement resolution via composer.json autoload mappings.
+ * PHP PSR-4 import resolution — internal helpers.
+ *
+ * Strategy lives in configs/php.ts.
+ * This file contains the shared helper for PSR-4 resolution via composer.json.
  */
 
 import type { SuffixIndex } from './utils.js';
 import { suffixResolve } from './utils.js';
-import type { ImportResult, ResolveCtx } from './types.js';
 import type { ComposerConfig } from '../language-config.js';
 
 /** Get or compute the sorted PSR-4 entries (cached after first call). */
@@ -91,20 +92,3 @@ export function resolvePhpImportInternal(
   const pathParts = normalized.split('/').filter(Boolean);
   return suffixResolve(pathParts, normalizedFileList, allFileList, index);
 }
-
-/** PHP: namespace-based resolution via composer.json PSR-4. */
-export function resolvePhpImport(
-  rawImportPath: string,
-  _filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  const resolved = resolvePhpImportInternal(
-    rawImportPath,
-    ctx.configs.composerConfig,
-    ctx.allFilePaths,
-    ctx.normalizedFileList,
-    ctx.allFileList,
-    ctx.index,
-  );
-  return resolved ? { kind: 'files', files: [resolved] } : null;
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/python.ts b/gitnexus/src/core/ingestion/import-resolvers/python.ts
index 4e9c4bbb3..264103a09 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/python.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/python.ts
@@ -1,12 +1,12 @@
 /**
  * Python import resolution — PEP 328 relative imports and proximity-based bare imports.
  * Import system spec: PEP 302 (original), PEP 451 (current).
+ *
+ * Strategy lives in configs/python.ts.
+ * This file contains the shared internal helper used by the strategy and tests.
  */
 
 import { tryResolveWithExtensions } from './utils.js';
-import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
 
 /**
  * Resolve a Python import to a file path (low-level helper).
@@ -74,23 +74,3 @@ export function resolvePythonImportInternal(
 
   return null;
 }
-
-/**
- * Python: relative imports (PEP 328) + proximity-based bare imports.
- * Falls through to standard suffix resolution when proximity finds no match.
- */
-export function resolvePythonImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  const resolved = resolvePythonImportInternal(filePath, rawImportPath, ctx.allFilePaths);
-  if (resolved) {
-    // Store in resolveCache so other files importing the same module skip the
-    // ancestor walk. The cache key matches resolveStandard's convention.
-    ctx.resolveCache.set(`${filePath}::${rawImportPath}`, resolved);
-    return { kind: 'files', files: [resolved] };
-  }
-  if (rawImportPath.startsWith('.')) return null; // relative but unresolved -- don't suffix-match
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.Python);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/resolver-factory.ts b/gitnexus/src/core/ingestion/import-resolvers/resolver-factory.ts
new file mode 100644
index 000000000..4caf748a7
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-resolvers/resolver-factory.ts
@@ -0,0 +1,35 @@
+/**
+ * Import resolver factory — creates a composable import resolver from
+ * an ordered list of strategies.
+ *
+ * Mirrors the method-extractors/generic.ts and call-extractors/generic.ts
+ * pattern: declare a config per language, produce a runtime resolver via factory.
+ *
+ * Each strategy is tried in order. The first non-null result wins.
+ * A result with an empty `files` array is treated as "handled but unresolved"
+ * (stops the chain without producing import edges).
+ */
+
+import type { ImportResolverFn, ImportResolutionConfig } from './types.js';
+
+/**
+ * Create an ImportResolverFn from a declarative config.
+ *
+ * Chains strategies in declaration order — first non-null result wins.
+ * Returns null only if every strategy returns null.
+ *
+ * Error behaviour: if a strategy throws, the error propagates immediately
+ * and remaining strategies are not tried.  Strategies are expected to be
+ * pure data transforms that never throw; any unexpected exception indicates
+ * a bug in the strategy implementation.
+ */
+export function createImportResolver(config: ImportResolutionConfig): ImportResolverFn {
+  const { strategies } = config;
+  return (rawImportPath, filePath, ctx) => {
+    for (const strategy of strategies) {
+      const result = strategy(rawImportPath, filePath, ctx);
+      if (result) return result;
+    }
+    return null;
+  };
+}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/ruby.ts b/gitnexus/src/core/ingestion/import-resolvers/ruby.ts
index b8ada4cf4..4bf47d31f 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/ruby.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/ruby.ts
@@ -1,11 +1,12 @@
 /**
- * Ruby require/require_relative import resolution.
- * Handles path resolution for Ruby's require and require_relative calls.
+ * Ruby require/require_relative import resolution — internal helpers.
+ *
+ * Strategy lives in configs/ruby.ts.
+ * This file only contains the low-level helper used by the strategy.
  */
 
 import type { SuffixIndex } from './utils.js';
 import { suffixResolve } from './utils.js';
-import type { ImportResult, ResolveCtx } from './types.js';
 
 /**
  * Resolve a Ruby require/require_relative path to a matching .rb file (low-level helper).
@@ -22,18 +23,3 @@ export function resolveRubyImportInternal(
   const pathParts = importPath.replace(/^\.\//, '').split('/').filter(Boolean);
   return suffixResolve(pathParts, normalizedFileList, allFileList, index);
 }
-
-/** Ruby: require / require_relative. */
-export function resolveRubyImport(
-  rawImportPath: string,
-  _filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  const resolved = resolveRubyImportInternal(
-    rawImportPath,
-    ctx.normalizedFileList,
-    ctx.allFileList,
-    ctx.index,
-  );
-  return resolved ? { kind: 'files', files: [resolved] } : null;
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/rust.ts b/gitnexus/src/core/ingestion/import-resolvers/rust.ts
index 632e19352..2d1dd864a 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/rust.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/rust.ts
@@ -1,12 +1,10 @@
 /**
- * Rust module import resolution.
- * Handles crate::, super::, self:: prefix paths and :: separators.
+ * Rust module import resolution — internal helpers.
+ *
+ * Strategy lives in configs/rust.ts.
+ * This file contains shared helpers used by the strategy and standard.ts.
  */
 
-import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ResolveCtx } from './types.js';
-import { resolveStandard } from './standard.js';
-
 /**
  * Resolve Rust use-path to a file (low-level helper).
  * Handles crate::, super::, self:: prefixes and :: path separators.
@@ -84,49 +82,3 @@ export function tryRustModulePath(modulePath: string, allFiles: Set<string>): st
 
   return null;
 }
-
-/** Rust: expand grouped imports: use {crate::a, crate::b} and use crate::models::{User, Repo}. */
-export function resolveRustImport(
-  rawImportPath: string,
-  filePath: string,
-  ctx: ResolveCtx,
-): ImportResult {
-  // Top-level grouped: use {crate::a, crate::b}
-  if (rawImportPath.startsWith('{') && rawImportPath.endsWith('}')) {
-    const inner = rawImportPath.slice(1, -1);
-    const parts = inner
-      .split(',')
-      .map((p) => p.trim())
-      .filter(Boolean);
-    const resolved: string[] = [];
-    for (const part of parts) {
-      const r = resolveRustImportInternal(filePath, part, ctx.allFilePaths);
-      if (r) resolved.push(r);
-    }
-    return resolved.length > 0 ? { kind: 'files', files: resolved } : null;
-  }
-
-  // Scoped grouped: use crate::models::{User, Repo}
-  const braceIdx = rawImportPath.indexOf('::{');
-  if (braceIdx !== -1 && rawImportPath.endsWith('}')) {
-    const pathPrefix = rawImportPath.substring(0, braceIdx);
-    const braceContent = rawImportPath.substring(braceIdx + 3, rawImportPath.length - 1);
-    const items = braceContent
-      .split(',')
-      .map((s) => s.trim())
-      .filter(Boolean);
-    const resolved: string[] = [];
-    for (const item of items) {
-      // Handle `use crate::models::{User, Repo as R}` — strip alias for resolution
-      const itemName = item.includes(' as ') ? item.split(' as ')[0].trim() : item;
-      const r = resolveRustImportInternal(filePath, `${pathPrefix}::${itemName}`, ctx.allFilePaths);
-      if (r) resolved.push(r);
-    }
-    if (resolved.length > 0) return { kind: 'files', files: resolved };
-    // Fallback: resolve the prefix path itself (e.g. crate::models -> models.rs)
-    const prefixResult = resolveRustImportInternal(filePath, pathPrefix, ctx.allFilePaths);
-    if (prefixResult) return { kind: 'files', files: [prefixResult] };
-  }
-
-  return resolveStandard(rawImportPath, filePath, ctx, SupportedLanguages.Rust);
-}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/standard.ts b/gitnexus/src/core/ingestion/import-resolvers/standard.ts
index a29810a2f..f8aae9625 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/standard.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/standard.ts
@@ -8,7 +8,7 @@ import type { SuffixIndex } from './utils.js';
 import { tryResolveWithExtensions, suffixResolve } from './utils.js';
 import { resolveRustImportInternal } from './rust.js';
 import { SupportedLanguages } from 'gitnexus-shared';
-import type { ImportResult, ImportResolverFn, ResolveCtx } from './types.js';
+import type { ImportResult, ImportResolverStrategy, ResolveCtx } from './types.js';
 import type { TsconfigPaths } from '../language-config.js';
 
 /** Max entries in the resolve cache. Beyond this, entries are evicted.
@@ -174,18 +174,11 @@ export function resolveStandard(
   return resolvedPath ? { kind: 'files', files: [resolvedPath] } : null;
 }
 
-/** JavaScript: standard single-file resolution. */
-export const resolveJavascriptImport: ImportResolverFn = (raw, fp, ctx) =>
-  resolveStandard(raw, fp, ctx, SupportedLanguages.JavaScript);
+// ============================================================================
+// Strategy factory — composable hook for ImportResolutionConfig
+// ============================================================================
 
-/** TypeScript: standard single-file resolution. */
-export const resolveTypescriptImport: ImportResolverFn = (raw, fp, ctx) =>
-  resolveStandard(raw, fp, ctx, SupportedLanguages.TypeScript);
-
-/** C: standard single-file resolution for #include directives. */
-export const resolveCImport: ImportResolverFn = (raw, fp, ctx) =>
-  resolveStandard(raw, fp, ctx, SupportedLanguages.C);
-
-/** C++: standard single-file resolution for #include directives. */
-export const resolveCppImport: ImportResolverFn = (raw, fp, ctx) =>
-  resolveStandard(raw, fp, ctx, SupportedLanguages.CPlusPlus);
+/** Create a reusable standard-resolution strategy for a given language. */
+export function createStandardStrategy(language: SupportedLanguages): ImportResolverStrategy {
+  return (raw, fp, ctx) => resolveStandard(raw, fp, ctx, language);
+}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/types.ts b/gitnexus/src/core/ingestion/import-resolvers/types.ts
index 3e68c38b2..66e23a79b 100644
--- a/gitnexus/src/core/ingestion/import-resolvers/types.ts
+++ b/gitnexus/src/core/ingestion/import-resolvers/types.ts
@@ -12,6 +12,7 @@ import type {
 } from '../language-config.js';
 import type { SwiftPackageConfig } from '../language-config.js';
 import type { SuffixIndex } from './utils.js';
+import type { SupportedLanguages } from 'gitnexus-shared';
 
 /**
  * Result of resolving an import via language-specific dispatch.
@@ -53,3 +54,28 @@ export type ImportResolverFn = (
   filePath: string,
   resolveCtx: ResolveCtx,
 ) => ImportResult;
+
+/**
+ * A single import resolution strategy — one step in a composable chain.
+ * Same signature as ImportResolverFn. Returns null to let the next strategy
+ * in the chain try; returns a result (even with empty files) to stop the chain.
+ */
+export type ImportResolverStrategy = ImportResolverFn;
+
+/**
+ * Declarative config for composable import resolution — mirrors the
+ * MethodExtractionConfig / CallExtractionConfig pattern.
+ *
+ * Each language declares an ordered list of strategies to try.
+ * The factory (`createImportResolver`) chains them: first non-null result wins.
+ */
+export interface ImportResolutionConfig {
+  /**
+   * Documentation-only metadata identifying which language this config serves.
+   * **Not used by `createImportResolver`** — the factory only iterates `strategies`.
+   * Useful for logging, debugging, and compile-time exhaustiveness checks when
+   * mapping `SupportedLanguages → ImportResolutionConfig` in language providers.
+   */
+  readonly language: SupportedLanguages;
+  readonly strategies: readonly ImportResolverStrategy[];
+}
diff --git a/gitnexus/src/core/ingestion/import-resolvers/vue.ts b/gitnexus/src/core/ingestion/import-resolvers/vue.ts
deleted file mode 100644
index c46e3f725..000000000
--- a/gitnexus/src/core/ingestion/import-resolvers/vue.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-/**
- * Vue import resolver — delegates to TypeScript's standard resolver.
- *
- * Vue <script> blocks use the same import syntax as TypeScript (including
- * tsconfig path aliases like `@/`), so no custom resolution logic is needed.
- */
-
-import { SupportedLanguages } from 'gitnexus-shared';
-import { resolveStandard } from './standard.js';
-import type { ImportResolverFn } from './types.js';
-
-export const resolveVueImport: ImportResolverFn = (raw, fp, ctx) =>
-  resolveStandard(raw, fp, ctx, SupportedLanguages.TypeScript);
diff --git a/gitnexus/src/core/ingestion/import-target-adapter.ts b/gitnexus/src/core/ingestion/import-target-adapter.ts
new file mode 100644
index 000000000..80a5a265e
--- /dev/null
+++ b/gitnexus/src/core/ingestion/import-target-adapter.ts
@@ -0,0 +1,124 @@
+/**
+ * Bridge between CLI-package per-language `ImportResolverFn`s and the
+ * shared `FinalizeHooks.resolveImportTarget` contract
+ * (RFC §5.2; Ring 2 PKG #922).
+ *
+ * The shared finalize algorithm (#915) asks one question:
+ *
+ *     resolveImportTarget(targetRaw, fromFile, workspaceIndex): string | null
+ *
+ * The CLI already has 16 language-specific resolvers satisfying a
+ * richer signature:
+ *
+ *     ImportResolverFn(rawImportPath, filePath, resolveCtx): ImportResult
+ *
+ * This module builds a dispatch adapter — one FinalizeHook implementation
+ * that looks up the file's language from its path and delegates to the
+ * right per-language resolver. Callers package per-language resolvers +
+ * a shared `ResolveCtx` into an opaque `ImportTargetWorkspace` and pass
+ * it as `workspaceIndex` to `finalizeScopeModel`.
+ *
+ * ## What's deliberately NOT here
+ *
+ *   - **Re-implementation of any per-language resolver.** We wrap the
+ *     existing `importResolver` field on each `LanguageProvider` — the
+ *     same code path the legacy DAG uses today.
+ *   - **Dynamic-import handling.** The shared finalize algorithm short-
+ *     circuits `ParsedImport { kind: 'dynamic-unresolved' }` before
+ *     calling `resolveImportTarget`, so the adapter never sees those.
+ *   - **`importPathPreprocessor`.** Preprocessing belongs inside the
+ *     provider's `interpretImport` hook (which writes the final
+ *     `ParsedImport.targetRaw`). By the time finalize passes a
+ *     `targetRaw` to this adapter, it is the string the provider wants
+ *     resolved verbatim.
+ */
+
+import {
+  getLanguageFromFilename,
+  type SupportedLanguages,
+  type WorkspaceIndex,
+} from 'gitnexus-shared';
+import type { ImportResolverFn, ImportResult, ResolveCtx } from './import-resolvers/types.js';
+import type { LanguageProvider } from './language-provider.js';
+
+/** A single language's resolver bundled with the context it needs. */
+export interface LanguageResolverEntry {
+  readonly resolver: ImportResolverFn;
+  readonly ctx: ResolveCtx;
+}
+
+/**
+ * The opaque `workspaceIndex` shape recognized by
+ * `resolveImportTargetAcrossLanguages`. Built once per ingestion run via
+ * `buildImportTargetWorkspace`, threaded through `finalizeScopeModel`.
+ */
+export interface ImportTargetWorkspace {
+  readonly perLanguage: ReadonlyMap<SupportedLanguages, LanguageResolverEntry>;
+}
+
+/**
+ * Build the workspace index from a map of language → provider. Providers
+ * whose `importResolver` is absent are silently skipped (no language will
+ * ever hit that branch at dispatch time).
+ *
+ * The `resolveCtx` is shared across all languages. Callers assemble it
+ * once per run (the existing pipeline already does this for the legacy
+ * DAG) and hand it to both the legacy resolution path and this factory.
+ */
+export function buildImportTargetWorkspace(
+  providers: ReadonlyMap<SupportedLanguages, LanguageProvider>,
+  resolveCtx: ResolveCtx,
+): ImportTargetWorkspace {
+  const perLanguage = new Map<SupportedLanguages, LanguageResolverEntry>();
+  for (const [lang, provider] of providers) {
+    if (provider.importResolver === undefined) continue;
+    perLanguage.set(lang, { resolver: provider.importResolver, ctx: resolveCtx });
+  }
+  return { perLanguage };
+}
+
+/**
+ * The FinalizeHooks-compatible implementation. Dispatches on `fromFile`'s
+ * extension → per-language resolver. Returns the first resolved file,
+ * or `null` if the resolver returns `null` or doesn't know about the
+ * language.
+ *
+ * Picks the first entry of `files[]` for both `'files'` and `'package'`
+ * result kinds — the legacy pipeline uses the whole array, but the
+ * shared `finalize()` hook contract is single-file. If the workspace
+ * later needs richer semantics (split-target packages), this is the
+ * single site to extend.
+ */
+export function resolveImportTargetAcrossLanguages(
+  targetRaw: string,
+  fromFile: string,
+  workspaceIndex: WorkspaceIndex,
+): string | null {
+  const workspace = workspaceIndex as ImportTargetWorkspace | undefined;
+  if (workspace === undefined || workspace.perLanguage === undefined) return null;
+
+  const lang = getLanguageFromFilename(fromFile);
+  if (lang === null) return null;
+
+  const entry = workspace.perLanguage.get(lang);
+  if (entry === undefined) return null;
+
+  let result: ImportResult;
+  try {
+    result = entry.resolver(targetRaw, fromFile, entry.ctx);
+  } catch {
+    // Existing resolvers can throw on malformed inputs (e.g., Python
+    // relative paths above the workspace root). Swallow — the shared
+    // algorithm treats a null here as `linkStatus: 'unresolved'`, which
+    // is the right fallback.
+    return null;
+  }
+  if (result === null) return null;
+
+  // Both `files` and `package` variants expose a `files` array; the
+  // package variant also carries `dirSuffix` which we ignore at the
+  // FinalizeHook boundary (single-file contract). Legacy consumers
+  // continue to see the full result via `importResolver` directly.
+  const first = result.files[0];
+  return first ?? null;
+}
diff --git a/gitnexus/src/core/ingestion/language-provider.ts b/gitnexus/src/core/ingestion/language-provider.ts
index 736c3b666..351b339a7 100644
--- a/gitnexus/src/core/ingestion/language-provider.ts
+++ b/gitnexus/src/core/ingestion/language-provider.ts
@@ -9,13 +9,36 @@
  * so adding a language to the enum without creating a provider is a compiler error.
  */
 
-import type { SupportedLanguages, MroStrategy } from 'gitnexus-shared';
+import type {
+  SupportedLanguages,
+  MroStrategy,
+  CaptureMatch,
+  BindingRef,
+  TypeRef,
+  Scope,
+  ScopeId,
+  ScopeKind,
+  ScopeTree,
+  ParsedImport,
+  ParsedTypeBinding,
+  SymbolDefinition,
+  Callsite,
+  WorkspaceIndex,
+} from 'gitnexus-shared';
 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';
 import type { ClassExtractor } from './class-types.js';
 import type { ExportChecker } from './export-detection.js';
 import type { FieldExtractor } from './field-extractor.js';
+import type { HeritageExtractor } from './heritage-types.js';
 import type { MethodExtractor } from './method-types.js';
+import type { VariableExtractor } from './variable-types.js';
 import type { ImportResolverFn } from './import-resolvers/types.js';
 import type { NamedBindingExtractorFn } from './named-bindings/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
@@ -155,6 +178,12 @@ interface LanguageProviderConfig {
   readonly mroStrategy?: MroStrategy;
 
   // ── Language-specific extraction hooks ────────────────────────────
+  /** Call extractor for extracting call site information (calledName, callForm,
+   *  receiverName, argCount, mixed chains) from @call / @call.name captures.
+   *  Produced by createCallExtractor() with a per-language CallExtractionConfig.
+   *  Default: undefined — if unset, no calls are extracted for this language.
+   *  All tree-sitter providers MUST supply this. */
+  readonly callExtractor?: CallExtractor;
   /** Field extractor for extracting field/property definitions from class/struct
    *  declarations. Produces FieldInfo[] with name, type, visibility, static,
    *  readonly metadata. Default: undefined (no field extraction). */
@@ -163,10 +192,21 @@ interface LanguageProviderConfig {
    *  declarations. Produces MethodInfo[] with name, parameters, visibility, isAbstract,
    *  isFinal, annotations metadata. Default: undefined (no method extraction). */
   readonly methodExtractor?: MethodExtractor;
+  /** Variable extractor for extracting metadata from module/file-scoped variable,
+   *  constant, and static declarations. Produces VariableInfo with type, visibility,
+   *  isConst, isStatic, isMutable metadata. Default: undefined (no variable extraction). */
+  readonly variableExtractor?: VariableExtractor;
   /** Class/type extractor for deriving canonical qualified names for class-like symbols.
    *  Uses the same provider-driven strategy pattern as method/field extraction so
    *  namespace/package/module rules stay language-specific. */
   readonly classExtractor?: ClassExtractor;
+  /** Heritage extractor for extracting extends/implements/trait-impl relationships
+   *  from tree-sitter @heritage.* captures and call-based heritage (e.g., Ruby
+   *  include/extend/prepend). Produced by createHeritageExtractor() — pass a
+   *  SupportedLanguages value for default behaviour or a full
+   *  HeritageExtractionConfig for languages with custom hooks (Go, Ruby).
+   *  All tree-sitter providers MUST supply this. */
+  readonly heritageExtractor?: HeritageExtractor;
   /** Extract a semantic description for a definition node (e.g., PHP Eloquent
    *  property arrays, relation method descriptions).
    *  Default: undefined (no description extraction). */
@@ -180,10 +220,312 @@ interface LanguageProviderConfig {
    *  Default: undefined (no route files). */
   readonly isRouteFile?: (filePath: string) => boolean;
 
+  // ── Call-resolution DAG hooks ─────────────────────────────────────
+  /**
+   * DAG stage 3 hook: synthesize an implicit receiver when the call site omits one.
+   *
+   * Runs after shared inference (TypeEnv → constructor-map → class-as-receiver →
+   * mixed-chain). Return an `ImplicitReceiverOverride` to overlay all fields onto
+   * `ReceiverEnriched`; return null to keep current state and proceed to stage 4.
+   *
+   * Constraints: MUST return null when an explicit receiver is already set, at
+   * top-level scope, or for built-in methods. Do not mutate input params.
+   * `hint` is opaque to shared stages; consumed by this language's `selectDispatch`.
+   *
+   * Ruby example: bare `serialize` in `Account#call_serialize` →
+   * `{ callForm: 'member', receiverName: 'self', receiverTypeName: 'Account',
+   *    receiverSource: 'implicit-self', hint: 'instance' }`
+   *
+   * @see call-types.ts § ImplicitReceiverOverride
+   * @see selectDispatch (stage 4, reads the hint)
+   *
+   * Default: undefined (no implicit-receiver inference).
+   */
+  readonly inferImplicitReceiver?: (params: {
+    readonly calledName: string;
+    readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+    readonly receiverName: string | undefined;
+    readonly receiverTypeName: string | undefined;
+    readonly callNode: SyntaxNode;
+    readonly filePath: string;
+  }) => ImplicitReceiverOverride | null;
+
+  /**
+   * DAG stage 4 hook: decide dispatch strategy (primary path, fallback, MRO view).
+   *
+   * Runs after stage 3. Return a `DispatchDecision` to override shared defaults;
+   * return null to use `defaultDispatchDecision` (constructor→`'constructor'`,
+   * member→`'owner-scoped'`, free→`'free'`). Most languages return null.
+   *
+   * The hook is responsible for its own gating. `ancestryView` only affects
+   * `'ruby-mixin'` strategy. Singleton-ancestry miss NEVER falls through to
+   * file-scoped fallback in stage 5 (enforced in resolveCallTarget).
+   *
+   * Ruby examples:
+   * - `receiverSource='implicit-self', hint='instance'` →
+   *   `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'instance'}`
+   * - `receiverSource='class-as-receiver'` →
+   *   `{primary: 'owner-scoped', ancestryView: 'singleton'}` (miss null-routes)
+   * - `receiverSource='implicit-self', hint='singleton'` →
+   *   `{primary: 'owner-scoped', fallback: 'free-arity-narrowed', ancestryView: 'singleton'}`
+   *
+   * @see call-types.ts § DispatchDecision
+   * @see call-processor.ts § defaultDispatchDecision, resolveCallTarget
+   *
+   * Default: undefined (use `defaultDispatchDecision`).
+   */
+  readonly selectDispatch?: (params: {
+    readonly calledName: string;
+    readonly callForm: 'free' | 'member' | 'constructor' | undefined;
+    readonly receiverName: string | undefined;
+    readonly receiverTypeName: string | undefined;
+    readonly receiverSource: ReceiverEnriched['receiverSource'];
+    readonly hint: string | undefined;
+  }) => DispatchDecision | null;
+
   // ── Noise filtering ────────────────────────────────────────────────
   /** 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>;
+
+  // ══════════════════════════════════════════════════════════════════════════
+  //  Scope-based resolution hooks (RFC #909 — Ring 1 #911)
+  //
+  //  All hooks below are OPTIONAL with safe defaults so existing providers
+  //  continue to compile unchanged. Ring 2 (#919–#925) wires these into the
+  //  central `ScopeExtractor` + finalize pipeline; Ring 3 per-language
+  //  tickets implement the ones each language needs.
+  //
+  //  See: https://www.notion.so/346dc50b6ed281cfaacbe480bf231d50 §5.2
+  // ══════════════════════════════════════════════════════════════════════════
+
+  // ── Parse phase (per-capture interpretation) ───────────────────────
+
+  /**
+   * Emit scope captures from raw source, **pre-grouped per tree-sitter
+   * query match**. Tree-sitter-based providers run a `scopes.scm` query
+   * and emit one `CaptureMatch` per query match; standalone providers
+   * (COBOL) emit matches from a regex tagger. The return shape is
+   * parser-agnostic: the central `ScopeExtractor` consumes
+   * `CaptureMatch[]` without knowing which parser produced them.
+   *
+   * **Pre-grouping is the provider's job.** The extractor expects each
+   * `CaptureMatch` to correspond to one logical match — e.g., an import
+   * statement match carries `@import.statement` + `@import.source` +
+   * `@import.name` keyed under their capture names. Providers MUST
+   * preserve the tree-sitter match boundaries so the extractor's topic
+   * routing (scope / declaration / import / type-binding / reference)
+   * lands on coherent records.
+   *
+   * 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>`).
+   *
+   * **Sync return.** Tree-sitter query execution and COBOL's regex
+   * tagger are both synchronous; no current or foreseeable provider
+   * needs async work inside this hook. The sync signature lets
+   * `parse-worker.ts` (#920) invoke it inline in its already-sync
+   * per-file loop without cascading `async` through the batch pipeline.
+   *
+   * Default: undefined (language continues to use legacy DAG).
+   */
+  readonly emitScopeCaptures?: (sourceText: string, filePath: string) => readonly CaptureMatch[];
+
+  /**
+   * 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;
+
+  // ── Finalize phase (cross-file + materialization) ──────────────────
+
+  /**
+   * 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[];
+
+  // ── Reference-extraction phase ─────────────────────────────────────
+
+  /**
+   * 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';
+
+  // ── Resolution phase (RFC §4v2) ────────────────────────────────────
+
+  /**
+   * 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. */
diff --git a/gitnexus/src/core/ingestion/languages/c-cpp.ts b/gitnexus/src/core/ingestion/languages/c-cpp.ts
index 5b887634f..37e6da732 100644
--- a/gitnexus/src/core/ingestion/languages/c-cpp.ts
+++ b/gitnexus/src/core/ingestion/languages/c-cpp.ts
@@ -10,10 +10,12 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { cClassConfig, cppClassConfig } from '../class-extractors/configs/c-cpp.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as cCppConfig } from '../type-extractors/c-cpp.js';
 import { cCppExportChecker } from '../export-detection.js';
-import { resolveCImport, resolveCppImport } from '../import-resolvers/standard.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { cImportConfig, cppImportConfig } from '../import-resolvers/configs/c-cpp.js';
 import { C_QUERIES, CPP_QUERIES } from '../tree-sitter-queries.js';
 
 /**
@@ -37,6 +39,11 @@ import {
 } from '../field-extractors/configs/c-cpp.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { cMethodConfig, cppMethodConfig } from '../method-extractors/configs/c-cpp.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { cVariableConfig, cppVariableConfig } from '../variable-extractors/configs/c-cpp.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 const C_BUILT_INS: ReadonlySet<string> = new Set([
   'printf',
@@ -145,16 +152,9 @@ const C_BUILT_INS: ReadonlySet<string> = new Set([
   'put',
 ]);
 
-const cClassExtractor = createClassExtractor({
-  language: SupportedLanguages.C,
-  typeDeclarationNodes: ['struct_specifier', 'enum_specifier'],
-});
+const cClassExtractor = createClassExtractor(cClassConfig);
 
-const cppClassExtractor = createClassExtractor({
-  language: SupportedLanguages.CPlusPlus,
-  typeDeclarationNodes: ['class_specifier', 'struct_specifier', 'enum_specifier'],
-  ancestorScopeNodeTypes: ['namespace_definition', 'class_specifier', 'struct_specifier'],
-});
+const cppClassExtractor = createClassExtractor(cppClassConfig);
 
 /**
  * C/C++ function name extraction — unwraps pointer_declarator / reference_declarator /
@@ -320,14 +320,17 @@ export const cProvider = defineLanguage({
   treeSitterQueries: C_QUERIES,
   typeConfig: cCppConfig,
   exportChecker: cCppExportChecker,
-  importResolver: resolveCImport,
+  importResolver: createImportResolver(cImportConfig),
   importSemantics: 'wildcard-transitive',
+  callExtractor: createCallExtractor(cCallConfig),
   fieldExtractor: createFieldExtractor(cFieldConfig),
   methodExtractor: createMethodExtractor({
     ...cMethodConfig,
     extractFunctionName: cCppExtractFunctionName,
   }),
+  variableExtractor: createVariableExtractor(cVariableConfig),
   classExtractor: cClassExtractor,
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.C),
   labelOverride: cppLabelOverride,
   builtInNames: C_BUILT_INS,
 });
@@ -338,15 +341,18 @@ export const cppProvider = defineLanguage({
   treeSitterQueries: CPP_QUERIES,
   typeConfig: cCppConfig,
   exportChecker: cCppExportChecker,
-  importResolver: resolveCppImport,
+  importResolver: createImportResolver(cppImportConfig),
   importSemantics: 'wildcard-transitive',
   mroStrategy: 'leftmost-base',
+  callExtractor: createCallExtractor(cppCallConfig),
   fieldExtractor: createFieldExtractor(cppFieldConfig),
   methodExtractor: createMethodExtractor({
     ...cppMethodConfig,
     extractFunctionName: cCppExtractFunctionName,
   }),
+  variableExtractor: createVariableExtractor(cppVariableConfig),
   classExtractor: cppClassExtractor,
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.CPlusPlus),
   labelOverride: cppLabelOverride,
   builtInNames: C_BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/csharp.ts b/gitnexus/src/core/ingestion/languages/csharp.ts
index 6ec3a6a8b..a491f339a 100644
--- a/gitnexus/src/core/ingestion/languages/csharp.ts
+++ b/gitnexus/src/core/ingestion/languages/csharp.ts
@@ -8,16 +8,23 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { csharpClassConfig } from '../class-extractors/configs/csharp.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as csharpConfig } from '../type-extractors/csharp.js';
 import { csharpExportChecker } from '../export-detection.js';
-import { resolveCSharpImport } from '../import-resolvers/csharp.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { csharpImportConfig } from '../import-resolvers/configs/csharp.js';
 import { extractCSharpNamedBindings } from '../named-bindings/csharp.js';
 import { CSHARP_QUERIES } from '../tree-sitter-queries.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { csharpCallConfig } from '../call-extractors/configs/csharp.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { csharpConfig as csharpFieldConfig } from '../field-extractors/configs/csharp.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { csharpMethodConfig } from '../method-extractors/configs/csharp.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { csharpVariableConfig } from '../variable-extractors/configs/csharp.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 const BUILT_INS: ReadonlySet<string> = new Set([
   'Console',
@@ -120,30 +127,15 @@ export const csharpProvider = defineLanguage({
   treeSitterQueries: CSHARP_QUERIES,
   typeConfig: csharpConfig,
   exportChecker: csharpExportChecker,
-  importResolver: resolveCSharpImport,
+  importResolver: createImportResolver(csharpImportConfig),
   namedBindingExtractor: extractCSharpNamedBindings,
   interfaceNamePattern: /^I[A-Z]/,
   mroStrategy: 'implements-split',
+  callExtractor: createCallExtractor(csharpCallConfig),
   fieldExtractor: createFieldExtractor(csharpFieldConfig),
   methodExtractor: createMethodExtractor(csharpMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.CSharp,
-    typeDeclarationNodes: [
-      'class_declaration',
-      'interface_declaration',
-      'struct_declaration',
-      'enum_declaration',
-      'record_declaration',
-    ],
-    fileScopeNodeTypes: ['file_scoped_namespace_declaration'],
-    ancestorScopeNodeTypes: [
-      'namespace_declaration',
-      'class_declaration',
-      'interface_declaration',
-      'struct_declaration',
-      'enum_declaration',
-      'record_declaration',
-    ],
-  }),
+  variableExtractor: createVariableExtractor(csharpVariableConfig),
+  classExtractor: createClassExtractor(csharpClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.CSharp),
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/dart.ts b/gitnexus/src/core/ingestion/languages/dart.ts
index 7dc6769c6..130d15deb 100644
--- a/gitnexus/src/core/ingestion/languages/dart.ts
+++ b/gitnexus/src/core/ingestion/languages/dart.ts
@@ -15,15 +15,22 @@ import type { NodeLabel } from 'gitnexus-shared';
 import { FUNCTION_NODE_TYPES } from '../utils/ast-helpers.js';
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { dartClassConfig } from '../class-extractors/configs/dart.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as dartConfig } from '../type-extractors/dart.js';
 import { dartExportChecker } from '../export-detection.js';
-import { resolveDartImport } from '../import-resolvers/dart.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { dartImportConfig } from '../import-resolvers/configs/dart.js';
 import { DART_QUERIES } from '../tree-sitter-queries.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { dartConfig as dartFieldConfig } from '../field-extractors/configs/dart.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { dartMethodConfig } from '../method-extractors/configs/dart.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { dartVariableConfig } from '../variable-extractors/configs/dart.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { dartCallConfig } from '../call-extractors/configs/dart.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 /**
  * Resolve the enclosing function from a `function_body` node by looking at its
@@ -89,15 +96,14 @@ export const dartProvider = defineLanguage({
   treeSitterQueries: DART_QUERIES,
   typeConfig: dartConfig,
   exportChecker: dartExportChecker,
-  importResolver: resolveDartImport,
+  importResolver: createImportResolver(dartImportConfig),
   importSemantics: 'wildcard-leaf',
+  callExtractor: createCallExtractor(dartCallConfig),
   fieldExtractor: createFieldExtractor(dartFieldConfig),
   methodExtractor: createMethodExtractor(dartMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Dart,
-    typeDeclarationNodes: ['class_definition', 'extension_declaration', 'enum_declaration'],
-    ancestorScopeNodeTypes: ['class_definition', 'extension_declaration', 'enum_declaration'],
-  }),
+  variableExtractor: createVariableExtractor(dartVariableConfig),
+  classExtractor: createClassExtractor(dartClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Dart),
   enclosingFunctionFinder: dartEnclosingFunctionFinder,
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/go.ts b/gitnexus/src/core/ingestion/languages/go.ts
index 2a2b35f50..245dc197b 100644
--- a/gitnexus/src/core/ingestion/languages/go.ts
+++ b/gitnexus/src/core/ingestion/languages/go.ts
@@ -11,15 +11,23 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { goClassConfig } from '../class-extractors/configs/go.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as goConfig } from '../type-extractors/go.js';
 import { goExportChecker } from '../export-detection.js';
-import { resolveGoImport } from '../import-resolvers/go.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { goImportConfig } from '../import-resolvers/configs/go.js';
 import { GO_QUERIES } from '../tree-sitter-queries.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { goConfig as goFieldConfig } from '../field-extractors/configs/go.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { goMethodConfig } from '../method-extractors/configs/go.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { goVariableConfig } from '../variable-extractors/configs/go.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { goCallConfig } from '../call-extractors/configs/go.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { goHeritageConfig } from '../heritage-extractors/configs/go.js';
 
 export const goProvider = defineLanguage({
   id: SupportedLanguages.Go,
@@ -27,24 +35,12 @@ export const goProvider = defineLanguage({
   treeSitterQueries: GO_QUERIES,
   typeConfig: goConfig,
   exportChecker: goExportChecker,
-  importResolver: resolveGoImport,
+  importResolver: createImportResolver(goImportConfig),
   importSemantics: 'wildcard-leaf',
+  callExtractor: createCallExtractor(goCallConfig),
   fieldExtractor: createFieldExtractor(goFieldConfig),
   methodExtractor: createMethodExtractor(goMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Go,
-    typeDeclarationNodes: ['type_declaration'],
-    fileScopeNodeTypes: ['package_clause'],
-    extractName(node) {
-      const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
-      return typeSpec?.childForFieldName('name')?.text;
-    },
-    extractType(node) {
-      const typeSpec = node.namedChildren.find((child) => child.type === 'type_spec');
-      const typeNode = typeSpec?.childForFieldName('type');
-      if (typeNode?.type === 'struct_type') return 'Struct';
-      if (typeNode?.type === 'interface_type') return 'Interface';
-      return undefined;
-    },
-  }),
+  variableExtractor: createVariableExtractor(goVariableConfig),
+  classExtractor: createClassExtractor(goClassConfig),
+  heritageExtractor: createHeritageExtractor(goHeritageConfig),
 });
diff --git a/gitnexus/src/core/ingestion/languages/java.ts b/gitnexus/src/core/ingestion/languages/java.ts
index b9fab77f1..4781219d3 100644
--- a/gitnexus/src/core/ingestion/languages/java.ts
+++ b/gitnexus/src/core/ingestion/languages/java.ts
@@ -9,16 +9,23 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { javaClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
 import { javaExportChecker } from '../export-detection.js';
-import { resolveJavaImport } from '../import-resolvers/jvm.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
 import { extractJavaNamedBindings } from '../named-bindings/java.js';
 import { JAVA_QUERIES } from '../tree-sitter-queries.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { javaCallConfig } from '../call-extractors/configs/jvm.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { javaConfig } from '../field-extractors/configs/jvm.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { javaMethodConfig } from '../method-extractors/configs/jvm.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { javaVariableConfig } from '../variable-extractors/configs/jvm.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 export const javaProvider = defineLanguage({
   id: SupportedLanguages.Java,
@@ -26,26 +33,14 @@ export const javaProvider = defineLanguage({
   treeSitterQueries: JAVA_QUERIES,
   typeConfig: javaTypeConfig,
   exportChecker: javaExportChecker,
-  importResolver: resolveJavaImport,
+  importResolver: createImportResolver(javaImportConfig),
   namedBindingExtractor: extractJavaNamedBindings,
   interfaceNamePattern: /^I[A-Z]/,
   mroStrategy: 'implements-split',
+  callExtractor: createCallExtractor(javaCallConfig),
   fieldExtractor: createFieldExtractor(javaConfig),
   methodExtractor: createMethodExtractor(javaMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Java,
-    typeDeclarationNodes: [
-      'class_declaration',
-      'interface_declaration',
-      'enum_declaration',
-      'record_declaration',
-    ],
-    fileScopeNodeTypes: ['package_declaration'],
-    ancestorScopeNodeTypes: [
-      'class_declaration',
-      'interface_declaration',
-      'enum_declaration',
-      'record_declaration',
-    ],
-  }),
+  variableExtractor: createVariableExtractor(javaVariableConfig),
+  classExtractor: createClassExtractor(javaClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Java),
 });
diff --git a/gitnexus/src/core/ingestion/languages/kotlin.ts b/gitnexus/src/core/ingestion/languages/kotlin.ts
index 94c47e7ab..dd65e5d42 100644
--- a/gitnexus/src/core/ingestion/languages/kotlin.ts
+++ b/gitnexus/src/core/ingestion/languages/kotlin.ts
@@ -9,18 +9,25 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { kotlinClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
 import { kotlinTypeConfig } from '../type-extractors/jvm.js';
 import { kotlinExportChecker } from '../export-detection.js';
-import { resolveKotlinImport } from '../import-resolvers/jvm.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { kotlinImportConfig } from '../import-resolvers/configs/jvm.js';
 import { extractKotlinNamedBindings } from '../named-bindings/kotlin.js';
 import { appendKotlinWildcard } from '../import-resolvers/jvm.js';
 import { KOTLIN_QUERIES } from '../tree-sitter-queries.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { kotlinCallConfig } from '../call-extractors/configs/jvm.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { kotlinConfig } from '../field-extractors/configs/jvm.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { kotlinMethodConfig } from '../method-extractors/configs/jvm.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { kotlinVariableConfig } from '../variable-extractors/configs/jvm.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 /** Check if a Kotlin function_declaration capture is inside a class_body (i.e., a method).
  *  Kotlin grammar uses function_declaration for both top-level functions and class methods.
@@ -101,22 +108,16 @@ export const kotlinProvider = defineLanguage({
   treeSitterQueries: KOTLIN_QUERIES,
   typeConfig: kotlinTypeConfig,
   exportChecker: kotlinExportChecker,
-  importResolver: resolveKotlinImport,
+  importResolver: createImportResolver(kotlinImportConfig),
   namedBindingExtractor: extractKotlinNamedBindings,
   importPathPreprocessor: appendKotlinWildcard,
   mroStrategy: 'implements-split',
+  callExtractor: createCallExtractor(kotlinCallConfig),
   fieldExtractor: createFieldExtractor(kotlinConfig),
   methodExtractor: createMethodExtractor(kotlinMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Kotlin,
-    typeDeclarationNodes: ['class_declaration', 'object_declaration', 'companion_object'],
-    fileScopeNodeTypes: ['package_header'],
-    ancestorScopeNodeTypes: ['class_declaration', 'object_declaration', 'companion_object'],
-    extractType(node) {
-      if (node.type !== 'class_declaration') return undefined;
-      return node.children.some((child) => child?.text === 'interface') ? 'Interface' : 'Class';
-    },
-  }),
+  variableExtractor: createVariableExtractor(kotlinVariableConfig),
+  classExtractor: createClassExtractor(kotlinClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Kotlin),
   builtInNames: BUILT_INS,
   labelOverride: (functionNode, defaultLabel) => {
     if (defaultLabel !== 'Function') return defaultLabel;
diff --git a/gitnexus/src/core/ingestion/languages/php.ts b/gitnexus/src/core/ingestion/languages/php.ts
index 642c6bd83..736a63468 100644
--- a/gitnexus/src/core/ingestion/languages/php.ts
+++ b/gitnexus/src/core/ingestion/languages/php.ts
@@ -8,10 +8,12 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { phpClassConfig } from '../class-extractors/configs/php.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as phpConfig } from '../type-extractors/php.js';
 import { phpExportChecker } from '../export-detection.js';
-import { resolvePhpImport } from '../import-resolvers/php.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { phpImportConfig } from '../import-resolvers/configs/php.js';
 import { extractPhpNamedBindings } from '../named-bindings/php.js';
 import { PHP_QUERIES } from '../tree-sitter-queries.js';
 import { findDescendant, extractStringContent, type SyntaxNode } from '../utils/ast-helpers.js';
@@ -20,6 +22,11 @@ import { createFieldExtractor } from '../field-extractors/generic.js';
 import { phpConfig as phpFieldConfig } from '../field-extractors/configs/php.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { phpMethodConfig } from '../method-extractors/configs/php.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { phpVariableConfig } from '../variable-extractors/configs/php.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { phpCallConfig } from '../call-extractors/configs/php.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 const BUILT_INS: ReadonlySet<string> = new Set([
   'echo',
@@ -235,15 +242,14 @@ export const phpProvider = defineLanguage({
   treeSitterQueries: PHP_QUERIES,
   typeConfig: phpConfig,
   exportChecker: phpExportChecker,
-  importResolver: resolvePhpImport,
+  importResolver: createImportResolver(phpImportConfig),
   namedBindingExtractor: extractPhpNamedBindings,
+  callExtractor: createCallExtractor(phpCallConfig),
   fieldExtractor: createFieldExtractor(phpFieldConfig),
   methodExtractor: createMethodExtractor(phpMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.PHP,
-    typeDeclarationNodes: ['class_declaration', 'interface_declaration', 'enum_declaration'],
-    ancestorScopeNodeTypes: ['namespace_definition'],
-  }),
+  variableExtractor: createVariableExtractor(phpVariableConfig),
+  classExtractor: createClassExtractor(phpClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.PHP),
   descriptionExtractor: phpDescriptionExtractor,
   isRouteFile: isPhpRouteFile,
   builtInNames: BUILT_INS,
diff --git a/gitnexus/src/core/ingestion/languages/python.ts b/gitnexus/src/core/ingestion/languages/python.ts
index 8c776d4a0..5773cd3dd 100644
--- a/gitnexus/src/core/ingestion/languages/python.ts
+++ b/gitnexus/src/core/ingestion/languages/python.ts
@@ -12,16 +12,23 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { pythonClassConfig } from '../class-extractors/configs/python.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as pythonConfig } from '../type-extractors/python.js';
 import { pythonExportChecker } from '../export-detection.js';
-import { resolvePythonImport } from '../import-resolvers/python.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { pythonImportConfig } from '../import-resolvers/configs/python.js';
 import { extractPythonNamedBindings } from '../named-bindings/python.js';
 import { PYTHON_QUERIES } from '../tree-sitter-queries.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { pythonConfig as pythonFieldConfig } from '../field-extractors/configs/python.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { pythonMethodConfig } from '../method-extractors/configs/python.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { pythonVariableConfig } from '../variable-extractors/configs/python.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { pythonCallConfig } from '../call-extractors/configs/python.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 const BUILT_INS: ReadonlySet<string> = new Set([
   'print',
@@ -59,16 +66,15 @@ export const pythonProvider = defineLanguage({
   treeSitterQueries: PYTHON_QUERIES,
   typeConfig: pythonConfig,
   exportChecker: pythonExportChecker,
-  importResolver: resolvePythonImport,
+  importResolver: createImportResolver(pythonImportConfig),
   namedBindingExtractor: extractPythonNamedBindings,
   importSemantics: 'namespace',
   mroStrategy: 'c3',
+  callExtractor: createCallExtractor(pythonCallConfig),
   fieldExtractor: createFieldExtractor(pythonFieldConfig),
   methodExtractor: createMethodExtractor(pythonMethodConfig),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Python,
-    typeDeclarationNodes: ['class_definition'],
-    ancestorScopeNodeTypes: ['class_definition'],
-  }),
+  variableExtractor: createVariableExtractor(pythonVariableConfig),
+  classExtractor: createClassExtractor(pythonClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Python),
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/ruby.ts b/gitnexus/src/core/ingestion/languages/ruby.ts
index a15b5439c..e538f3fd2 100644
--- a/gitnexus/src/core/ingestion/languages/ruby.ts
+++ b/gitnexus/src/core/ingestion/languages/ruby.ts
@@ -10,17 +10,45 @@
 import { SupportedLanguages } from 'gitnexus-shared';
 import type { NodeLabel } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { rubyClassConfig } from '../class-extractors/configs/ruby.js';
 import { defineLanguage } from '../language-provider.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
 import { typeConfig as rubyConfig } from '../type-extractors/ruby.js';
 import { routeRubyCall } from '../call-routing.js';
 import { rubyExportChecker } from '../export-detection.js';
-import { resolveRubyImport } from '../import-resolvers/ruby.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { rubyImportConfig } from '../import-resolvers/configs/ruby.js';
 import { RUBY_QUERIES } from '../tree-sitter-queries.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { rubyConfig as rubyFieldConfig } from '../field-extractors/configs/ruby.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { rubyMethodConfig } from '../method-extractors/configs/ruby.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { rubyVariableConfig } from '../variable-extractors/configs/ruby.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { rubyCallConfig } from '../call-extractors/configs/ruby.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
+import { rubyHeritageConfig } from '../heritage-extractors/configs/ruby.js';
+import { maybeRewriteRubyBareCallToSelf } from '../utils/ruby-self-call.js';
+import { findEnclosingClassInfo } from '../utils/ast-helpers.js';
+import type { DispatchDecision, ImplicitReceiverOverride } from '../call-types.js';
+
+/**
+ * Ruby label override. Applied to:
+ *   - `definition.module` captures in the structure phase — remaps to `Trait`
+ *     so Ruby modules are registered in the class-like type registry and are
+ *     therefore resolvable by `lookupClassByName` during mixin heritage
+ *     resolution (`include`/`extend`/`prepend`).
+ *   - `definition.function` captures — Ruby has no bare "function" construct
+ *     (top-level `def` is a method on `main`); return the default so generic
+ *     logic continues to apply.
+ *
+ * Returning `null` means "skip this definition"; we never do that here.
+ */
+const rubyLabelOverride = (_node: SyntaxNode, defaultLabel: NodeLabel): NodeLabel | null => {
+  if (defaultLabel === 'Module') return 'Trait';
+  return defaultLabel;
+};
 
 /** Ruby method/singleton_method: extract name from 'name' field, label as Method. */
 const rubyExtractFunctionName = (
@@ -99,39 +127,109 @@ const BUILT_INS: ReadonlySet<string> = new Set([
   'uniq',
 ]);
 
+/**
+ * Remaps `class << self` (singleton_class) to its enclosing class/module for
+ * receiver inference. A `singleton_class` node is not itself a type — walking
+ * up to the real owner lets `inferImplicitReceiver` set `hint='singleton'`.
+ * Returns null for orphaned singleton_class (no enclosing class/module found).
+ * All other container types are returned as-is.
+ */
+const rubyResolveEnclosingOwner = (node: SyntaxNode): SyntaxNode | null => {
+  if (node.type === 'singleton_class') {
+    let ancestor = node.parent;
+    while (ancestor) {
+      if (ancestor.type === 'class' || ancestor.type === 'module') {
+        return ancestor;
+      }
+      ancestor = ancestor.parent;
+    }
+    return null; // no enclosing class/module — skip
+  }
+  return node; // use as-is for all other container types
+};
+
 export const rubyProvider = defineLanguage({
   id: SupportedLanguages.Ruby,
   extensions: ['.rb', '.rake', '.gemspec'],
   treeSitterQueries: RUBY_QUERIES,
   typeConfig: rubyConfig,
   exportChecker: rubyExportChecker,
-  importResolver: resolveRubyImport,
+  importResolver: createImportResolver(rubyImportConfig),
   callRouter: routeRubyCall,
   importSemantics: 'wildcard-leaf',
-  resolveEnclosingOwner(node) {
-    // Ruby singleton_class (class << self) should resolve to the enclosing
-    // class or module for owner/container resolution (HAS_METHOD edges, class IDs).
-    if (node.type === 'singleton_class') {
-      let ancestor = node.parent;
-      while (ancestor) {
-        if (ancestor.type === 'class' || ancestor.type === 'module') {
-          return ancestor;
-        }
-        ancestor = ancestor.parent;
-      }
-      return null; // no enclosing class/module — skip
-    }
-    return node; // use as-is for all other container types
-  },
+  callExtractor: createCallExtractor(rubyCallConfig),
+  resolveEnclosingOwner: rubyResolveEnclosingOwner,
   fieldExtractor: createFieldExtractor(rubyFieldConfig),
   methodExtractor: createMethodExtractor({
     ...rubyMethodConfig,
     extractFunctionName: rubyExtractFunctionName,
   }),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Ruby,
-    typeDeclarationNodes: ['class'],
-    ancestorScopeNodeTypes: ['module', 'class'],
-  }),
+  variableExtractor: createVariableExtractor(rubyVariableConfig),
+  classExtractor: createClassExtractor(rubyClassConfig),
+  heritageExtractor: createHeritageExtractor(rubyHeritageConfig),
+  labelOverride: rubyLabelOverride,
+  // Ruby MRO is kind-aware: prepend providers beat the class's own method,
+  // which in turn beats include providers. See `lookupMethodByOwnerWithMRO`
+  // in `model/resolve.ts` for the walk order.
+  mroStrategy: 'ruby-mixin',
+
+  // ── DAG hooks ────────────────────────────────────────────────────
+  //
+  // DAG stage 3: rewrite bare calls (e.g. `serialize` in Account#call_serialize)
+  // as `self.serialize` so they route through owner-scoped MRO instead of
+  // global free-call lookup. `dispatchKind` goes into `hint` for stage 4.
+  inferImplicitReceiver: ({
+    calledName,
+    callForm,
+    receiverName,
+    receiverTypeName,
+    callNode,
+    filePath,
+  }): ImplicitReceiverOverride | null => {
+    // Only fire when no receiver has been resolved already.
+    if (receiverName || receiverTypeName) return null;
+    const enclosing = findEnclosingClassInfo(callNode, filePath, rubyResolveEnclosingOwner);
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      calledName,
+      callForm,
+      callNode,
+      enclosing?.className ?? null,
+      { isBuiltInName: (n) => BUILT_INS.has(n), mroStrategy: 'ruby-mixin' },
+    );
+    if (!rewrite) return null;
+    return {
+      callForm: rewrite.callForm,
+      receiverName: rewrite.receiverName,
+      receiverTypeName: rewrite.receiverTypeName,
+      receiverSource: 'implicit-self',
+      hint: rewrite.dispatchKind, // 'instance' | 'singleton'
+    };
+  },
+
+  // DAG stage 4: two Ruby dispatch overrides —
+  //   implicit-self: MRO walk first, fallback to free-arity-narrowed on miss.
+  //   class-as-receiver: singleton ancestry (extend providers only); miss null-routes.
+  selectDispatch: ({ receiverSource, hint }): DispatchDecision | null => {
+    if (receiverSource === 'implicit-self') {
+      // hint='instance' → instance ancestry (prepend→direct→include, see mro-strategy.ts § 'ruby-mixin')
+      // hint='singleton' → singleton ancestry (extend providers only; miss null-routes)
+      const ancestryView: 'instance' | 'singleton' =
+        hint === 'singleton' ? 'singleton' : 'instance';
+      return {
+        primary: 'owner-scoped',
+        fallback: 'free-arity-narrowed',
+        ancestryView,
+      };
+    }
+    if (receiverSource === 'class-as-receiver') {
+      // Class constant receiver (e.g. Account.log): singleton ancestry only; miss null-routes.
+      return {
+        primary: 'owner-scoped',
+        ancestryView: 'singleton',
+      };
+    }
+    return null;
+  },
+
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/rust.ts b/gitnexus/src/core/ingestion/languages/rust.ts
index 5e664ef8f..ac0cd5788 100644
--- a/gitnexus/src/core/ingestion/languages/rust.ts
+++ b/gitnexus/src/core/ingestion/languages/rust.ts
@@ -13,17 +13,24 @@
 import { SupportedLanguages } from 'gitnexus-shared';
 import type { NodeLabel } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { rustClassConfig } from '../class-extractors/configs/rust.js';
 import { defineLanguage } from '../language-provider.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
 import { typeConfig as rustConfig } from '../type-extractors/rust.js';
 import { rustExportChecker } from '../export-detection.js';
-import { resolveRustImport } from '../import-resolvers/rust.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { rustImportConfig } from '../import-resolvers/configs/rust.js';
 import { extractRustNamedBindings } from '../named-bindings/rust.js';
 import { RUST_QUERIES } from '../tree-sitter-queries.js';
 import { createFieldExtractor } from '../field-extractors/generic.js';
 import { rustConfig as rustFieldConfig } from '../field-extractors/configs/rust.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { rustMethodConfig } from '../method-extractors/configs/rust.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { rustVariableConfig } from '../variable-extractors/configs/rust.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { rustCallConfig } from '../call-extractors/configs/rust.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 /** Rust impl_item: find the function_item child and extract its name as a Method. */
 const rustExtractFunctionName = (
@@ -117,18 +124,17 @@ export const rustProvider = defineLanguage({
   treeSitterQueries: RUST_QUERIES,
   typeConfig: rustConfig,
   exportChecker: rustExportChecker,
-  importResolver: resolveRustImport,
+  importResolver: createImportResolver(rustImportConfig),
   namedBindingExtractor: extractRustNamedBindings,
   mroStrategy: 'qualified-syntax',
+  callExtractor: createCallExtractor(rustCallConfig),
   fieldExtractor: createFieldExtractor(rustFieldConfig),
   methodExtractor: createMethodExtractor({
     ...rustMethodConfig,
     extractFunctionName: rustExtractFunctionName,
   }),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Rust,
-    typeDeclarationNodes: ['struct_item', 'enum_item'],
-    ancestorScopeNodeTypes: ['mod_item', 'struct_item', 'enum_item'],
-  }),
+  variableExtractor: createVariableExtractor(rustVariableConfig),
+  classExtractor: createClassExtractor(rustClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Rust),
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/swift.ts b/gitnexus/src/core/ingestion/languages/swift.ts
index 314c27c1d..38f5d8147 100644
--- a/gitnexus/src/core/ingestion/languages/swift.ts
+++ b/gitnexus/src/core/ingestion/languages/swift.ts
@@ -13,10 +13,12 @@
 import { SupportedLanguages } from 'gitnexus-shared';
 import type { NodeLabel } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { swiftClassConfig } from '../class-extractors/configs/swift.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as swiftConfig } from '../type-extractors/swift.js';
 import { swiftExportChecker } from '../export-detection.js';
-import { resolveSwiftImport } from '../import-resolvers/swift.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { swiftImportConfig } from '../import-resolvers/configs/swift.js';
 import { SWIFT_QUERIES } from '../tree-sitter-queries.js';
 import type { SwiftPackageConfig } from '../language-config.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
@@ -24,6 +26,11 @@ import { createFieldExtractor } from '../field-extractors/generic.js';
 import { swiftConfig as swiftFieldConfig } from '../field-extractors/configs/swift.js';
 import { createMethodExtractor } from '../method-extractors/generic.js';
 import { swiftMethodConfig } from '../method-extractors/configs/swift.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { swiftVariableConfig } from '../variable-extractors/configs/swift.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { swiftCallConfig } from '../call-extractors/configs/swift.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 /**
  * Group Swift files by SPM target for implicit module visibility.
@@ -237,26 +244,18 @@ export const swiftProvider = defineLanguage({
   treeSitterQueries: SWIFT_QUERIES,
   typeConfig: swiftConfig,
   exportChecker: swiftExportChecker,
-  importResolver: resolveSwiftImport,
+  importResolver: createImportResolver(swiftImportConfig),
   importSemantics: 'wildcard-leaf',
   heritageDefaultEdge: 'IMPLEMENTS',
+  callExtractor: createCallExtractor(swiftCallConfig),
   fieldExtractor: createFieldExtractor(swiftFieldConfig),
   methodExtractor: createMethodExtractor({
     ...swiftMethodConfig,
     extractFunctionName: swiftExtractFunctionName,
   }),
-  classExtractor: createClassExtractor({
-    language: SupportedLanguages.Swift,
-    typeDeclarationNodes: ['class_declaration', 'protocol_declaration'],
-    ancestorScopeNodeTypes: ['class_declaration', 'protocol_declaration'],
-    extractType(node) {
-      if (node.type === 'protocol_declaration') return 'Interface';
-      if (node.type !== 'class_declaration') return undefined;
-      if (node.children.some((child) => child?.text === 'struct')) return 'Struct';
-      if (node.children.some((child) => child?.text === 'enum')) return 'Enum';
-      return 'Class';
-    },
-  }),
+  variableExtractor: createVariableExtractor(swiftVariableConfig),
+  classExtractor: createClassExtractor(swiftClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.Swift),
   implicitImportWirer: wireSwiftImplicitImports,
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/typescript.ts b/gitnexus/src/core/ingestion/languages/typescript.ts
index b680c5aa1..0a1c3f28f 100644
--- a/gitnexus/src/core/ingestion/languages/typescript.ts
+++ b/gitnexus/src/core/ingestion/languages/typescript.ts
@@ -11,11 +11,18 @@ import { SupportedLanguages } from 'gitnexus-shared';
 import type { NodeLabel } from 'gitnexus-shared';
 import { defineLanguage } from '../language-provider.js';
 import { createClassExtractor } from '../class-extractors/generic.js';
-import type { ClassExtractionConfig } from '../class-types.js';
+import {
+  typescriptClassConfig,
+  javascriptClassConfig,
+} from '../class-extractors/configs/typescript-javascript.js';
 import type { SyntaxNode } from '../utils/ast-helpers.js';
 import { typeConfig as typescriptConfig } from '../type-extractors/typescript.js';
 import { tsExportChecker } from '../export-detection.js';
-import { resolveTypescriptImport, resolveJavascriptImport } from '../import-resolvers/standard.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import {
+  typescriptImportConfig,
+  javascriptImportConfig,
+} from '../import-resolvers/configs/typescript-javascript.js';
 import { extractTsNamedBindings } from '../named-bindings/typescript.js';
 import { TYPESCRIPT_QUERIES, JAVASCRIPT_QUERIES } from '../tree-sitter-queries.js';
 import { typescriptFieldExtractor } from '../field-extractors/typescript.js';
@@ -26,6 +33,17 @@ import {
   typescriptMethodConfig,
   javascriptMethodConfig,
 } from '../method-extractors/configs/typescript-javascript.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import {
+  typescriptVariableConfig,
+  javascriptVariableConfig,
+} from '../variable-extractors/configs/typescript-javascript.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import {
+  typescriptCallConfig,
+  javascriptCallConfig,
+} from '../call-extractors/configs/typescript-javascript.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 /**
  * TypeScript/JavaScript: arrow_function and function_expression get their name
@@ -149,36 +167,23 @@ export const BUILT_INS: ReadonlySet<string> = new Set([
   'valueOf',
 ]);
 
-const tsJsClassConfig: ClassExtractionConfig = {
-  language: SupportedLanguages.TypeScript,
-  typeDeclarationNodes: [
-    'class_declaration',
-    'abstract_class_declaration',
-    'interface_declaration',
-    'enum_declaration',
-  ],
-  ancestorScopeNodeTypes: [
-    'class_declaration',
-    'abstract_class_declaration',
-    'interface_declaration',
-    'enum_declaration',
-  ],
-};
-
 export const typescriptProvider = defineLanguage({
   id: SupportedLanguages.TypeScript,
   extensions: ['.ts', '.tsx'],
   treeSitterQueries: TYPESCRIPT_QUERIES,
   typeConfig: typescriptConfig,
   exportChecker: tsExportChecker,
-  importResolver: resolveTypescriptImport,
+  importResolver: createImportResolver(typescriptImportConfig),
   namedBindingExtractor: extractTsNamedBindings,
+  callExtractor: createCallExtractor(typescriptCallConfig),
   fieldExtractor: typescriptFieldExtractor,
   methodExtractor: createMethodExtractor({
     ...typescriptMethodConfig,
     extractFunctionName: tsExtractFunctionName,
   }),
-  classExtractor: createClassExtractor(tsJsClassConfig),
+  variableExtractor: createVariableExtractor(typescriptVariableConfig),
+  classExtractor: createClassExtractor(typescriptClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.TypeScript),
   builtInNames: BUILT_INS,
 });
 
@@ -188,16 +193,16 @@ export const javascriptProvider = defineLanguage({
   treeSitterQueries: JAVASCRIPT_QUERIES,
   typeConfig: typescriptConfig,
   exportChecker: tsExportChecker,
-  importResolver: resolveJavascriptImport,
+  importResolver: createImportResolver(javascriptImportConfig),
   namedBindingExtractor: extractTsNamedBindings,
+  callExtractor: createCallExtractor(javascriptCallConfig),
   fieldExtractor: createFieldExtractor(javascriptConfig),
   methodExtractor: createMethodExtractor({
     ...javascriptMethodConfig,
     extractFunctionName: tsExtractFunctionName,
   }),
-  classExtractor: createClassExtractor({
-    ...tsJsClassConfig,
-    language: SupportedLanguages.JavaScript,
-  }),
+  variableExtractor: createVariableExtractor(javascriptVariableConfig),
+  classExtractor: createClassExtractor(javascriptClassConfig),
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.JavaScript),
   builtInNames: BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/languages/vue.ts b/gitnexus/src/core/ingestion/languages/vue.ts
index 20ccdfa18..51ab37882 100644
--- a/gitnexus/src/core/ingestion/languages/vue.ts
+++ b/gitnexus/src/core/ingestion/languages/vue.ts
@@ -13,14 +13,21 @@
 
 import { SupportedLanguages } from 'gitnexus-shared';
 import { createClassExtractor } from '../class-extractors/generic.js';
+import { vueClassConfig } from '../class-extractors/configs/typescript-javascript.js';
 import { defineLanguage } from '../language-provider.js';
 import { typeConfig as typescriptConfig } from '../type-extractors/typescript.js';
 import { tsExportChecker } from '../export-detection.js';
-import { resolveVueImport } from '../import-resolvers/vue.js';
+import { createImportResolver } from '../import-resolvers/resolver-factory.js';
+import { vueImportConfig } from '../import-resolvers/configs/typescript-javascript.js';
 import { extractTsNamedBindings } from '../named-bindings/typescript.js';
 import { TYPESCRIPT_QUERIES } from '../tree-sitter-queries.js';
 import { typescriptFieldExtractor } from '../field-extractors/typescript.js';
 import { BUILT_INS as TS_BUILT_INS } from './typescript.js';
+import { createVariableExtractor } from '../variable-extractors/generic.js';
+import { typescriptVariableConfig } from '../variable-extractors/configs/typescript-javascript.js';
+import { createCallExtractor } from '../call-extractors/generic.js';
+import { typescriptCallConfig } from '../call-extractors/configs/typescript-javascript.js';
+import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 
 const VUE_SPECIFIC_BUILT_INS = [
   'ref',
@@ -56,21 +63,7 @@ const VUE_SPECIFIC_BUILT_INS = [
 
 const VUE_BUILT_INS: ReadonlySet<string> = new Set([...TS_BUILT_INS, ...VUE_SPECIFIC_BUILT_INS]);
 
-const vueClassExtractor = createClassExtractor({
-  language: SupportedLanguages.Vue,
-  typeDeclarationNodes: [
-    'class_declaration',
-    'abstract_class_declaration',
-    'interface_declaration',
-    'enum_declaration',
-  ],
-  ancestorScopeNodeTypes: [
-    'class_declaration',
-    'abstract_class_declaration',
-    'interface_declaration',
-    'enum_declaration',
-  ],
-});
+const vueClassExtractor = createClassExtractor(vueClassConfig);
 
 export const vueProvider = defineLanguage({
   id: SupportedLanguages.Vue,
@@ -78,9 +71,12 @@ export const vueProvider = defineLanguage({
   treeSitterQueries: TYPESCRIPT_QUERIES,
   typeConfig: typescriptConfig,
   exportChecker: tsExportChecker,
-  importResolver: resolveVueImport,
+  importResolver: createImportResolver(vueImportConfig),
   namedBindingExtractor: extractTsNamedBindings,
+  callExtractor: createCallExtractor(typescriptCallConfig),
   fieldExtractor: typescriptFieldExtractor,
+  variableExtractor: createVariableExtractor(typescriptVariableConfig),
   classExtractor: vueClassExtractor,
+  heritageExtractor: createHeritageExtractor(SupportedLanguages.TypeScript),
   builtInNames: VUE_BUILT_INS,
 });
diff --git a/gitnexus/src/core/ingestion/model/field-registry.ts b/gitnexus/src/core/ingestion/model/field-registry.ts
index 45fe5c86a..62376c889 100644
--- a/gitnexus/src/core/ingestion/model/field-registry.ts
+++ b/gitnexus/src/core/ingestion/model/field-registry.ts
@@ -5,7 +5,7 @@
  * Stores Property symbols keyed by `ownerNodeId\0fieldName` for O(1) lookup.
  */
 
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 
 // ---------------------------------------------------------------------------
 // Public read-only interface
diff --git a/gitnexus/src/core/ingestion/model/heritage-map.ts b/gitnexus/src/core/ingestion/model/heritage-map.ts
index 16ecf3305..ae89022b4 100644
--- a/gitnexus/src/core/ingestion/model/heritage-map.ts
+++ b/gitnexus/src/core/ingestion/model/heritage-map.ts
@@ -87,11 +87,47 @@ export const resolveExtendsType = (
 /** Maximum ancestor chain depth to prevent runaway traversal. */
 const MAX_ANCESTOR_DEPTH = 32;
 
+/**
+ * Direct parent entry with the heritage kind that produced it. Preserved
+ * so kind-aware consumers (Ruby MRO, see `lookupMethodByOwnerWithMRO`) can
+ * walk prepend/include providers in the correct order. Flat-string consumers
+ * use `getParents` / `getAncestors` and see only the parent nodeIds.
+ */
+export interface ParentEntry {
+  readonly parentId: string;
+  /** 'extends' | 'implements' | 'trait-impl' | 'include' | 'extend' | 'prepend' */
+  readonly kind: string;
+}
+
 export interface HeritageMap {
   /** Direct parents of `childNodeId` (extends + implements + trait-impl). */
   getParents(childNodeId: string): string[];
   /** Full ancestor chain (BFS, bounded depth, cycle-safe). */
   getAncestors(childNodeId: string): string[];
+  /**
+   * Direct parents with heritage kind preserved, insertion-ordered. Used by
+   * kind-aware consumers (Ruby MRO) that need to distinguish prepend /
+   * include / extend / extends for walk-order decisions.
+   *
+   * Insertion order mirrors the order `ExtractedHeritage` records were fed
+   * into `buildHeritageMap`, which in turn mirrors tree-sitter match order.
+   * For Ruby, this matches source declaration order for `prepend` / `include`
+   * statements — the MRO walk reverses this (last-declared-first) at the
+   * consumer side.
+   */
+  getParentEntries(childNodeId: string): readonly ParentEntry[];
+  /**
+   * Ordered ancestry for instance method dispatch (Ruby-aware): includes
+   * `extends`, `implements`, `trait-impl`, `include`, `prepend` kinds.
+   * Excludes `extend` (singleton-only). Order is caller-determined in Unit 3.
+   * For non-Ruby callers (first-wins, c3, etc.), this matches `getAncestors`.
+   */
+  getInstanceAncestry(childNodeId: string): readonly ParentEntry[];
+  /**
+   * Ordered ancestry for singleton / class-method dispatch (Ruby-aware):
+   * only `extend` kind parents. For non-Ruby languages this is always empty.
+   */
+  getSingletonAncestry(childNodeId: string): readonly ParentEntry[];
   /**
    * File paths of classes that directly implement or extend-as-interface the
    * given interface/abstract-class **name**. Replaces the standalone
@@ -130,8 +166,12 @@ export const buildHeritageMap = (
   ctx: ResolutionContext,
   getHeritageStrategy?: HeritageStrategyLookup,
 ): HeritageMap => {
-  // childNodeId → Set<parentNodeId>  (Set to deduplicate cross-chunk duplicates)
-  const directParents = new Map<string, Set<string>>();
+  // childNodeId → insertion-ordered array of { parentId, kind }.
+  // Ordered array (not Set) because Ruby MRO walk depends on declaration
+  // order. A parallel `seen` map dedupes `(parentId, kind)` pairs without
+  // losing order.
+  const directParents = new Map<string, ParentEntry[]>();
+  const seenParents = new Map<string, Set<string>>();
 
   // interfaceName → Set<filePath>  (implementor lookup for interface dispatch)
   const implementorFiles = new Map<string, Set<string>>();
@@ -149,10 +189,23 @@ export const buildHeritageMap = (
 
           let parents = directParents.get(child.nodeId);
           if (!parents) {
-            parents = new Set();
+            parents = [];
             directParents.set(child.nodeId, parents);
           }
-          parents.add(parent.nodeId);
+          let seen = seenParents.get(child.nodeId);
+          if (!seen) {
+            seen = new Set();
+            seenParents.set(child.nodeId, seen);
+          }
+          // Dedup by `parentId + kind` so the same parent under two different
+          // kinds (e.g. a module that is both included and prepended — legal
+          // Ruby though unusual) is recorded twice; the consumer needs both
+          // kinds in the walk. A single (parent, kind) pair is deduped.
+          const key = `${parent.nodeId}|${h.kind}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            parents.push({ parentId: parent.nodeId, kind: h.kind });
+          }
         }
       }
     }
@@ -191,9 +244,30 @@ export const buildHeritageMap = (
 
   // --- Public API ---------------------------------------------------
 
+  /** Internal helper: return the entries array (may be undefined). */
+  const entriesFor = (nodeId: string): readonly ParentEntry[] | undefined =>
+    directParents.get(nodeId);
+
+  const getParentEntries = (childNodeId: string): readonly ParentEntry[] => {
+    const entries = entriesFor(childNodeId);
+    return entries ?? [];
+  };
+
   const getParents = (childNodeId: string): string[] => {
-    const parents = directParents.get(childNodeId);
-    return parents ? [...parents] : [];
+    const entries = entriesFor(childNodeId);
+    if (!entries) return [];
+    // Deduplicate parent ids across kinds so the flat-string contract
+    // (used by non-Ruby MRO strategies and by the C3 linearizer) stays
+    // identical to its pre-kind-awareness behavior.
+    const out: string[] = [];
+    const seen = new Set<string>();
+    for (const e of entries) {
+      if (!seen.has(e.parentId)) {
+        seen.add(e.parentId);
+        out.push(e.parentId);
+      }
+    }
+    return out;
   };
 
   const getAncestors = (childNodeId: string): string[] => {
@@ -212,10 +286,13 @@ export const buildHeritageMap = (
         visited.add(parentId);
         result.push(parentId);
         // Expand parent's own parents for next level
-        const grandparents = directParents.get(parentId);
+        const grandparents = entriesFor(parentId);
         if (grandparents) {
+          const gpSeen = new Set<string>();
           for (const gp of grandparents) {
-            if (!visited.has(gp)) nextFrontier.push(gp);
+            if (gpSeen.has(gp.parentId)) continue;
+            gpSeen.add(gp.parentId);
+            if (!visited.has(gp.parentId)) nextFrontier.push(gp.parentId);
           }
         }
       }
@@ -226,9 +303,77 @@ export const buildHeritageMap = (
     return result;
   };
 
+  /**
+   * Lazy-computed per-owner split of direct parents into instance-dispatch
+   * (non-`extend`) and singleton-dispatch (`extend`-only) views. Memoized on
+   * first request so the `.filter()` pass happens at most once per owner per
+   * HeritageMap lifetime, not per call-site dispatch.
+   *
+   * Shared empty-array sentinels for owners with no entries in a given view
+   * avoid per-call allocation when the split is asymmetric (common Ruby case:
+   * a class has `include` but no `extend`, so its singleton view is empty).
+   */
+  const EMPTY_PARENT_ENTRIES: readonly ParentEntry[] = [];
+  const splitCache = new Map<
+    string,
+    { instance: readonly ParentEntry[]; singleton: readonly ParentEntry[] }
+  >();
+
+  const splitForOwner = (
+    childNodeId: string,
+  ): { instance: readonly ParentEntry[]; singleton: readonly ParentEntry[] } => {
+    let cached = splitCache.get(childNodeId);
+    if (cached) return cached;
+    const entries = entriesFor(childNodeId);
+    if (!entries || entries.length === 0) {
+      cached = { instance: EMPTY_PARENT_ENTRIES, singleton: EMPTY_PARENT_ENTRIES };
+    } else {
+      const instance: ParentEntry[] = [];
+      const singleton: ParentEntry[] = [];
+      for (const e of entries) {
+        if (e.kind === 'extend') singleton.push(e);
+        else instance.push(e);
+      }
+      cached = {
+        instance: instance.length === 0 ? EMPTY_PARENT_ENTRIES : instance,
+        singleton: singleton.length === 0 ? EMPTY_PARENT_ENTRIES : singleton,
+      };
+    }
+    splitCache.set(childNodeId, cached);
+    return cached;
+  };
+
+  /**
+   * Instance-dispatch ancestry walk. Excludes `extend` (singleton-only).
+   * For kind-aware consumers (Ruby MRO): walks parents in source-insertion
+   * order. The consumer is responsible for interleaving self / reversing
+   * prepend order / etc. This method preserves raw declaration order.
+   *
+   * Result is cached per owner; repeat calls return the same array.
+   */
+  const getInstanceAncestry = (childNodeId: string): readonly ParentEntry[] =>
+    splitForOwner(childNodeId).instance;
+
+  /**
+   * Singleton-dispatch ancestry walk. Only `extend` parents. For non-Ruby
+   * languages this is always empty (no language currently produces `extend`
+   * heritage records outside Ruby).
+   *
+   * Result is cached per owner; repeat calls return the same array.
+   */
+  const getSingletonAncestry = (childNodeId: string): readonly ParentEntry[] =>
+    splitForOwner(childNodeId).singleton;
+
   const getImplementorFiles = (interfaceName: string): ReadonlySet<string> => {
     return implementorFiles.get(interfaceName) ?? EMPTY_SET;
   };
 
-  return { getParents, getAncestors, getImplementorFiles };
+  return {
+    getParents,
+    getAncestors,
+    getParentEntries,
+    getInstanceAncestry,
+    getSingletonAncestry,
+    getImplementorFiles,
+  };
 };
diff --git a/gitnexus/src/core/ingestion/model/index.ts b/gitnexus/src/core/ingestion/model/index.ts
index 27f939171..d5398e6b7 100644
--- a/gitnexus/src/core/ingestion/model/index.ts
+++ b/gitnexus/src/core/ingestion/model/index.ts
@@ -26,7 +26,17 @@ export {
   type SymbolTableReader,
   type SymbolTableWriter,
   createSymbolTable,
+  type AddMetadata,
+  CLASS_TYPES,
+  CLASS_TYPES_TUPLE,
+  type ClassLikeLabel,
+  FREE_CALLABLE_TYPES,
+  FREE_CALLABLE_TUPLE,
+  type FreeCallableLabel,
+  CALL_TARGET_TYPES,
 } from './symbol-table.js';
+// `SymbolDefinition` moved to `gitnexus-shared` (RFC #909 Ring 1 #910).
+// Consumers should import it directly from `gitnexus-shared`, not via this barrel.
 
 // Type registry (classes, structs, interfaces, enums, records, impls)
 export {
@@ -63,11 +73,12 @@ export {
   isFileInPackageDir,
 } from './resolution-context.js';
 
-// Heritage types. `buildHeritageMap` + `resolveExtendsType` are exported
-// directly from `heritage-map.ts` and are not re-surfaced here to keep
-// the barrel narrow.
+// Heritage types and builder. `buildHeritageMap` + `resolveExtendsType` are
+// exported directly from `heritage-map.ts` and are not re-surfaced here to
+// keep the barrel narrow.
 export {
   type ExtractedHeritage,
+  type HeritageMap,
   type HeritageResolutionStrategy,
   type HeritageStrategyLookup,
 } from './heritage-map.js';
diff --git a/gitnexus/src/core/ingestion/model/method-registry.ts b/gitnexus/src/core/ingestion/model/method-registry.ts
index be28e5782..327f568e7 100644
--- a/gitnexus/src/core/ingestion/model/method-registry.ts
+++ b/gitnexus/src/core/ingestion/model/method-registry.ts
@@ -7,7 +7,7 @@
  * (array values) and arity-based filtering.
  */
 
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 
 // ---------------------------------------------------------------------------
 // Public read-only interface
diff --git a/gitnexus/src/core/ingestion/model/registration-table.ts b/gitnexus/src/core/ingestion/model/registration-table.ts
index a5bb14f21..6e0e2646d 100644
--- a/gitnexus/src/core/ingestion/model/registration-table.ts
+++ b/gitnexus/src/core/ingestion/model/registration-table.ts
@@ -49,8 +49,8 @@
  * `NodeLabel` is missing from all three sets.
  */
 
-import type { NodeLabel } from 'gitnexus-shared';
-import type { SymbolDefinition, ClassLikeLabel, FreeCallableLabel } from './symbol-table.js';
+import type { NodeLabel, SymbolDefinition } from 'gitnexus-shared';
+import type { ClassLikeLabel, FreeCallableLabel } from './symbol-table.js';
 import { FREE_CALLABLE_TYPES } from './symbol-table.js';
 import type { MutableTypeRegistry } from './type-registry.js';
 import type { MutableMethodRegistry } from './method-registry.js';
diff --git a/gitnexus/src/core/ingestion/model/resolution-context.ts b/gitnexus/src/core/ingestion/model/resolution-context.ts
index b56524b36..45f94d698 100644
--- a/gitnexus/src/core/ingestion/model/resolution-context.ts
+++ b/gitnexus/src/core/ingestion/model/resolution-context.ts
@@ -18,7 +18,8 @@
  *   (three O(1) index lookups with a narrow, type-specific result set).
  */
 
-import type { SymbolDefinition, SymbolTableReader } from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
+import type { SymbolTableReader } from './symbol-table.js';
 import type { MutableSemanticModel } from './semantic-model.js';
 import { createSemanticModel } from './semantic-model.js';
 
diff --git a/gitnexus/src/core/ingestion/model/resolve.ts b/gitnexus/src/core/ingestion/model/resolve.ts
index 0fcf1e8b3..62653a762 100644
--- a/gitnexus/src/core/ingestion/model/resolve.ts
+++ b/gitnexus/src/core/ingestion/model/resolve.ts
@@ -6,7 +6,7 @@
  * on resolution-context.ts (circular dependency risk).
  */
 
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 import type { SemanticModel } from './semantic-model.js';
 import type { HeritageMap } from './heritage-map.js';
 import type { MroStrategy } from 'gitnexus-shared';
@@ -22,14 +22,18 @@ import type { MroStrategy } from 'gitnexus-shared';
 /**
  * Gather all ancestor IDs in BFS / topological order.
  * Returns the linearized list of ancestor IDs (excluding the class itself).
+ *
+ * Uses a head-pointer BFS (`queue[head++]`) instead of `Array.shift()` to
+ * avoid O(n) per-dequeue re-indexing — matching `buildParentMapFromHeritage`.
  */
 function gatherAncestors(classId: string, parentMap: Map<string, string[]>): string[] {
   const visited = new Set<string>();
   const order: string[] = [];
   const queue: string[] = [...(parentMap.get(classId) ?? [])];
+  let head = 0;
 
-  while (queue.length > 0) {
-    const id = queue.shift()!;
+  while (head < queue.length) {
+    const id = queue[head++]!;
     if (visited.has(id)) continue;
     visited.add(id);
     order.push(id);
@@ -274,33 +278,24 @@ const buildParentMapFromHeritage = (
 // ---------------------------------------------------------------------------
 
 /**
- * Look up a method on an owner class, walking the parent chain via HeritageMap
- * when the method isn't found on the direct owner.
+ * DAG stage 5 helper: look up a method on an owner class via MRO walk.
  *
- * Respects the 5 per-language MRO strategies:
- * - `first-wins`:       BFS ancestor walk, first match wins (default)
- * - `leftmost-base`:    BFS ancestor walk, leftmost base in declaration order wins (C++);
- *                        HeritageMap preserves insertion order matching source declaration,
- *                        so BFS order is equivalent to leftmost-base semantics
- * - `c3`:               C3-linearized ancestor order, first match wins (Python)
- * - `implements-split`: BFS ancestor walk, first match wins (Java/C#) —
- *                        full ambiguity detection for multiple interface defaults
- *                        is handled by computeMRO at graph level
- * - `qualified-syntax`: No auto-resolution (Rust) — returns undefined
+ * Low-level resolver; no dependency on SymbolTable, language registry, or
+ * resolution-context (keeps model/ layer free of cross-layer imports).
+ * All strategies respect `argCount` for overload narrowing.
+ * `ancestryOverride` replaces the default walk; caller must compute it correctly.
  *
- * Uses the `c3Linearize` defined in this file (also consumed by
- * mro-processor.ts for graph-level MRO emission) for the `c3` strategy.
+ * Strategy summary (full docs in gitnexus-shared/mro-strategy.ts):
+ * - `first-wins` / `leftmost-base` / `implements-split`: BFS, first match wins.
+ * - `c3`: C3-linearized order; falls back to BFS on cycle/inconsistency.
+ * - `qualified-syntax`: returns undefined immediately (Rust requires explicit syntax).
+ * - `ruby-mixin`: kind-aware walk — see inline comments below.
  *
- * Depends only on {@link SemanticModel} + {@link HeritageMap} + an
- * {@link MroStrategy} literal — NO dependency on SymbolTable, the language
- * registry, or resolution-context, which keeps the `model/` module free of
- * cross-layer imports. Callers derive the strategy from their language
- * provider before invoking this function.
+ * Internal API: exported for call-processor resolvers and tests.
+ * External callers should use resolveMemberCall instead.
  *
- * @internal This is the low-level MRO walker. Exported so call-processor's
- * higher-level resolvers (and unit tests) can invoke it directly. Callers
- * outside `core/ingestion/` should use the higher-level resolvers in
- * call-processor.ts instead of depending on this function.
+ * @see gitnexus-shared/mro-strategy.ts § 'ruby-mixin'
+ * @see call-processor.ts § resolveMemberCall
  */
 export const lookupMethodByOwnerWithMRO = (
   ownerNodeId: string,
@@ -309,7 +304,91 @@ export const lookupMethodByOwnerWithMRO = (
   model: SemanticModel,
   strategy: MroStrategy,
   argCount?: number,
+  /**
+   * Optional pre-computed ancestry list. When provided, overrides the default
+   * per-strategy ancestry source. Primarily used by Ruby singleton dispatch:
+   * the caller supplies `heritageMap.getSingletonAncestry(ownerNodeId)` as
+   * node-id array so this walker resolves against `extend` providers only.
+   *
+   * For `ruby-mixin` strategy, passing an override switches the walker into
+   * a no-prepend-no-direct linear scan (the caller has already decided the
+   * order), which is the correct semantics for singleton dispatch.
+   */
+  ancestryOverride?: readonly string[],
 ): SymbolDefinition | undefined => {
+  // ── Ruby mixin strategy ───────────────────────────────────────────
+  // Kind-aware walk — does NOT short-circuit on direct owner first (prepend beats direct).
+  // Instance dispatch: prepend (reverse) → direct → include (reverse) → transitive BFS.
+  // Singleton dispatch: caller supplies ancestryOverride (extend providers only);
+  //   simple left-to-right scan. Miss NEVER falls through to file-scoped fallback.
+  // See gitnexus-shared/mro-strategy.ts § 'ruby-mixin' for full strategy docs.
+  if (strategy === 'ruby-mixin') {
+    if (ancestryOverride) {
+      // Singleton dispatch: scan pre-computed ancestry only. Miss null-routes.
+      for (const ancestorId of ancestryOverride) {
+        const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+        if (method) return method;
+      }
+      return undefined;
+    }
+
+    // Instance dispatch — kind-aware walk per the pseudocode above.
+    const instanceEntries = heritageMap.getInstanceAncestry(ownerNodeId);
+    // Partition into prepend parents vs other parents (extends / include /
+    // implements / trait-impl), preserving declaration order within each.
+    const prependParents: string[] = [];
+    const otherParents: string[] = [];
+    for (const e of instanceEntries) {
+      if (e.kind === 'prepend') prependParents.push(e.parentId);
+      else otherParents.push(e.parentId);
+    }
+
+    // Step 1: Walk prepend parents in REVERSE declaration order (last-prepended wins).
+    for (let i = prependParents.length - 1; i >= 0; i--) {
+      const method = model.methods.lookupMethodByOwner(prependParents[i], methodName, argCount);
+      if (method) return method;
+    }
+
+    // Step 2: Direct owner lookup (the class's own method).
+    // This is the only difference from other strategies — prepend beats direct.
+    const direct = model.methods.lookupMethodByOwner(ownerNodeId, methodName, argCount);
+    if (direct) return direct;
+
+    // Step 3: Walk extends + include parents in REVERSE declaration order.
+    // (Ruby `include A; include B` puts B ahead of A in MRO.)
+    for (let i = otherParents.length - 1; i >= 0; i--) {
+      const method = model.methods.lookupMethodByOwner(otherParents[i], methodName, argCount);
+      if (method) return method;
+    }
+
+    // Step 4: Transitive ancestors (a mixin that itself mixes in another module).
+    // Fall back to the BFS ancestor walk for depth > 1. Order is best-effort;
+    // Ruby's actual MRO for transitive mixins is rare and under-specified
+    // (documented in architecture docs as deferred work).
+    //
+    // O(1) skip-check via Sets:
+    //   - `walkedDirect` covers parents already visited in steps 1-3.
+    //   - `singletonOnly` covers direct `extend` providers: they belong to
+    //     the singleton MRO and must NEVER appear in instance dispatch.
+    // Building Sets once before the BFS loop avoids O(n²) `Array.includes`
+    // on large mixin hierarchies.
+    const walkedDirect = new Set<string>(prependParents);
+    for (const id of otherParents) walkedDirect.add(id);
+    const singletonOnly = new Set<string>(
+      heritageMap.getSingletonAncestry(ownerNodeId).map((e) => e.parentId),
+    );
+    for (const ancestorId of heritageMap.getAncestors(ownerNodeId)) {
+      if (ancestorId === ownerNodeId) continue;
+      if (walkedDirect.has(ancestorId)) continue;
+      if (singletonOnly.has(ancestorId)) continue;
+      const method = model.methods.lookupMethodByOwner(ancestorId, methodName, argCount);
+      if (method) return method;
+    }
+    return undefined;
+  }
+
+  // ── Non-Ruby strategies: direct-owner-first short-circuit ─────────
+
   // Direct lookup first (child override — no walk needed).
   // argCount is threaded through so arity-differing overloads on the direct
   // owner can be disambiguated before the MRO walk starts.
@@ -322,7 +401,9 @@ export const lookupMethodByOwnerWithMRO = (
   // Determine ancestor walk order based on MRO strategy.
   // readonly to accept the cached (frozen) c3 linearization without copying.
   let ancestors: readonly string[];
-  if (strategy === 'c3') {
+  if (ancestryOverride) {
+    ancestors = ancestryOverride;
+  } else if (strategy === 'c3') {
     // C3 linearization (memoized per HeritageMap
     // so repeated calls for the same owner within an ingestion run reuse the
     // linearization instead of rebuilding the parent map and re-running C3).
diff --git a/gitnexus/src/core/ingestion/model/scope-resolution-indexes.ts b/gitnexus/src/core/ingestion/model/scope-resolution-indexes.ts
new file mode 100644
index 000000000..67e32fc0e
--- /dev/null
+++ b/gitnexus/src/core/ingestion/model/scope-resolution-indexes.ts
@@ -0,0 +1,73 @@
+/**
+ * `ScopeResolutionIndexes` — the bundle of materialized indexes produced
+ * by the finalize-orchestrator (RFC #909 Ring 2 PKG #921) and attached
+ * to `MutableSemanticModel`.
+ *
+ * Produced by `finalizeScopeModel(parsedFiles, hooks)` in
+ * `finalize-orchestrator.ts`. Consumed by the resolution phase (future
+ * tickets) where `Registry.lookup` / `resolveTypeRef` query this bundle
+ * to answer call-resolution questions without re-walking any AST.
+ *
+ * ## Lifecycle
+ *
+ *   1. Pipeline collects `ParsedFile[]` from the parsing-processor (#920).
+ *   2. Pipeline invokes `finalizeScopeModel(parsedFiles, hooks)` →
+ *      returns a `ScopeResolutionIndexes` (this interface).
+ *   3. Pipeline calls `model.attachScopeIndexes(indexes)` to stamp them
+ *      onto the `MutableSemanticModel`. This is a **one-shot write**;
+ *      subsequent calls throw. After attachment, the indexes are frozen
+ *      at the type level (everything is `readonly`) and at runtime via
+ *      `Object.freeze` on the bundle.
+ *   4. Resolution callers hold a `SemanticModel` reference and read
+ *      `model.scopes` to query.
+ *
+ * ## Content
+ *
+ *   - `scopeTree` / `moduleScopes` / `defs` / `qualifiedNames` — the
+ *     four Ring 2 SHARED indexes built over per-file artifacts.
+ *   - `methodDispatch` — MRO + implements materialized view (#914).
+ *   - `imports` — finalized `ImportEdge[]` per module scope (`parsedImports`
+ *     resolved through cross-file link + wildcard expansion).
+ *   - `bindings` — merged bindings per module scope (local + import +
+ *     wildcard + re-export), with the provider's precedence applied.
+ *   - `referenceSites` — union of every file's pre-resolution usage
+ *     facts. Consumed by the resolution phase (future) to emit
+ *     `Reference` records into `ReferenceIndex`.
+ *   - `stats` — coarse-grained counts from the shared finalize algorithm
+ *     (total files/edges, linked vs unresolved, SCC topology).
+ *
+ * `ReferenceIndex` is deliberately NOT here — it is populated in a later
+ * phase (RFC §3.2 Phase 4 / Ring 2 PKG #925) and owned separately.
+ */
+
+import type {
+  BindingRef,
+  DefIndex,
+  FinalizedScc,
+  FinalizeStats,
+  ImportEdge,
+  MethodDispatchIndex,
+  ModuleScopeIndex,
+  QualifiedNameIndex,
+  ReferenceSite,
+  ScopeId,
+  ScopeTree,
+} from 'gitnexus-shared';
+
+export interface ScopeResolutionIndexes {
+  readonly scopeTree: ScopeTree;
+  readonly defs: DefIndex;
+  readonly qualifiedNames: QualifiedNameIndex;
+  readonly moduleScopes: ModuleScopeIndex;
+  readonly methodDispatch: MethodDispatchIndex;
+  /** Finalized `ImportEdge[]` per module scope. */
+  readonly imports: ReadonlyMap<ScopeId, readonly ImportEdge[]>;
+  /** Merged bindings (local + imports + wildcards) per module scope. */
+  readonly bindings: ReadonlyMap<ScopeId, ReadonlyMap<string, readonly BindingRef[]>>;
+  /** Pre-resolution usage facts; consumed by the resolution phase. */
+  readonly referenceSites: readonly ReferenceSite[];
+  /** SCC condensation of the file-level import graph — callers that want
+   *  parallel per-SCC processing in the resolution phase read this. */
+  readonly sccs: readonly FinalizedScc[];
+  readonly stats: FinalizeStats;
+}
diff --git a/gitnexus/src/core/ingestion/model/semantic-model.ts b/gitnexus/src/core/ingestion/model/semantic-model.ts
index deee4ad93..d1c5f1446 100644
--- a/gitnexus/src/core/ingestion/model/semantic-model.ts
+++ b/gitnexus/src/core/ingestion/model/semantic-model.ts
@@ -53,14 +53,11 @@ import type { FieldRegistry, MutableFieldRegistry } from './field-registry.js';
 import { createTypeRegistry } from './type-registry.js';
 import { createMethodRegistry } from './method-registry.js';
 import { createFieldRegistry } from './field-registry.js';
-import type {
-  SymbolTableReader,
-  SymbolTableWriter,
-  SymbolDefinition,
-  AddMetadata,
-} from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
+import type { SymbolTableReader, SymbolTableWriter, AddMetadata } from './symbol-table.js';
 import { createSymbolTable } from './symbol-table.js';
 import { createRegistrationTable } from './registration-table.js';
+import type { ScopeResolutionIndexes } from './scope-resolution-indexes.js';
 
 // ---------------------------------------------------------------------------
 // Public read-only interface
@@ -87,6 +84,19 @@ export interface SemanticModel {
   readonly methods: MethodRegistry;
   readonly fields: FieldRegistry;
   readonly symbols: SymbolTableReader;
+  /**
+   * Materialized scope-resolution indexes from RFC #909 Ring 2 PKG #921.
+   *
+   * `undefined` until the finalize-orchestrator attaches them. While
+   * `undefined`, the legacy DAG is the sole resolution surface; once set,
+   * resolvers whose language has `REGISTRY_PRIMARY_<LANG>=true` consult
+   * these indexes instead.
+   *
+   * The attach is a one-shot write (see `MutableSemanticModel`). Callers
+   * holding a read-only `SemanticModel` handle see either `undefined` or
+   * the final frozen bundle — never a half-populated view.
+   */
+  readonly scopes?: ScopeResolutionIndexes;
 }
 
 // ---------------------------------------------------------------------------
@@ -104,6 +114,17 @@ export interface MutableSemanticModel extends SemanticModel {
   readonly symbols: SymbolTableWriter;
   /** Clear all registries AND the nested SymbolTable. */
   clear(): void;
+  /**
+   * Stamp the finalize-orchestrator's output onto this model.
+   *
+   * **One-shot write.** Throws when called a second time — the indexes are
+   * meant to be materialized once per ingestion run. `Object.freeze` is
+   * applied to the attached bundle so consumers cannot mutate after attach.
+   *
+   * `clear()` resets the attached bundle back to `undefined`, enabling a
+   * fresh re-ingestion to attach a new bundle.
+   */
+  attachScopeIndexes(indexes: ScopeResolutionIndexes): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -156,6 +177,21 @@ export const createSemanticModel = (): MutableSemanticModel => {
     return def;
   };
 
+  // Scope-resolution bundle slot. Starts `undefined`; populated by a
+  // one-shot `attachScopeIndexes(...)` from the finalize-orchestrator.
+  // Held inside the factory closure so the returned `SemanticModel`
+  // surface exposes it as a plain `readonly` property without a setter.
+  let attachedScopes: ScopeResolutionIndexes | undefined;
+
+  const attachScopeIndexes = (indexes: ScopeResolutionIndexes): void => {
+    if (attachedScopes !== undefined) {
+      throw new Error(
+        'SemanticModel: scope indexes already attached. ' + 'Call `clear()` before re-attaching.',
+      );
+    }
+    attachedScopes = Object.freeze(indexes);
+  };
+
   // Cascade clear: single source of truth for "reset the entire model".
   // Wired into both `model.clear()` AND `model.symbols.clear()` so that a
   // caller holding only a SymbolTable reference can't leave the
@@ -166,6 +202,7 @@ export const createSemanticModel = (): MutableSemanticModel => {
     methods.clear();
     fields.clear();
     rawSymbols.clear();
+    attachedScopes = undefined;
   };
 
   // Writer-typed facade: exposes reads + add, but NO `clear` field.
@@ -188,6 +225,10 @@ export const createSemanticModel = (): MutableSemanticModel => {
     methods,
     fields,
     symbols,
+    get scopes() {
+      return attachedScopes;
+    },
     clear: cascadeClear,
+    attachScopeIndexes,
   };
 };
diff --git a/gitnexus/src/core/ingestion/model/symbol-table.ts b/gitnexus/src/core/ingestion/model/symbol-table.ts
index 75abb9731..c22f63acb 100644
--- a/gitnexus/src/core/ingestion/model/symbol-table.ts
+++ b/gitnexus/src/core/ingestion/model/symbol-table.ts
@@ -34,7 +34,7 @@
  * logic up the dependency chain instead.
  */
 
-import type { NodeLabel } from 'gitnexus-shared';
+import type { NodeLabel, SymbolDefinition } from 'gitnexus-shared';
 
 /**
  * Class-like NodeLabels — used for qualifiedName fallback inside
@@ -113,28 +113,10 @@ export const CALL_TARGET_TYPES: ReadonlySet<NodeLabel> = new Set<NodeLabel>([
   'Constructor',
 ]);
 
-export interface SymbolDefinition {
-  nodeId: string;
-  filePath: string;
-  type: NodeLabel;
-  /** Canonical dot-separated qualified type name for class-like symbols
-   *  (e.g. `App.Models.User`). Falls back to the simple symbol name when no
-   *  package/namespace/module scope exists or no explicit qualified metadata is provided. */
-  qualifiedName?: string;
-  parameterCount?: number;
-  /** Number of required (non-optional, non-default) parameters.
-   *  Enables range-based arity filtering: argCount >= requiredParameterCount && argCount <= parameterCount. */
-  requiredParameterCount?: number;
-  /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
-   *  Populated when parameter types are resolvable from AST (any typed language). */
-  parameterTypes?: string[];
-  /** Raw return type text extracted from AST (e.g. 'User', 'Promise<User>') */
-  returnType?: string;
-  /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
-  declaredType?: string;
-  /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
-  ownerId?: string;
-}
+// `SymbolDefinition` moved to `gitnexus-shared` as part of RFC #909 Ring 1
+// (see #910). It is imported at the top of this file from `gitnexus-shared`
+// and re-used unchanged throughout. Consumers should import
+// `SymbolDefinition` directly from `gitnexus-shared`, not via this file.
 
 /**
  * Optional metadata accepted by {@link SymbolTable.add}. Kept as a separate
diff --git a/gitnexus/src/core/ingestion/model/type-registry.ts b/gitnexus/src/core/ingestion/model/type-registry.ts
index 95d52dbc1..3f9fdc5f4 100644
--- a/gitnexus/src/core/ingestion/model/type-registry.ts
+++ b/gitnexus/src/core/ingestion/model/type-registry.ts
@@ -6,7 +6,7 @@
  * Also includes a separate index for Rust Impl blocks.
  */
 
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 
 // ---------------------------------------------------------------------------
 // Public read-only interface
diff --git a/gitnexus/src/core/ingestion/parsing-processor.ts b/gitnexus/src/core/ingestion/parsing-processor.ts
index a13d66818..b7b143039 100644
--- a/gitnexus/src/core/ingestion/parsing-processor.ts
+++ b/gitnexus/src/core/ingestion/parsing-processor.ts
@@ -4,7 +4,7 @@ import Parser from 'tree-sitter';
 import { loadParser, loadLanguage, isLanguageAvailable } from '../tree-sitter/parser-loader.js';
 import { getProvider } from './languages/index.js';
 import { generateId } from '../../lib/utils.js';
-import type { SymbolTableReader, SymbolTableWriter } from './model/symbol-table.js';
+import type { SymbolTableReader, SymbolTableWriter, ExtractedHeritage } from './model/index.js';
 // SymbolTableReader is used for the FieldExtractorContext stub; the
 // parsing functions themselves need Writer because they call .add().
 import { ASTCache } from './ast-cache.js';
@@ -31,6 +31,7 @@ import {
   buildCollisionGroups,
 } from './utils/method-props.js';
 import type { LanguageProvider } from './language-provider.js';
+import type { ParsedFile } from 'gitnexus-shared';
 import { WorkerPool } from './workers/worker-pool.js';
 import type {
   ParseWorkerResult,
@@ -46,7 +47,6 @@ import type {
   FileScopeBindings,
   ExtractedORMQuery,
 } from './workers/parse-worker.js';
-import type { ExtractedHeritage } from './model/heritage-map.js';
 import { getTreeSitterBufferSize, TREE_SITTER_MAX_BUFFER } from './constants.js';
 
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
@@ -63,6 +63,14 @@ export interface WorkerExtractedData {
   ormQueries: ExtractedORMQuery[];
   constructorBindings: FileConstructorBindings[];
   fileScopeBindings: FileScopeBindings[];
+  /**
+   * Per-file `ParsedFile` artifacts from the new scope-based resolution
+   * pipeline (RFC #909 Ring 2). Empty until a provider implements
+   * `emitScopeCaptures` — additive to the legacy DAG path. Aggregated
+   * from every worker chunk; consumed downstream by #921's
+   * finalize-orchestrator.
+   */
+  parsedFiles: ParsedFile[];
 }
 
 // ============================================================================
@@ -97,6 +105,7 @@ const processParsingWithWorkers = async (
       ormQueries: [],
       constructorBindings: [],
       fileScopeBindings: [],
+      parsedFiles: [],
     };
 
   const total = files.length;
@@ -121,6 +130,7 @@ const processParsingWithWorkers = async (
   const allORMQueries: ExtractedORMQuery[] = [];
   const allConstructorBindings: FileConstructorBindings[] = [];
   const fileScopeBindingsByFile: FileScopeBindings[] = [];
+  const allParsedFiles: ParsedFile[] = [];
   for (const result of chunkResults) {
     for (const node of result.nodes) {
       graph.addNode({
@@ -158,6 +168,11 @@ const processParsingWithWorkers = async (
     for (const item of result.constructorBindings) allConstructorBindings.push(item);
     if (result.fileScopeBindings)
       for (const item of result.fileScopeBindings) fileScopeBindingsByFile.push(item);
+    // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
+    // workers that don't emit the field yet (older worker builds or
+    // partial rollouts), since the additive contract means undefined =
+    // "this worker produced no ParsedFiles for this chunk".
+    if (result.parsedFiles) for (const item of result.parsedFiles) allParsedFiles.push(item);
   }
 
   // Merge and log skipped languages from workers
@@ -188,6 +203,7 @@ const processParsingWithWorkers = async (
     ormQueries: allORMQueries,
     constructorBindings: allConstructorBindings,
     fileScopeBindings: fileScopeBindingsByFile,
+    parsedFiles: allParsedFiles,
   };
 };
 
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
index 52c7a0d47..f8e0d3b53 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts
@@ -108,6 +108,7 @@ export async function runChunkedParseAndResolve(
   allORMQueries: ExtractedORMQuery[];
   bindingAccumulator: BindingAccumulator;
   resolutionContext: ReturnType<typeof createResolutionContext>;
+  usedWorkerPool: boolean;
 }> {
   const ctx = createResolutionContext();
   const symbolTable = ctx.model.symbols;
@@ -173,9 +174,11 @@ export async function runChunkedParseAndResolve(
     stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
   });
 
-  // Don't spawn workers for tiny repos — overhead exceeds benefit
-  const MIN_FILES_FOR_WORKERS = 15;
-  const MIN_BYTES_FOR_WORKERS = 512 * 1024;
+  // Don't spawn workers for tiny repos — overhead exceeds benefit.
+  // Test suites may lower the thresholds via `options.workerThresholdsForTest`
+  // to exercise the worker-pool path with small fixtures; see PipelineOptions.
+  const MIN_FILES_FOR_WORKERS = options?.workerThresholdsForTest?.minFiles ?? 15;
+  const MIN_BYTES_FOR_WORKERS = options?.workerThresholdsForTest?.minBytes ?? 512 * 1024;
   const totalBytes = parseableScanned.reduce((s, f) => s + f.size, 0);
 
   // Create worker pool once, reuse across chunks
@@ -588,5 +591,9 @@ export async function runChunkedParseAndResolve(
     allORMQueries,
     bindingAccumulator,
     resolutionContext: ctx,
+    // Whether a worker pool was actually live for this run. False means the
+    // sequential fallback handled every chunk (either due to `skipWorkers`,
+    // the file-count/byte thresholds, or a pool-creation failure).
+    usedWorkerPool: workerPool !== undefined,
   };
 }
diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse.ts
index 19ccec409..6415cb6e5 100644
--- a/gitnexus/src/core/ingestion/pipeline-phases/parse.ts
+++ b/gitnexus/src/core/ingestion/pipeline-phases/parse.ts
@@ -56,6 +56,13 @@ export interface ParseOutput {
   readonly allPathSet: ReadonlySet<string>;
   /** Pass-through: total file count for progress reporting. */
   totalFiles: number;
+  /**
+   * True if the parse phase spawned a live worker pool for this run.
+   * False means every chunk ran through the sequential fallback (skipWorkers,
+   * thresholds not met, or pool-creation failure). Primarily a test affordance:
+   * see `PipelineOptions.workerThresholdsForTest`.
+   */
+  readonly usedWorkerPool: boolean;
 }
 
 export const parsePhase: PipelinePhase<ParseOutput> = {
diff --git a/gitnexus/src/core/ingestion/pipeline.ts b/gitnexus/src/core/ingestion/pipeline.ts
index c0cfa2992..e1f226289 100644
--- a/gitnexus/src/core/ingestion/pipeline.ts
+++ b/gitnexus/src/core/ingestion/pipeline.ts
@@ -43,6 +43,17 @@ export interface PipelineOptions {
   skipGraphPhases?: boolean;
   /** Force sequential parsing (no worker pool). Useful for testing the sequential path. */
   skipWorkers?: boolean;
+  /**
+   * @internal Test-only override for worker-pool gating thresholds.
+   * When unset, production defaults apply (15 files OR 512 KB total bytes).
+   * Setting either field lowers the corresponding threshold so small test
+   * fixtures can still exercise the worker-pool path. Do not use from
+   * production call sites.
+   */
+  workerThresholdsForTest?: {
+    minFiles?: number;
+    minBytes?: number;
+  };
 }
 
 // ── Phase registry ─────────────────────────────────────────────────────────
@@ -99,7 +110,10 @@ export const runPipelineFromRepo = async (
   });
 
   // Extract final results for the PipelineResult contract
-  const { totalFiles } = getPhaseOutput<{ totalFiles: number }>(results, 'parse');
+  const { totalFiles, usedWorkerPool } = getPhaseOutput<{
+    totalFiles: number;
+    usedWorkerPool: boolean;
+  }>(results, 'parse');
 
   let communityResult: CommunitiesOutput['communityResult'] | undefined;
   let processResult: ProcessesOutput['processResult'] | undefined;
@@ -123,5 +137,12 @@ export const runPipelineFromRepo = async (
     },
   });
 
-  return { graph, repoPath, totalFileCount: totalFiles, communityResult, processResult };
+  return {
+    graph,
+    repoPath,
+    totalFileCount: totalFiles,
+    communityResult,
+    processResult,
+    usedWorkerPool,
+  };
 };
diff --git a/gitnexus/src/core/ingestion/registry-primary-flag.ts b/gitnexus/src/core/ingestion/registry-primary-flag.ts
new file mode 100644
index 000000000..8b59912bd
--- /dev/null
+++ b/gitnexus/src/core/ingestion/registry-primary-flag.ts
@@ -0,0 +1,83 @@
+/**
+ * `REGISTRY_PRIMARY_<LANG>` per-language feature flags for the scope-based
+ * resolution rollout (RFC §6.1 Ring 3; Ring 2 PKG #924).
+ *
+ * This module is the single source of truth for whether a given language
+ * has been flipped to registry-primary call resolution. When a language's
+ * flag is true, its files route through `Registry.lookup` (RFC §4) instead
+ * of the legacy call-resolution DAG; when false (the default), the legacy
+ * DAG runs unchanged.
+ *
+ * ## Contract
+ *
+ *   - Env-var name per language: `REGISTRY_PRIMARY_<UPPER(enum-value)>`.
+ *     Example: `SupportedLanguages.Python` → `REGISTRY_PRIMARY_PYTHON`;
+ *     `SupportedLanguages.CPlusPlus` (value `'cpp'`) → `REGISTRY_PRIMARY_CPP`.
+ *   - Truthy values: `'true'`, `'1'`, `'yes'` (case-insensitive,
+ *     whitespace-trimmed). Anything else — including `undefined`, empty
+ *     string, or unknown tokens — is `false`.
+ *   - No per-process caching. `process.env` is read on every call. The
+ *     flag is consulted once per file at call-resolution time, so the
+ *     overhead is negligible; skipping caching keeps test isolation
+ *     trivial (no `resetFlagCache()` coordination needed).
+ *
+ * ## Integration site
+ *
+ * `call-processor.ts` integration lands in **#921** (`finalize-orchestrator`)
+ * where the `SemanticModel` becomes accessible and `Registry.lookup` can
+ * actually be called with a populated context. This module ships the flag
+ * primitive in isolation so #921 has a clean, tested utility to consult.
+ *
+ * ## Shadow mode is orthogonal
+ *
+ * Shadow mode (`GITNEXUS_SHADOW_MODE=1`, introduced in #923) runs BOTH
+ * legacy and registry paths regardless of the per-language flag, so the
+ * parity dashboard has signal even for un-flipped languages. That logic
+ * lives in `shadow-harness.ts` (#923), not here.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+
+/**
+ * Return the env-var name that controls a given language's registry-
+ * primary flag. Exported for test assertions and for the PR-labeling
+ * CI job that cross-references per-language flag changes.
+ */
+export function envVarNameFor(lang: SupportedLanguages): string {
+  return `REGISTRY_PRIMARY_${lang.toUpperCase()}`;
+}
+
+/**
+ * Whether `lang` has been flipped to registry-primary call resolution.
+ *
+ * Returns `false` by default — a language must explicitly set its env
+ * var to a truthy value to opt in. The flag is the sole control surface:
+ * flipping it requires no code change, and reverting it requires no code
+ * change.
+ */
+export function isRegistryPrimary(lang: SupportedLanguages): boolean {
+  return parseFlag(process.env[envVarNameFor(lang)]);
+}
+
+/**
+ * All languages whose registry-primary flag is currently on. Useful for
+ * startup-time logging + the shadow-harness dashboard, which wants to
+ * distinguish "primary: legacy" from "primary: registry" rows.
+ */
+export function primaryLanguages(): ReadonlySet<SupportedLanguages> {
+  const out = new Set<SupportedLanguages>();
+  for (const lang of Object.values(SupportedLanguages)) {
+    if (isRegistryPrimary(lang)) out.add(lang);
+  }
+  return out;
+}
+
+// ─── Internal ───────────────────────────────────────────────────────────────
+
+/** Accepted truthy strings (case-insensitive, trimmed). */
+const TRUTHY_VALUES: ReadonlySet<string> = new Set(['true', '1', 'yes']);
+
+function parseFlag(raw: string | undefined): boolean {
+  if (raw === undefined) return false;
+  return TRUTHY_VALUES.has(raw.trim().toLowerCase());
+}
diff --git a/gitnexus/src/core/ingestion/scope-extractor-bridge.ts b/gitnexus/src/core/ingestion/scope-extractor-bridge.ts
new file mode 100644
index 000000000..dfa3b9b4f
--- /dev/null
+++ b/gitnexus/src/core/ingestion/scope-extractor-bridge.ts
@@ -0,0 +1,54 @@
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   3. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+
+import type { ParsedFile } from 'gitnexus-shared';
+import { extract as extractScope } from './scope-extractor.js';
+import type { LanguageProvider } from './language-provider.js';
+
+/** Callback used to report scope-extraction warnings to the host (worker or direct). */
+export type ScopeBridgeWarn = (message: string) => void;
+
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+export function extractParsedFile(
+  provider: LanguageProvider,
+  sourceText: string,
+  filePath: string,
+  onWarn?: ScopeBridgeWarn,
+): ParsedFile | undefined {
+  if (provider.emitScopeCaptures === undefined) return undefined;
+  try {
+    const captures = provider.emitScopeCaptures(sourceText, filePath);
+    return extractScope(captures, filePath, provider);
+  } catch (err) {
+    const message = `scope extraction failed for ${filePath}: ${
+      err instanceof Error ? err.message : String(err)
+    }`;
+    if (onWarn !== undefined) onWarn(message);
+    else console.warn(message);
+    return undefined;
+  }
+}
diff --git a/gitnexus/src/core/ingestion/scope-extractor.ts b/gitnexus/src/core/ingestion/scope-extractor.ts
new file mode 100644
index 000000000..4ab0a6257
--- /dev/null
+++ b/gitnexus/src/core/ingestion/scope-extractor.ts
@@ -0,0 +1,823 @@
+/**
+ * `ScopeExtractor` — the central, source-agnostic driver that turns a
+ * language provider's `CaptureMatch[]` into a `ParsedFile`
+ * (RFC §5.3 + §3.2 Phase 1; Ring 2 PKG #919).
+ *
+ * Exactly one entry point: `extract(matches, filePath, provider) → ParsedFile`.
+ * Runs a five-pass pipeline over the matches. Each pass is internal; the
+ * public contract is the output `ParsedFile`.
+ *
+ * ## Design principles
+ *
+ *   - **Source-agnostic.** Consumes `CaptureMatch[]` from providers;
+ *     doesn't know whether they came from tree-sitter queries or COBOL's
+ *     regex tagger. No `Tree` / `SyntaxNode` types leak into this file.
+ *   - **One AST walk per language.** Providers do the AST walk inside
+ *     their `emitScopeCaptures` hook; this driver does zero further
+ *     traversal — it consumes captures only.
+ *   - **Pure-ish.** The extractor itself is pure (same matches →
+ *     same ParsedFile) when providers are pure. No side effects, no I/O.
+ *   - **Centralized invariant enforcement.** Structural invariants on the
+ *     scope tree (non-module has parent; parent contains child; siblings
+ *     don't overlap) are enforced by `buildScopeTree` from Ring 2 SHARED
+ *     (#912). Malformed inputs throw `ScopeTreeInvariantError`.
+ *
+ * ## The five passes
+ *
+ *   1. **Build scope tree.** Walk `@scope.*` matches. For each, consult
+ *      `provider.shouldCreateScope` (default true) and
+ *      `provider.resolveScopeKind` (default: suffix of the capture name).
+ *      Derive parent by lexical-range containment. Hand the resulting
+ *      `Scope[]` to `buildScopeTree` for validation.
+ *   2. **Attach declarations + local bindings.** Walk `@declaration.*`
+ *      matches. For each, build a `SymbolDefinition` and attach it to
+ *      `provider.bindingScopeFor` (default: innermost containing scope)
+ *      as `ownedDefs` + a local `BindingRef { origin: 'local' }`.
+ *   3. **Collect raw imports.** Walk `@import.*` matches. Call
+ *      `provider.interpretImport` per match; attach the returned
+ *      `ParsedImport` to the ParsedFile (not to any `Scope` — finalize
+ *      reconstructs the owning scope via `provider.importOwningScope`
+ *      during Phase 2).
+ *   4. **Collect type bindings.** Walk `@type-binding.*` matches. Call
+ *      `provider.interpretTypeBinding` per match. Attach the resulting
+ *      `TypeRef` to the innermost containing scope's `typeBindings`
+ *      (or override via `provider.bindingScopeFor` if set).
+ *   5. **Collect reference sites.** Walk `@reference.*` matches. Emit
+ *      one `ReferenceSite` per match. Classify call form via
+ *      `provider.classifyCallForm` (default: the capture's sub-tag if
+ *      present; else `'free'`).
+ *
+ * ## What gets attached where
+ *
+ *   - `Scope.bindings`     — **local bindings only** at this stage (Pass 2).
+ *                            Finalize (#915) merges imports/wildcards on top.
+ *   - `Scope.ownedDefs`    — declarations structurally owned by this scope.
+ *   - `Scope.typeBindings` — local type facts (parameter annotations, `self`).
+ *   - `Scope.imports`      — empty here. Populated by the finalize algorithm
+ *                            when it resolves `ParsedImport.targetRaw`.
+ *   - `ParsedFile.parsedImports` — every raw import in this file.
+ *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
+ *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
+ */
+
+import type {
+  BindingRef,
+  CaptureMatch,
+  ImportEdge,
+  ParsedFile,
+  ParsedImport,
+  ReferenceSite,
+  ReferenceKind,
+  Range,
+  Scope,
+  ScopeId,
+  ScopeKind,
+  SymbolDefinition,
+  TypeRef,
+} from 'gitnexus-shared';
+import { buildPositionIndex, buildScopeTree, makeScopeId } from 'gitnexus-shared';
+import type { LanguageProvider } from './language-provider.js';
+
+// ─── Narrow hook surface the extractor actually uses ───────────────────────
+
+/**
+ * The subset of `LanguageProvider` hooks that `extract()` reads. Declared
+ * as its own type so:
+ *
+ *   - Tests can implement just these six hooks without faking the whole
+ *     `LanguageProvider` interface (which is ~40 fields including the
+ *     legacy-DAG surface).
+ *   - The extractor's dependency contract stays explicit — adding a new
+ *     hook read requires updating this type.
+ *
+ * Real callers pass a full `LanguageProvider` — structural typing makes it
+ * a `ScopeExtractorHooks` for free.
+ */
+export type ScopeExtractorHooks = Pick<
+  LanguageProvider,
+  | 'shouldCreateScope'
+  | 'resolveScopeKind'
+  | 'bindingScopeFor'
+  | 'interpretImport'
+  | 'interpretTypeBinding'
+  | 'classifyCallForm'
+>;
+
+// ─── Public entry point ─────────────────────────────────────────────────────
+
+/**
+ * Drive the five extraction passes and return a `ParsedFile`.
+ *
+ * Throws `ScopeTreeInvariantError` (from #912) when the provider emits
+ * captures that violate structural scope invariants. The error surfaces
+ * upward rather than being silently corrected — a malformed capture set
+ * is a bug in the provider's `emitScopeCaptures`, not a data condition
+ * to tolerate.
+ */
+export function extract(
+  matches: readonly CaptureMatch[],
+  filePath: string,
+  provider: ScopeExtractorHooks,
+): ParsedFile {
+  // Partition matches by topic up front — one linear pass over the input.
+  const partitioned = partitionByTopic(matches);
+
+  // ── Pass 1: build the scope tree ─────────────────────────────────────
+  const scopeDrafts = pass1BuildScopes(partitioned.scope, filePath, provider);
+  const scopes = scopeDrafts.map(draftToScope);
+  // buildScopeTree validates invariants (throws on violation) and exposes
+  // the lookup contract consumed by Passes 2-5.
+  //
+  // **Snapshot semantics.** Both `scopeTree` and `positionIndex` are built
+  // from the post-Pass-1 `scopes` — parent/range/kind are accurate, but
+  // `bindings`, `ownedDefs`, and `typeBindings` are all empty here. Later
+  // passes write into the *drafts*, not into these snapshots; any hook
+  // that reads `scope.bindings` etc. via the `scopeTree` argument sees a
+  // structural view only. This is by design — hooks use scopeTree for
+  // "what's the parent chain?" queries, not for content queries.
+  const scopeTree = buildScopeTree(scopes);
+  const positionIndex = buildPositionIndex(scopes);
+
+  const moduleScope = scopeDrafts.find((s) => s.kind === 'Module');
+  if (moduleScope === undefined) {
+    throw new Error(
+      `ScopeExtractor: no Module scope found for '${filePath}'. ` +
+        `Provider must emit at least one @scope.module capture per file.`,
+    );
+  }
+
+  // ── Pass 2: attach declarations + local bindings ────────────────────
+  const localDefs: SymbolDefinition[] = [];
+  pass2AttachDeclarations(
+    partitioned.declaration,
+    scopeDrafts,
+    positionIndex,
+    localDefs,
+    filePath,
+    provider,
+    scopeTree,
+  );
+
+  // ── Pass 3: collect raw imports ─────────────────────────────────────
+  const parsedImports: ParsedImport[] = [];
+  pass3CollectImports(partitioned.import_, parsedImports, provider);
+
+  // ── Pass 4: collect type bindings ───────────────────────────────────
+  pass4CollectTypeBindings(
+    partitioned.typeBinding,
+    scopeDrafts,
+    positionIndex,
+    filePath,
+    provider,
+    scopeTree,
+  );
+
+  // ── Pass 5: collect reference sites ─────────────────────────────────
+  const referenceSites: ReferenceSite[] = [];
+  pass5CollectReferences(
+    partitioned.reference,
+    positionIndex,
+    filePath,
+    referenceSites,
+    provider,
+    scopeTree,
+  );
+
+  // Freeze Scope drafts into final shape and return.
+  const frozenScopes = scopeDrafts.map(draftToScope);
+  return Object.freeze({
+    filePath,
+    moduleScope: moduleScope.id,
+    scopes: Object.freeze(frozenScopes),
+    parsedImports: Object.freeze(parsedImports.slice()),
+    localDefs: Object.freeze(localDefs.slice()),
+    referenceSites: Object.freeze(referenceSites.slice()),
+  });
+}
+
+// ─── Internal: partitioning by topic ───────────────────────────────────────
+
+interface Partitioned {
+  readonly scope: readonly CaptureMatch[];
+  readonly declaration: readonly CaptureMatch[];
+  readonly import_: readonly CaptureMatch[];
+  readonly typeBinding: readonly CaptureMatch[];
+  readonly reference: readonly CaptureMatch[];
+}
+
+/**
+ * Bucket each match by the topic of its anchor capture. The anchor is the
+ * capture whose name is prefixed with the match's topic (`@scope.*`,
+ * `@declaration.*`, `@import.*`, `@type-binding.*`, `@reference.*`).
+ *
+ * A match may contain additional captures (e.g., `@import.source`,
+ * `@declaration.class.name`) that are used by the provider hooks to
+ * decode details. Those live inside the `CaptureMatch` and are surfaced
+ * to hooks verbatim — the extractor itself only routes by anchor.
+ */
+function partitionByTopic(matches: readonly CaptureMatch[]): Partitioned {
+  const scope: CaptureMatch[] = [];
+  const declaration: CaptureMatch[] = [];
+  const import_: CaptureMatch[] = [];
+  const typeBinding: CaptureMatch[] = [];
+  const reference: CaptureMatch[] = [];
+
+  for (const match of matches) {
+    const topic = topicOf(match);
+    switch (topic) {
+      case 'scope':
+        scope.push(match);
+        break;
+      case 'declaration':
+        declaration.push(match);
+        break;
+      case 'import':
+        import_.push(match);
+        break;
+      case 'type-binding':
+        typeBinding.push(match);
+        break;
+      case 'reference':
+        reference.push(match);
+        break;
+      case 'unknown':
+        // Unrecognized anchor — silently skip. Providers may emit extra
+        // captures (e.g., `@comment`) that the extractor has no topic for.
+        break;
+    }
+  }
+
+  return { scope, declaration, import_, typeBinding, reference };
+}
+
+type Topic = 'scope' | 'declaration' | 'import' | 'type-binding' | 'reference' | 'unknown';
+
+function topicOf(match: CaptureMatch): Topic {
+  // The anchor is the capture whose name uses one of the known topic
+  // prefixes. For multi-capture matches, ALL captures share the topic;
+  // we pick the first matching key for efficiency.
+  for (const name of Object.keys(match)) {
+    if (name.startsWith('@scope.')) return 'scope';
+    if (name.startsWith('@declaration.')) return 'declaration';
+    if (name.startsWith('@import.')) return 'import';
+    if (name.startsWith('@type-binding.')) return 'type-binding';
+    if (name.startsWith('@reference.')) return 'reference';
+  }
+  return 'unknown';
+}
+
+// ─── Internal: Scope draft model ───────────────────────────────────────────
+
+/**
+ * Mutable Scope record used during extraction. The final `Scope` (readonly,
+ * returned in `ParsedFile.scopes`) is produced by `draftToScope` at the end
+ * of each pass's writes.
+ */
+interface ScopeDraft {
+  readonly id: ScopeId;
+  readonly parent: ScopeId | null;
+  readonly kind: ScopeKind;
+  readonly range: Range;
+  readonly filePath: string;
+  readonly bindings: Map<string, BindingRef[]>;
+  readonly ownedDefs: SymbolDefinition[];
+  readonly imports: ImportEdge[];
+  readonly typeBindings: Map<string, TypeRef>;
+}
+
+function draftToScope(draft: ScopeDraft): Scope {
+  const frozenBindings = new Map<string, readonly BindingRef[]>();
+  for (const [name, refs] of draft.bindings) {
+    frozenBindings.set(name, Object.freeze(refs.slice()));
+  }
+  return {
+    id: draft.id,
+    parent: draft.parent,
+    kind: draft.kind,
+    range: draft.range,
+    filePath: draft.filePath,
+    bindings: frozenBindings,
+    ownedDefs: Object.freeze(draft.ownedDefs.slice()),
+    imports: Object.freeze(draft.imports.slice()),
+    typeBindings: new Map(draft.typeBindings),
+  };
+}
+
+// ─── Pass 1: build scope tree ──────────────────────────────────────────────
+
+/**
+ * Convert `@scope.*` matches into `ScopeDraft[]`. Parent relationships
+ * are derived from range containment (outermost scope containing `range`
+ * becomes the parent). Scopes with `shouldCreateScope === false` are
+ * silently omitted — their children reparent to the next enclosing
+ * real scope.
+ */
+function pass1BuildScopes(
+  matches: readonly CaptureMatch[],
+  filePath: string,
+  provider: ScopeExtractorHooks,
+): ScopeDraft[] {
+  interface Candidate {
+    readonly match: CaptureMatch;
+    readonly range: Range;
+    readonly kind: ScopeKind;
+    readonly create: boolean;
+    readonly id: ScopeId;
+  }
+
+  const candidates: Candidate[] = [];
+  for (const match of matches) {
+    const anchor = anchorCaptureFor(match, '@scope.');
+    if (anchor === undefined) continue;
+    const kind = resolveKindForScopeMatch(match, anchor, provider);
+    if (kind === null) continue;
+    const create = provider.shouldCreateScope?.(match) ?? true;
+    const id = makeScopeId({ filePath, range: anchor.range, kind });
+    candidates.push({ match, range: anchor.range, kind, create, id });
+  }
+
+  // Sort by (startLine, startCol) ASC, (endLine, endCol) DESC so outer
+  // scopes appear before their children for parent-resolution.
+  candidates.sort((a, b) => {
+    if (a.range.startLine !== b.range.startLine) return a.range.startLine - b.range.startLine;
+    if (a.range.startCol !== b.range.startCol) return a.range.startCol - b.range.startCol;
+    if (a.range.endLine !== b.range.endLine) return b.range.endLine - a.range.endLine;
+    return b.range.endCol - a.range.endCol;
+  });
+
+  const drafts: ScopeDraft[] = [];
+  const stack: Candidate[] = []; // enclosing real scopes, outermost at [0]
+
+  for (const cand of candidates) {
+    // Pop the stack until the top strictly contains this candidate.
+    while (stack.length > 0 && !rangeStrictlyContains(stack[stack.length - 1]!.range, cand.range)) {
+      stack.pop();
+    }
+
+    if (cand.create) {
+      const parent = stack.length > 0 ? stack[stack.length - 1]!.id : null;
+      drafts.push(makeDraft(cand.id, parent, cand.kind, cand.range, filePath));
+      stack.push(cand);
+    }
+    // If `cand.create === false`, we don't push it onto the stack — child
+    // scopes will reparent to whatever's below it.
+  }
+
+  return drafts;
+}
+
+function resolveKindForScopeMatch(
+  match: CaptureMatch,
+  anchor: { readonly name: string },
+  provider: ScopeExtractorHooks,
+): ScopeKind | null {
+  // Provider override takes precedence.
+  const override = provider.resolveScopeKind?.(match);
+  if (override !== undefined && override !== null) return override;
+
+  // Default: derive from capture name suffix (`@scope.function` → 'Function').
+  const suffix = anchor.name.slice('@scope.'.length);
+  switch (suffix.toLowerCase()) {
+    case 'module':
+      return 'Module';
+    case 'namespace':
+      return 'Namespace';
+    case 'class':
+      return 'Class';
+    case 'function':
+      return 'Function';
+    case 'block':
+      return 'Block';
+    case 'expression':
+      return 'Expression';
+    default:
+      return null;
+  }
+}
+
+function makeDraft(
+  id: ScopeId,
+  parent: ScopeId | null,
+  kind: ScopeKind,
+  range: Range,
+  filePath: string,
+): ScopeDraft {
+  return {
+    id,
+    parent,
+    kind,
+    range,
+    filePath,
+    bindings: new Map(),
+    ownedDefs: [],
+    imports: [],
+    typeBindings: new Map(),
+  };
+}
+
+// ─── Pass 2: attach declarations + local bindings ──────────────────────────
+
+function pass2AttachDeclarations(
+  matches: readonly CaptureMatch[],
+  drafts: readonly ScopeDraft[],
+  positionIndex: ReturnType<typeof buildPositionIndex>,
+  localDefs: SymbolDefinition[],
+  filePath: string,
+  provider: ScopeExtractorHooks,
+  scopeTree: ReturnType<typeof buildScopeTree>,
+): void {
+  const draftById = new Map<ScopeId, ScopeDraft>();
+  for (const d of drafts) draftById.set(d.id, d);
+
+  for (const match of matches) {
+    const anchor = anchorCaptureFor(match, '@declaration.');
+    if (anchor === undefined) continue;
+
+    const def = buildDefFromDeclarationMatch(match, anchor, filePath);
+    if (def === undefined) continue;
+
+    // Find the innermost scope that contains the declaration's anchor range.
+    const innermostId = positionIndex.atPosition(
+      filePath,
+      anchor.range.startLine,
+      anchor.range.startCol,
+    );
+    if (innermostId === undefined) continue;
+    const innermost = draftById.get(innermostId);
+    if (innermost === undefined) continue;
+
+    // Ownership: attach the def to the innermost scope's `ownedDefs` — that
+    // is the structural owner. `def.ownerId` is NOT populated here — the
+    // extractor has no clean path to the parent's own DefId mid-extraction
+    // (the parent declaration may not yet have been processed, or may live
+    // in a different scope entirely). Providers that need `ownerId` should
+    // set it directly from the declaration hook (e.g., derive from the
+    // `@declaration.owner` capture or the parent scope id); otherwise
+    // `finalize` populates method/field `ownerId` via `MethodDispatchIndex`
+    // (#914) in a follow-up pass that sees every def already in place.
+    innermost.ownedDefs.push(def);
+    localDefs.push(def);
+
+    // Binding visibility: default to innermost; allow hoisting via
+    // `provider.bindingScopeFor`. `draftToScope(innermost)` here is a
+    // **structural** snapshot — parent/range/kind only. Hooks MUST NOT
+    // rely on `scope.bindings`, `ownedDefs`, or `typeBindings` being
+    // populated during Pass 2: those fields are written across passes,
+    // so reading them mid-extraction yields a partial view. The
+    // `scopeTree` argument is similarly snapshot-before-mutation.
+    const bindingScopeId =
+      provider.bindingScopeFor?.(match, draftToScope(innermost), scopeTree) ?? innermost.id;
+    const bindingHost = draftById.get(bindingScopeId) ?? innermost;
+
+    const nameKey = deriveDeclarationName(match, def);
+    if (nameKey === undefined) continue;
+
+    const existing = bindingHost.bindings.get(nameKey) ?? [];
+    existing.push({ def, origin: 'local' });
+    bindingHost.bindings.set(nameKey, existing);
+  }
+}
+
+function buildDefFromDeclarationMatch(
+  match: CaptureMatch,
+  anchor: { readonly name: string; readonly range: Range; readonly text: string },
+  filePath: string,
+): SymbolDefinition | undefined {
+  // Anchor name pattern: `@declaration.<kind>` where <kind> maps to NodeLabel.
+  const kindStr = anchor.name.slice('@declaration.'.length);
+  const type = normalizeNodeLabel(kindStr);
+  if (type === undefined) return undefined;
+
+  const nameCap =
+    match['@declaration.name'] ?? match[`@declaration.${kindStr}.name`] ?? match[anchor.name];
+  if (nameCap === undefined) return undefined;
+
+  const qualifiedCap = match['@declaration.qualified_name'];
+  const qualifiedName = qualifiedCap?.text;
+
+  return {
+    nodeId: makeDefId(filePath, anchor.range, type, nameCap.text),
+    filePath,
+    type,
+    ...(qualifiedName !== undefined ? { qualifiedName } : { qualifiedName: nameCap.text }),
+  };
+}
+
+function deriveDeclarationName(match: CaptureMatch, def: SymbolDefinition): string | undefined {
+  const nameCap =
+    match['@declaration.name'] ??
+    match[
+      Object.keys(match).find((k) => k.startsWith('@declaration.') && k.endsWith('.name')) ?? ''
+    ];
+  if (nameCap !== undefined) return nameCap.text;
+  // Fall back to qualifiedName tail.
+  const q = def.qualifiedName;
+  if (q !== undefined && q.length > 0) {
+    const dot = q.lastIndexOf('.');
+    return dot === -1 ? q : q.slice(dot + 1);
+  }
+  return undefined;
+}
+
+/**
+ * Map a lower-case declaration kind (from `@declaration.<kind>`) to a
+ * graph `NodeLabel`. Silently returns `undefined` for kinds we don't
+ * recognize — providers can emit richer captures without breaking the
+ * driver.
+ */
+function normalizeNodeLabel(kindStr: string): SymbolDefinition['type'] | undefined {
+  switch (kindStr.toLowerCase()) {
+    case 'class':
+      return 'Class';
+    case 'interface':
+      return 'Interface';
+    case 'enum':
+      return 'Enum';
+    case 'struct':
+      return 'Struct';
+    case 'union':
+      return 'Union';
+    case 'trait':
+      return 'Trait';
+    case 'method':
+      return 'Method';
+    case 'function':
+      return 'Function';
+    case 'constructor':
+      return 'Constructor';
+    case 'field':
+    case 'property':
+      return 'Property';
+    case 'variable':
+    case 'const':
+      return 'Variable';
+    case 'typealias':
+    case 'type_alias':
+      return 'TypeAlias';
+    case 'typedef':
+      return 'Typedef';
+    case 'record':
+      return 'Record';
+    case 'delegate':
+      return 'Delegate';
+    case 'annotation':
+      return 'Annotation';
+    case 'namespace':
+      return 'Namespace';
+    default:
+      return undefined;
+  }
+}
+
+function makeDefId(
+  filePath: string,
+  range: Range,
+  type: SymbolDefinition['type'],
+  name: string,
+): string {
+  return `def:${filePath}#${range.startLine}:${range.startCol}:${type}:${name}`;
+}
+
+// ─── Pass 3: collect raw imports ───────────────────────────────────────────
+
+function pass3CollectImports(
+  matches: readonly CaptureMatch[],
+  parsedImports: ParsedImport[],
+  provider: ScopeExtractorHooks,
+): void {
+  if (provider.interpretImport === undefined) return;
+  for (const match of matches) {
+    const anchor = anchorCaptureFor(match, '@import.');
+    if (anchor === undefined) continue;
+    const parsed = provider.interpretImport(match);
+    if (parsed === null) continue;
+    parsedImports.push(parsed);
+  }
+}
+
+// ─── Pass 4: collect type bindings ─────────────────────────────────────────
+
+function pass4CollectTypeBindings(
+  matches: readonly CaptureMatch[],
+  drafts: readonly ScopeDraft[],
+  positionIndex: ReturnType<typeof buildPositionIndex>,
+  filePath: string,
+  provider: ScopeExtractorHooks,
+  scopeTree: ReturnType<typeof buildScopeTree>,
+): void {
+  const draftById = new Map<ScopeId, ScopeDraft>();
+  for (const d of drafts) draftById.set(d.id, d);
+
+  for (const match of matches) {
+    const anchor = anchorCaptureFor(match, '@type-binding.');
+    if (anchor === undefined) continue;
+
+    const parsed = provider.interpretTypeBinding?.(match);
+    if (parsed === null || parsed === undefined) continue;
+
+    const innermostId = positionIndex.atPosition(
+      filePath,
+      anchor.range.startLine,
+      anchor.range.startCol,
+    );
+    if (innermostId === undefined) continue;
+    const innermost = draftById.get(innermostId);
+    if (innermost === undefined) continue;
+
+    // `bindingScopeFor` may hoist the type binding to an outer scope.
+    const hostId =
+      provider.bindingScopeFor?.(match, draftToScope(innermost), scopeTree) ?? innermost.id;
+    const host = draftById.get(hostId) ?? innermost;
+
+    const typeRef: TypeRef = {
+      rawName: parsed.rawTypeName,
+      declaredAtScope: host.id,
+      source: parsed.source,
+    };
+    host.typeBindings.set(parsed.boundName, typeRef);
+  }
+}
+
+// ─── Pass 5: collect reference sites ───────────────────────────────────────
+
+function pass5CollectReferences(
+  matches: readonly CaptureMatch[],
+  positionIndex: ReturnType<typeof buildPositionIndex>,
+  filePath: string,
+  referenceSites: ReferenceSite[],
+  provider: ScopeExtractorHooks,
+  scopeTree: ReturnType<typeof buildScopeTree>,
+): void {
+  for (const match of matches) {
+    const anchor = anchorCaptureFor(match, '@reference.');
+    if (anchor === undefined) continue;
+
+    const kind = referenceKindFromAnchor(anchor.name);
+    if (kind === undefined) continue;
+
+    const nameCap = match['@reference.name'] ?? anchor;
+    const inScopeId = positionIndex.atPosition(
+      filePath,
+      anchor.range.startLine,
+      anchor.range.startCol,
+    );
+    if (inScopeId === undefined) continue;
+
+    const callForm =
+      kind === 'call'
+        ? classifyCallFormForMatch(match, anchor.name, provider, scopeTree, inScopeId)
+        : undefined;
+    const explicitReceiver = extractExplicitReceiver(match);
+    const arity = extractArity(match);
+
+    const site: ReferenceSite = {
+      name: nameCap.text,
+      atRange: anchor.range,
+      inScope: inScopeId,
+      kind,
+      ...(callForm !== undefined ? { callForm } : {}),
+      ...(explicitReceiver !== undefined ? { explicitReceiver } : {}),
+      ...(arity !== undefined ? { arity } : {}),
+    };
+    referenceSites.push(site);
+  }
+}
+
+function referenceKindFromAnchor(name: string): ReferenceKind | undefined {
+  const suffix = name.slice('@reference.'.length);
+  // Strip sub-tag after the kind (`@reference.call.member` → `call`).
+  const firstDot = suffix.indexOf('.');
+  const head = firstDot === -1 ? suffix : suffix.slice(0, firstDot);
+  switch (head.toLowerCase()) {
+    case 'call':
+      return 'call';
+    case 'read':
+      return 'read';
+    case 'write':
+      return 'write';
+    case 'type':
+    case 'type_reference':
+      return 'type-reference';
+    case 'inherits':
+      return 'inherits';
+    case 'import_use':
+    case 'import-use':
+      return 'import-use';
+    default:
+      return undefined;
+  }
+}
+
+function classifyCallFormForMatch(
+  match: CaptureMatch,
+  anchorName: string,
+  provider: ScopeExtractorHooks,
+  scopeTree: ReturnType<typeof buildScopeTree>,
+  inScopeId: ScopeId,
+): 'free' | 'member' | 'constructor' | 'index' {
+  // Declarative sub-tag path first: `@reference.call.member` → 'member'.
+  const suffix = anchorName.slice('@reference.call.'.length);
+  switch (suffix.toLowerCase()) {
+    case 'free':
+      return 'free';
+    case 'member':
+      return 'member';
+    case 'constructor':
+      return 'constructor';
+    case 'index':
+      return 'index';
+  }
+
+  // Hook-based path: provider knows.
+  const hook = provider.classifyCallForm;
+  if (hook !== undefined) {
+    const scope = scopeTree.getScope(inScopeId);
+    if (scope !== undefined) return hook(match, scope);
+  }
+
+  return 'free';
+}
+
+function extractExplicitReceiver(match: CaptureMatch): { readonly name: string } | undefined {
+  const cap = match['@reference.receiver'];
+  if (cap === undefined) return undefined;
+  return { name: cap.text };
+}
+
+function extractArity(match: CaptureMatch): number | undefined {
+  const cap = match['@reference.arity'];
+  if (cap === undefined) return undefined;
+  const n = Number.parseInt(cap.text, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+// ─── Internal: range + capture utilities ───────────────────────────────────
+
+function rangeStrictlyContains(outer: Range, inner: Range): boolean {
+  if (
+    outer.startLine === inner.startLine &&
+    outer.startCol === inner.startCol &&
+    outer.endLine === inner.endLine &&
+    outer.endCol === inner.endCol
+  ) {
+    return false;
+  }
+  const startsBefore =
+    outer.startLine < inner.startLine ||
+    (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
+  const endsAfter =
+    outer.endLine > inner.endLine ||
+    (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
+  return startsBefore && endsAfter;
+}
+
+/**
+ * Capture names that are never anchors — they are sub-tags nested inside a
+ * larger anchor (e.g., the receiver expression inside a `@reference.call`
+ * may span more source than the called name, but is not the call itself).
+ *
+ * The list is maintained here centrally rather than per-pass because the
+ * set is small and stable; adding a new sub-tag convention is a one-line
+ * change.
+ */
+const KNOWN_SUB_TAGS: ReadonlySet<string> = new Set<string>([
+  '@declaration.name',
+  '@declaration.qualified_name',
+  '@import.name',
+  '@import.source',
+  '@import.alias',
+  '@type-binding.name',
+  '@type-binding.type',
+  '@reference.name',
+  '@reference.receiver',
+  '@reference.arity',
+]);
+
+/**
+ * Return the anchor capture for a match — the one whose name begins with
+ * `prefix` AND is not in the known-sub-tag set. When multiple candidates
+ * remain, the broadest-ranged one wins: tree-sitter queries often tag
+ * both a whole statement and a sub-token under the same topic
+ * (`@scope.function` + `@scope.function.name`); the anchor is the
+ * statement-level one.
+ */
+function anchorCaptureFor(
+  match: CaptureMatch,
+  prefix: string,
+): { readonly name: string; readonly range: Range; readonly text: string } | undefined {
+  let best: { readonly name: string; readonly range: Range; readonly text: string } | undefined;
+  let bestSpan = -1;
+  for (const name of Object.keys(match)) {
+    if (!name.startsWith(prefix)) continue;
+    if (KNOWN_SUB_TAGS.has(name)) continue;
+    const cap = match[name]!;
+    const span =
+      (cap.range.endLine - cap.range.startLine) * 1_000_000 +
+      (cap.range.endCol - cap.range.startCol);
+    if (span > bestSpan) {
+      bestSpan = span;
+      best = cap;
+    }
+  }
+  return best;
+}
diff --git a/gitnexus/src/core/ingestion/shadow-harness.ts b/gitnexus/src/core/ingestion/shadow-harness.ts
new file mode 100644
index 000000000..549f2bf49
--- /dev/null
+++ b/gitnexus/src/core/ingestion/shadow-harness.ts
@@ -0,0 +1,222 @@
+/**
+ * Shadow-mode parity harness — dual-run observability for the RFC #909
+ * registry rollout (RFC §6.3; Ring 2 PKG #923).
+ *
+ * ## What it does
+ *
+ *   - Exposes `record({ language, callsite, legacy, newResult })` for
+ *     every call site where the caller has BOTH a legacy-DAG resolution
+ *     and a new `Registry.lookup` resolution.
+ *   - Computes a `ShadowDiff` per record via shared `diffResolutions`
+ *     (#918) and accumulates them in a per-language bucket.
+ *   - At the end of a run, aggregates into a `ShadowParityReport` via
+ *     shared `aggregateDiffs` (#918) — per-language parity %,
+ *     evidence-kind breakdown of divergences, grand-total overall row.
+ *   - Optionally persists the report as JSON under
+ *     `.gitnexus/shadow-parity/` so the static dashboard at
+ *     `gitnexus/shadow-parity-dashboard/` can render it offline.
+ *
+ * ## What it does NOT do
+ *
+ *   - **Invoke either resolution path itself.** The caller must run
+ *     legacy + `Registry.lookup` and pass results in. The harness is a
+ *     side-car, not a dispatcher — this keeps call-processor integration
+ *     surgical when it lands (tracked as a follow-up; the shared model
+ *     doesn't dual-invoke on its own).
+ *   - **Flip anything.** `REGISTRY_PRIMARY_<LANG>` lives in
+ *     `registry-primary-flag.ts` (#924); the harness records the
+ *     caller-supplied "which side is primary" bit for each record so the
+ *     dashboard can label rows, but it does not consult the flag itself.
+ *
+ * ## Activation
+ *
+ * `GITNEXUS_SHADOW_MODE=1` (or `'true'`, `'yes'`, case-insensitive,
+ * trimmed) enables the harness. When disabled, `record()` is a cheap
+ * no-op: no accumulation, no allocation beyond the harness object
+ * itself. Callers can always construct a harness and hand it through;
+ * the "off" overhead is near-zero.
+ *
+ * ## Persistence shape
+ *
+ * When `persist()` is called, the harness writes TWO files:
+ *
+ *   - `<outputDir>/<runId>.json` — the timestamped snapshot (immutable)
+ *   - `<outputDir>/latest.json`  — a pointer that the dashboard reads
+ *
+ * Both files contain the same `PersistedShadowReport` payload:
+ *
+ *   {
+ *     schemaVersion: 1,
+ *     runId: "<iso-8601>-<rand>",
+ *     generatedAt: "<iso-8601>",
+ *     primaryByLanguage: { [lang]: "legacy" | "registry" },
+ *     report: <ShadowParityReport>
+ *   }
+ *
+ * Schema-version-gated so future format changes don't silently confuse
+ * older dashboards. The dashboard renders `report.perLanguage` rows and
+ * annotates each with `primaryByLanguage[lang]`.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {
+  aggregateDiffs,
+  diffResolutions,
+  type Resolution,
+  type ShadowCallsite,
+  type ShadowDiff,
+  type ShadowParityReport,
+  type SupportedLanguages,
+} from 'gitnexus-shared';
+
+// ─── Public API ────────────────────────────────────────────────────────────
+
+/** Which side of the dual-run is considered authoritative for this language. */
+export type PrimarySide = 'legacy' | 'registry';
+
+/** One record per call site the caller dual-runs. */
+export interface ShadowRecordInput {
+  readonly language: SupportedLanguages;
+  readonly callsite: ShadowCallsite;
+  readonly legacy: readonly Resolution[];
+  readonly newResult: readonly Resolution[];
+  /**
+   * Which side drove the actual runtime answer for this record. Lets the
+   * dashboard distinguish "registry-primary, legacy is shadow" from the
+   * default "legacy-primary, registry is shadow" without re-reading
+   * `REGISTRY_PRIMARY_<LANG>` env vars at render time.
+   */
+  readonly primary: PrimarySide;
+}
+
+/** Persisted JSON shape. Schema-versioned for future migrations. */
+export interface PersistedShadowReport {
+  readonly schemaVersion: 1;
+  readonly runId: string;
+  readonly generatedAt: string;
+  readonly primaryByLanguage: Readonly<Partial<Record<SupportedLanguages, PrimarySide>>>;
+  readonly report: ShadowParityReport;
+}
+
+export interface ShadowHarness {
+  /** `true` iff `GITNEXUS_SHADOW_MODE` is truthy. When `false`, `record()` is a no-op. */
+  readonly enabled: boolean;
+  /** Accumulate a dual-run observation. No-op when `enabled === false`. */
+  record(input: ShadowRecordInput): void;
+  /** Number of records accumulated so far. Useful for diagnostics / tests. */
+  size(): number;
+  /**
+   * Aggregate the accumulated records into a `ShadowParityReport`
+   * without persisting. Returns a deterministic snapshot each call;
+   * idempotent with respect to `record()` ordering.
+   */
+  snapshot(now?: Date): ShadowParityReport;
+  /**
+   * Write the aggregated snapshot to JSON. Resolves to the path of the
+   * per-run file. Also writes/overwrites `latest.json` alongside.
+   *
+   * Creates `outputDir` if it doesn't exist.
+   */
+  persist(outputDir: string, now?: Date): Promise<string>;
+  /** Reset the accumulator. Preserves `enabled`. */
+  clear(): void;
+}
+
+/**
+ * Construct a harness. Reads `GITNEXUS_SHADOW_MODE` at construction time
+ * (not per-`record()` call) so repeated no-op records don't re-check the
+ * env var in the hot path.
+ */
+export function createShadowHarness(): ShadowHarness {
+  const enabled = parseShadowModeEnv(process.env['GITNEXUS_SHADOW_MODE']);
+
+  interface Accumulated {
+    readonly language: SupportedLanguages;
+    readonly diff: ShadowDiff;
+  }
+  const records: Accumulated[] = [];
+  const primaryByLanguage: Partial<Record<SupportedLanguages, PrimarySide>> = {};
+
+  const recordImpl = (input: ShadowRecordInput): void => {
+    if (!enabled) return;
+    const diff = diffResolutions(input.callsite, input.legacy, input.newResult);
+    records.push({ language: input.language, diff });
+    // Primary per-language is resolved by last-write. In practice a run
+    // is single-threaded with respect to flag readings, so this is
+    // deterministic; a language's primary cannot change mid-run.
+    primaryByLanguage[input.language] = input.primary;
+  };
+
+  const snapshotImpl = (now: Date = new Date()): ShadowParityReport => {
+    return aggregateDiffs(records, now);
+  };
+
+  const persistImpl = async (outputDir: string, now: Date = new Date()): Promise<string> => {
+    await fs.mkdir(outputDir, { recursive: true });
+    const report = snapshotImpl(now);
+    const runId = makeRunId(now);
+    const payload: PersistedShadowReport = {
+      schemaVersion: 1,
+      runId,
+      generatedAt: now.toISOString(),
+      primaryByLanguage,
+      report,
+    };
+    const json = JSON.stringify(payload, null, 2);
+    const perRunPath = path.join(outputDir, `${runId}.json`);
+    const latestPath = path.join(outputDir, 'latest.json');
+    await fs.writeFile(perRunPath, json, 'utf8');
+    await fs.writeFile(latestPath, json, 'utf8');
+    return perRunPath;
+  };
+
+  const clearImpl = (): void => {
+    records.length = 0;
+    for (const key of Object.keys(primaryByLanguage)) {
+      delete primaryByLanguage[key as SupportedLanguages];
+    }
+  };
+
+  return {
+    enabled,
+    record: recordImpl,
+    size: () => records.length,
+    snapshot: snapshotImpl,
+    persist: persistImpl,
+    clear: clearImpl,
+  };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────
+
+/**
+ * Env-var parser for `GITNEXUS_SHADOW_MODE`. Accepts the same truthy
+ * conventions as `REGISTRY_PRIMARY_<LANG>` from #924: `'true'` / `'1'` /
+ * `'yes'`, case-insensitive, whitespace-trimmed. Anything else — including
+ * `undefined`, `''`, `'false'`, `'off'`, typos — is false.
+ */
+function parseShadowModeEnv(raw: string | undefined): boolean {
+  if (raw === undefined) return false;
+  const normalized = raw.trim().toLowerCase();
+  return normalized === 'true' || normalized === '1' || normalized === 'yes';
+}
+
+/**
+ * Deterministic run id derived from the timestamp plus 4 random bytes
+ * of entropy. The timestamp comes first so files sort chronologically;
+ * the entropy suffix prevents collisions when multiple runs share a
+ * clock-second. Shape: `YYYYMMDD-HHMMSS-xxxxxxxx`.
+ */
+function makeRunId(now: Date): string {
+  const y = now.getUTCFullYear().toString().padStart(4, '0');
+  const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = now.getUTCDate().toString().padStart(2, '0');
+  const h = now.getUTCHours().toString().padStart(2, '0');
+  const min = now.getUTCMinutes().toString().padStart(2, '0');
+  const s = now.getUTCSeconds().toString().padStart(2, '0');
+  const entropy = Math.floor(Math.random() * 0xffffffff)
+    .toString(16)
+    .padStart(8, '0');
+  return `${y}${m}${d}-${h}${min}${s}-${entropy}`;
+}
diff --git a/gitnexus/src/core/ingestion/tree-sitter-queries.ts b/gitnexus/src/core/ingestion/tree-sitter-queries.ts
index 99fd3b21c..18b163777 100644
--- a/gitnexus/src/core/ingestion/tree-sitter-queries.ts
+++ b/gitnexus/src/core/ingestion/tree-sitter-queries.ts
@@ -61,6 +61,22 @@ export const TYPESCRIPT_QUERIES = `
       name: (identifier) @name
       value: (function_expression)))) @definition.function
 
+; Variable/constant declarations (non-function values).
+; Overlap with @definition.function patterns is handled by parse-worker dedup.
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name)) @definition.const
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name))) @definition.const
+
+; var declarations (mutable, function-scoped)
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @name)) @definition.variable
+
 (import_statement
   source: (string) @import.source) @import
 
@@ -203,6 +219,22 @@ export const JAVASCRIPT_QUERIES = `
       name: (identifier) @name
       value: (function_expression)))) @definition.function
 
+; Variable/constant declarations (non-function values).
+; Overlap with @definition.function patterns is handled by parse-worker dedup.
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @name)) @definition.const
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @name))) @definition.const
+
+; var declarations (mutable, function-scoped)
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @name)) @definition.variable
+
 (import_statement
   source: (string) @import.source) @import
 
@@ -306,6 +338,12 @@ export const PYTHON_QUERIES = `
     left: (identifier) @name
     type: (type)) @definition.property)
 
+; Plain variable assignments without type annotation: x = 5, MAX_SIZE = 100
+; Overlap with @definition.property (typed) is handled by parse-worker dedup.
+(expression_statement
+  (assignment
+    left: (identifier) @name)) @definition.variable
+
 ; Heritage queries - Python class inheritance
 (class_definition
   name: (identifier) @heritage.class
@@ -371,6 +409,11 @@ export const JAVA_QUERIES = `
 ; Constructor calls: new Foo()
 (object_creation_expression type: (type_identifier) @call.name) @call
 
+; Local variable declarations inside method bodies
+(local_variable_declaration
+  declarator: (variable_declarator
+    name: (identifier) @name)) @definition.variable
+
 ; Heritage - extends class
 (class_declaration name: (identifier) @heritage.class
   (superclass (type_identifier) @heritage.extends)) @heritage
@@ -416,6 +459,11 @@ export const C_QUERIES = `
 ; Calls
 (call_expression function: (identifier) @call.name) @call
 (call_expression function: (field_expression field: (field_identifier) @call.name)) @call
+
+; Variable declarations: int x = 5; or int x;
+(declaration
+  declarator: (init_declarator
+    declarator: (identifier) @name)) @definition.variable
 `;
 
 // Go queries - works with tree-sitter-go
@@ -450,6 +498,13 @@ export const GO_QUERIES = `
 (call_expression function: (identifier) @call.name) @call
 (call_expression function: (selector_expression field: (field_identifier) @call.name)) @call
 
+; Const/var declarations
+(const_declaration (const_spec name: (identifier) @name)) @definition.const
+(var_declaration (var_spec name: (identifier) @name)) @definition.variable
+
+; Short variable declaration: x := 5
+(short_var_declaration left: (expression_list (identifier) @name)) @definition.variable
+
 ; Struct literal construction: User{Name: "Alice"}
 (composite_literal type: (type_identifier) @call.name) @call
 
@@ -572,6 +627,11 @@ export const CPP_QUERIES = `
 ; Constructor calls: new User()
 (new_expression type: (type_identifier) @call.name) @call
 
+; Variable declarations: int x = 5; or auto x = 5;
+(declaration
+  declarator: (init_declarator
+    declarator: (identifier) @name)) @definition.variable
+
 ; Heritage
 (class_specifier name: (type_identifier) @heritage.class
   (base_class_clause (type_identifier) @heritage.extends)) @heritage
@@ -634,6 +694,12 @@ export const CSHARP_QUERIES = `
 ; Target-typed new (C# 9): User u = new("x", 5)
 (variable_declaration type: (identifier) @call.name (variable_declarator (implicit_object_creation_expression) @call))
 
+; Local variable declarations
+(local_declaration_statement
+  (variable_declaration
+    (variable_declarator
+      (identifier) @name))) @definition.variable
+
 ; Heritage
 (class_declaration name: (identifier) @heritage.class
   (base_list (identifier) @heritage.extends)) @heritage
@@ -781,6 +847,11 @@ export const PHP_QUERIES = `
 ; Constructor call: new User()
 (object_creation_expression (name) @call.name) @call
 
+; Const declarations at class scope
+(const_declaration
+  (const_element
+    (name) @name)) @definition.const
+
 ; ── Heritage: extends ────────────────────────────────────────────────────────
 (class_declaration
   name: (name) @heritage.class
@@ -849,6 +920,10 @@ export const RUBY_QUERIES = `
 (call
   method: (identifier) @call.name) @call
 
+; ── Constant assignment: MAX_SIZE = 100, ITEMS = [...] ───────────────────────
+(assignment
+  left: (constant) @name) @definition.const
+
 ; ── Bare calls without parens (identifiers at statement level are method calls) ─
 ; NOTE: This may over-capture variable reads as calls (e.g. 'result' at
 ; statement level). Ruby's grammar makes bare identifiers ambiguous — they
@@ -1123,6 +1198,12 @@ export const DART_QUERIES = `
   (setter_signature
     name: (identifier) @name)) @definition.property
 
+; ── Top-level variable declarations (const maxSize = 100, final x = 5, var y = 0) ──
+(declaration
+  (initialized_identifier_list
+    (initialized_identifier
+      (identifier) @name))) @definition.variable
+
 ; ── Imports ──────────────────────────────────────────────────────────────────
 (import_or_export
   (library_import
diff --git a/gitnexus/src/core/ingestion/type-env.ts b/gitnexus/src/core/ingestion/type-env.ts
index 368de762b..998e7a59e 100644
--- a/gitnexus/src/core/ingestion/type-env.ts
+++ b/gitnexus/src/core/ingestion/type-env.ts
@@ -21,7 +21,7 @@ import {
   stripNullable,
   extractReturnTypeName,
 } from './type-extractors/shared.js';
-import type { SemanticModel } from './model/semantic-model.js';
+import type { SemanticModel } from './model/index.js';
 import type { NodeLabel } from 'gitnexus-shared';
 
 /**
diff --git a/gitnexus/src/core/ingestion/utils/ast-helpers.ts b/gitnexus/src/core/ingestion/utils/ast-helpers.ts
index 2d4b794ae..f482fbec6 100644
--- a/gitnexus/src/core/ingestion/utils/ast-helpers.ts
+++ b/gitnexus/src/core/ingestion/utils/ast-helpers.ts
@@ -24,6 +24,7 @@ export const DEFINITION_CAPTURE_KEYS = [
   'definition.type',
   'definition.const',
   'definition.static',
+  'definition.variable',
   'definition.typedef',
   'definition.macro',
   'definition.union',
@@ -152,7 +153,14 @@ export const CONTAINER_TYPE_TO_LABEL: Record<string, string> = {
   mixin_declaration: 'Mixin',
   extension_declaration: 'Extension',
   class: 'Class',
-  module: 'Module',
+  // Ruby `module` declarations map to `Trait` so they participate in the
+  // class-like type registry used by `lookupClassByName` / `buildHeritageMap`.
+  // This lets `include` / `extend` / `prepend` mixin heritage resolve to
+  // the providing module. Safe for non-Ruby languages: the only supported
+  // grammar that uses the bare `module` AST node type as a container is
+  // Ruby (Rust uses `mod_item`). Any new language adding a `module` node
+  // type must explicitly reclassify here.
+  module: 'Trait',
   singleton_class: 'Class', // Ruby: class << self inherits enclosing class name
   object_declaration: 'Class',
   companion_object: 'Class',
@@ -184,12 +192,23 @@ export function getLabelFromCaptures(
   if (captureMap['definition.struct']) return 'Struct';
   if (captureMap['definition.enum']) return 'Enum';
   if (captureMap['definition.namespace']) return 'Namespace';
-  if (captureMap['definition.module']) return 'Module';
+  if (captureMap['definition.module']) {
+    // Let providers reclassify module captures (e.g. Ruby remaps `Module`→`Trait`
+    // so mixin heritage resolves through `lookupClassByName`). Returning null
+    // from labelOverride means "skip this symbol"; treat it as a no-op here so
+    // we keep the default label rather than dropping a real definition.
+    if (provider.labelOverride) {
+      const override = provider.labelOverride(captureMap['definition.module'], 'Module');
+      if (override && override !== 'Module') return override;
+    }
+    return 'Module';
+  }
   if (captureMap['definition.trait']) return 'Trait';
   if (captureMap['definition.impl']) return 'Impl';
   if (captureMap['definition.type']) return 'TypeAlias';
   if (captureMap['definition.const']) return 'Const';
   if (captureMap['definition.static']) return 'Static';
+  if (captureMap['definition.variable']) return 'Variable';
   if (captureMap['definition.typedef']) return 'Typedef';
   if (captureMap['definition.macro']) return 'Macro';
   if (captureMap['definition.union']) return 'Union';
diff --git a/gitnexus/src/core/ingestion/utils/ruby-self-call.ts b/gitnexus/src/core/ingestion/utils/ruby-self-call.ts
new file mode 100644
index 000000000..16fc7e7ab
--- /dev/null
+++ b/gitnexus/src/core/ingestion/utils/ruby-self-call.ts
@@ -0,0 +1,101 @@
+// gitnexus/src/core/ingestion/utils/ruby-self-call.ts
+
+/**
+ * Ruby bare-call self-inference helper.
+ *
+ * Ruby makes `self` implicit for method calls inside instance and class bodies:
+ * `serialize` inside `Account#call_serialize` means `self.serialize`. Other
+ * supported languages make the receiver explicit in source (`this.x`, `self.x`),
+ * so tree-sitter produces a member call directly. Ruby's bare identifier
+ * produces either `callForm === 'free'` or `callForm === undefined` (body_statement
+ * identifier captures where the @call node IS the @call.name node), and
+ * `resolveFreeCall` does a global tiered name lookup — no MRO walk.
+ *
+ * This helper is a pure decision function consumed by the Ruby language
+ * provider's `inferImplicitReceiver` hook. Shared pipeline code never imports
+ * it directly — only `languages/ruby.ts` does.
+ */
+
+import type { SyntaxNode } from './ast-helpers.js';
+import type { LanguageProvider } from '../language-provider.js';
+
+/**
+ * Rewrite suggestion returned by `maybeRewriteRubyBareCallToSelf`.
+ *
+ * `callForm` is always `'member'`; `receiverName` is always `'self'`.
+ * `dispatchKind` controls the stage-4 ancestry view:
+ * - `'instance'` → prepend → direct → include (normal MRO)
+ * - `'singleton'` → extend providers only, no file-scoped fallback
+ *
+ * Consumed by `languages/ruby.ts § inferImplicitReceiver` (wraps into
+ * `ImplicitReceiverOverride`; `dispatchKind` becomes the `hint` field).
+ */
+export interface SelfCallRewrite {
+  readonly callForm: 'member';
+  readonly receiverName: 'self';
+  readonly receiverTypeName: string;
+  /** `'singleton'` when the enclosing method is `def self.foo` / inside a
+   *  `singleton_class` body; `'instance'` otherwise. Controls MRO ancestry
+   *  view selection in stage-4 dispatch. */
+  readonly dispatchKind: 'instance' | 'singleton';
+}
+
+/** Maximum parent-walk depth to prevent runaway traversal. */
+const MAX_PARENT_DEPTH = 50;
+
+/**
+ * Returns true if `callNode` is inside a `singleton_method` or `singleton_class`.
+ * Stops at `class`/`module` boundary or MAX_PARENT_DEPTH (50) to bound traversal.
+ */
+function isInsideSingletonMethod(callNode: SyntaxNode): boolean {
+  let current: SyntaxNode | null = callNode.parent;
+  let depth = 0;
+  while (current && depth++ < MAX_PARENT_DEPTH) {
+    if (current.type === 'singleton_method') return true;
+    if (current.type === 'singleton_class') return true;
+    if (current.type === 'class' || current.type === 'module') return false;
+    current = current.parent;
+  }
+  return false;
+}
+
+/**
+ * Pure decision function: should a bare Ruby call be rewritten as `self.method`?
+ *
+ * Returns a `SelfCallRewrite` when all gates pass; null otherwise.
+ * Gates (all required): `callForm` is `'free'` or `undefined`, strategy is
+ * `'ruby-mixin'`, `enclosingClassName` is non-null, name is not `'super'`,
+ * name is not a built-in.
+ *
+ * Note: Ruby body-statement identifiers produce `callForm === undefined` because
+ * the @call node IS the @call.name node in tree-sitter-ruby.
+ *
+ * Example: `calledName='serialize'` in `Account` instance method →
+ * `{callForm:'member', receiverName:'self', receiverTypeName:'Account', dispatchKind:'instance'}`
+ */
+export function maybeRewriteRubyBareCallToSelf(
+  calledName: string,
+  callForm: 'free' | 'member' | 'constructor' | undefined,
+  callNode: SyntaxNode,
+  enclosingClassName: string | null,
+  provider: Pick<LanguageProvider, 'isBuiltInName' | 'mroStrategy'>,
+): SelfCallRewrite | null {
+  // Body-statement bare identifiers produce `callForm === undefined` because
+  // the @call node IS the @call.name node in tree-sitter-ruby. Treat both
+  // undefined and 'free' as qualifying.
+  if (callForm !== 'free' && callForm !== undefined) return null;
+  if (provider.mroStrategy !== 'ruby-mixin') return null;
+  if (!enclosingClassName) return null;
+  if (calledName === 'super') return null;
+  if (provider.isBuiltInName(calledName)) return null;
+
+  const dispatchKind: SelfCallRewrite['dispatchKind'] = isInsideSingletonMethod(callNode)
+    ? 'singleton'
+    : 'instance';
+  return {
+    callForm: 'member',
+    receiverName: 'self',
+    receiverTypeName: enclosingClassName,
+    dispatchKind,
+  };
+}
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/c-cpp.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/c-cpp.ts
new file mode 100644
index 000000000..29bf952ed
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/c-cpp.ts
@@ -0,0 +1,93 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/c-cpp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { hasKeyword } from '../../field-extractors/configs/helpers.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * C/C++ variable extraction config.
+ *
+ * Handles global/namespace-scoped variable declarations:
+ * - `int x = 5;`
+ * - `const int MAX = 100;`
+ * - `static int counter = 0;`
+ * - `constexpr int SIZE = 10;` (C++)
+ * - `extern int shared;`
+ *
+ * tree-sitter-c/cpp uses declaration for variable declarations.
+ */
+
+function extractCVarName(node: SyntaxNode): string | undefined {
+  // declaration → declarator (init_declarator or identifier)
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'init_declarator') {
+      const declarator = child.childForFieldName('declarator');
+      if (declarator?.type === 'identifier') return declarator.text;
+      if (declarator?.type === 'pointer_declarator') {
+        const inner = declarator.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+        return inner?.text;
+      }
+    }
+    if (child?.type === 'identifier') return child.text;
+  }
+  return undefined;
+}
+
+function extractCVarType(node: SyntaxNode): string | undefined {
+  const typeNode = node.childForFieldName('type');
+  if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+  // Fallback: first primitive_type or type_identifier child
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (
+      child?.type === 'primitive_type' ||
+      child?.type === 'type_identifier' ||
+      child?.type === 'sized_type_specifier'
+    ) {
+      return child.text?.trim();
+    }
+  }
+  return undefined;
+}
+
+const shared: Omit<VariableExtractionConfig, 'language'> = {
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['declaration'],
+
+  extractName: extractCVarName,
+  extractType: extractCVarType,
+
+  extractVisibility(node): VariableVisibility {
+    // C/C++ visibility is file-scoped by default (static = file-private)
+    if (hasKeyword(node, 'static')) return 'private';
+    if (hasKeyword(node, 'extern')) return 'public';
+    return 'public';
+  },
+
+  isConst(node) {
+    return hasKeyword(node, 'const') || hasKeyword(node, 'constexpr');
+  },
+
+  isStatic(node) {
+    return hasKeyword(node, 'static');
+  },
+
+  isMutable(node) {
+    return !hasKeyword(node, 'const') && !hasKeyword(node, 'constexpr');
+  },
+};
+
+export const cVariableConfig: VariableExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.C,
+};
+
+export const cppVariableConfig: VariableExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.CPlusPlus,
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/csharp.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/csharp.ts
new file mode 100644
index 000000000..002207cca
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/csharp.ts
@@ -0,0 +1,64 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/csharp.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { collectModifierTexts } from '../../field-extractors/configs/helpers.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+
+/**
+ * C# variable extraction config.
+ *
+ * C# does not have true top-level variables (pre-C# 9). In C# 9+ top-level
+ * statements, local_declaration_statement can appear at program scope.
+ * Class-scoped fields are handled by the field extractor.
+ */
+export const csharpVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.CSharp,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['local_declaration_statement'],
+
+  extractName(node) {
+    // local_declaration_statement → variable_declaration → variable_declarator → identifier
+    const varDecl = node.namedChildren.find((c) => c.type === 'variable_declaration');
+    if (!varDecl) return undefined;
+    const declarator = varDecl.namedChildren.find((c) => c.type === 'variable_declarator');
+    const name = declarator?.childForFieldName('name');
+    return name?.type === 'identifier' ? name.text : undefined;
+  },
+
+  extractType(node) {
+    const varDecl = node.namedChildren.find((c) => c.type === 'variable_declaration');
+    if (!varDecl) return undefined;
+    const typeNode = varDecl.childForFieldName('type');
+    if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    return undefined;
+  },
+
+  extractVisibility(node): VariableVisibility {
+    const mods = collectModifierTexts(node);
+    if (mods.has('public')) return 'public';
+    if (mods.has('private')) return 'private';
+    if (mods.has('protected') && mods.has('internal')) return 'protected internal';
+    if (mods.has('private') && mods.has('protected')) return 'private protected';
+    if (mods.has('protected')) return 'protected';
+    if (mods.has('internal')) return 'internal';
+    return 'private';
+  },
+
+  isConst(node) {
+    const mods = collectModifierTexts(node);
+    return mods.has('const');
+  },
+
+  isStatic(node) {
+    const mods = collectModifierTexts(node);
+    return mods.has('static');
+  },
+
+  isMutable(node) {
+    const mods = collectModifierTexts(node);
+    return !mods.has('const') && !mods.has('readonly');
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/dart.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/dart.ts
new file mode 100644
index 000000000..a7e52afa4
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/dart.ts
@@ -0,0 +1,101 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/dart.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Dart variable extraction config.
+ *
+ * Dart has top-level variable and constant declarations:
+ * - `const maxSize = 100;`
+ * - `final String name = "dart";`
+ * - `var counter = 0;`
+ * - `int x = 5;`
+ *
+ * tree-sitter-dart uses:
+ * - declaration (with initialized_identifier_list) for file-scope variables
+ */
+
+function extractDartVarName(node: SyntaxNode): string | undefined {
+  // declaration → initialized_variable_definition → identifier
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'initialized_variable_definition') {
+      const name = child.childForFieldName('name');
+      if (name) return name.text;
+      // Fallback: first identifier
+      for (let j = 0; j < child.namedChildCount; j++) {
+        const gc = child.namedChild(j);
+        if (gc?.type === 'identifier') return gc.text;
+      }
+    }
+    // declaration → initialized_identifier_list → initialized_identifier → identifier
+    if (child?.type === 'initialized_identifier_list') {
+      for (let j = 0; j < child.namedChildCount; j++) {
+        const gc = child.namedChild(j);
+        if (gc?.type === 'initialized_identifier') {
+          const ident = gc.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+          if (ident) return ident.text;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+function extractDartVarType(node: SyntaxNode): string | undefined {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'initialized_variable_definition') {
+      const typeNode = child.childForFieldName('type');
+      if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    }
+  }
+  // Look for type_identifier directly on the node
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'type_identifier') return child.text;
+  }
+  return undefined;
+}
+
+function hasDartKeyword(node: SyntaxNode, keyword: string): boolean {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.text === keyword) return true;
+  }
+  return false;
+}
+
+export const dartVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Dart,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['declaration'],
+
+  extractName: extractDartVarName,
+  extractType: extractDartVarType,
+
+  extractVisibility(node): VariableVisibility {
+    const name = extractDartVarName(node);
+    if (!name) return 'public';
+    // Dart convention: underscore prefix = library-private
+    return name.startsWith('_') ? 'private' : 'public';
+  },
+
+  isConst(node) {
+    return hasDartKeyword(node, 'const') || hasDartKeyword(node, 'final');
+  },
+
+  isStatic(_node) {
+    // Top-level Dart variables are not static
+    return false;
+  },
+
+  isMutable(node) {
+    return !hasDartKeyword(node, 'const') && !hasDartKeyword(node, 'final');
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/go.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/go.ts
new file mode 100644
index 000000000..2277aecfc
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/go.ts
@@ -0,0 +1,91 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/go.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Go variable extraction config.
+ *
+ * Go has package-scoped var and const declarations:
+ * - `var x int = 5`
+ * - `const MaxSize = 100`
+ * - `var ( ... )` grouped declarations
+ *
+ * tree-sitter-go uses:
+ * - var_declaration → var_spec → identifier, type
+ * - const_declaration → const_spec → identifier, type
+ *
+ * Visibility: uppercase first letter = exported (public), lowercase = unexported (package).
+ */
+
+function extractGoVarName(node: SyntaxNode): string | undefined {
+  // var_declaration/const_declaration → var_spec/const_spec → identifier
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'var_spec' || child?.type === 'const_spec') {
+      const name = child.childForFieldName('name');
+      if (name) return name.text;
+      // Fallback: first identifier child
+      for (let j = 0; j < child.namedChildCount; j++) {
+        const gc = child.namedChild(j);
+        if (gc?.type === 'identifier') return gc.text;
+      }
+    }
+  }
+  // short_var_declaration: x := 5 → expression_list → identifier
+  if (node.type === 'short_var_declaration') {
+    const left = node.childForFieldName('left');
+    if (left?.type === 'expression_list') {
+      const firstIdent = left.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+      if (firstIdent) return firstIdent.text;
+    }
+  }
+  return undefined;
+}
+
+function extractGoVarType(node: SyntaxNode): string | undefined {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'var_spec' || child?.type === 'const_spec') {
+      const typeNode = child.childForFieldName('type');
+      if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    }
+  }
+  return undefined;
+}
+
+export const goVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Go,
+  constNodeTypes: ['const_declaration'],
+  staticNodeTypes: [],
+  variableNodeTypes: ['var_declaration', 'short_var_declaration'],
+
+  extractName: extractGoVarName,
+  extractType: extractGoVarType,
+
+  extractVisibility(node): VariableVisibility {
+    const name = extractGoVarName(node);
+    if (!name) return 'package';
+    // Go visibility: uppercase first letter = exported
+    const firstChar = name.charAt(0);
+    return firstChar === firstChar.toUpperCase() && firstChar !== firstChar.toLowerCase()
+      ? 'public'
+      : 'package';
+  },
+
+  isConst(node) {
+    return node.type === 'const_declaration';
+  },
+
+  isStatic(_node) {
+    // Go does not have static declarations
+    return false;
+  },
+
+  isMutable(node) {
+    return node.type !== 'const_declaration';
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/jvm.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/jvm.ts
new file mode 100644
index 000000000..6ebaa3024
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/jvm.ts
@@ -0,0 +1,124 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/jvm.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { hasModifier } from '../../field-extractors/configs/helpers.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Java variable extraction config.
+ *
+ * Java does not have true module-level variables — all declarations are
+ * class-scoped. However, `static final` fields at class scope act like
+ * constants. These are already handled by the field extractor. This config
+ * covers any rare local_variable_declaration captures at file scope
+ * (e.g., in scripts or top-level code blocks in JShell).
+ */
+export const javaVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Java,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['local_variable_declaration'],
+
+  extractName(node) {
+    const declarator = node.namedChildren.find((c) => c.type === 'variable_declarator');
+    const name = declarator?.childForFieldName('name');
+    return name?.type === 'identifier' ? name.text : undefined;
+  },
+
+  extractType(node) {
+    const typeNode = node.childForFieldName('type');
+    if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    return undefined;
+  },
+
+  extractVisibility(node): VariableVisibility {
+    if (hasModifier(node, 'modifiers', 'public')) return 'public';
+    if (hasModifier(node, 'modifiers', 'private')) return 'private';
+    if (hasModifier(node, 'modifiers', 'protected')) return 'protected';
+    return 'package';
+  },
+
+  isConst(node) {
+    return hasModifier(node, 'modifiers', 'final');
+  },
+
+  isStatic(node) {
+    return hasModifier(node, 'modifiers', 'static');
+  },
+
+  isMutable(node) {
+    return !hasModifier(node, 'modifiers', 'final');
+  },
+};
+
+/**
+ * Kotlin variable extraction config.
+ *
+ * Kotlin has true top-level val/var declarations outside classes.
+ * tree-sitter-kotlin uses 'property_declaration' for both.
+ */
+export const kotlinVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Kotlin,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['property_declaration'],
+
+  extractName(node) {
+    // property_declaration → variable_declaration → simple_identifier
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === 'variable_declaration') {
+        const ident = child.namedChildren.find((c: SyntaxNode) => c.type === 'simple_identifier');
+        return ident?.text;
+      }
+    }
+    return undefined;
+  },
+
+  extractType(node) {
+    // Look for type annotation in variable_declaration child
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === 'variable_declaration') {
+        const typeNode = child.namedChildren.find(
+          (c: SyntaxNode) => c.type === 'user_type' || c.type === 'nullable_type',
+        );
+        if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+      }
+    }
+    return undefined;
+  },
+
+  extractVisibility(node): VariableVisibility {
+    if (hasModifier(node, 'modifiers', 'public')) return 'public';
+    if (hasModifier(node, 'modifiers', 'private')) return 'private';
+    if (hasModifier(node, 'modifiers', 'protected')) return 'protected';
+    if (hasModifier(node, 'modifiers', 'internal')) return 'internal';
+    return 'public'; // Kotlin default is public
+  },
+
+  isConst(node) {
+    // val is immutable; also check for `const` modifier
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child?.text === 'val') return true;
+    }
+    return hasModifier(node, 'modifiers', 'const');
+  },
+
+  isStatic(_node) {
+    // Top-level Kotlin properties are not static in the Java sense
+    return false;
+  },
+
+  isMutable(node) {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child?.text === 'var') return true;
+    }
+    return false;
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/php.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/php.ts
new file mode 100644
index 000000000..9c940d4f1
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/php.ts
@@ -0,0 +1,67 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/php.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { hasKeyword } from '../../field-extractors/configs/helpers.js';
+
+/**
+ * PHP variable extraction config.
+ *
+ * PHP has const declarations at namespace/file scope and global variables:
+ * - `const MAX_SIZE = 100;`
+ * - `define('MAX_SIZE', 100);`
+ * - `$variable = value;`
+ *
+ * tree-sitter-php uses:
+ * - const_declaration at namespace/program scope
+ * - expression_statement containing assignment_expression for variables
+ */
+export const phpVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.PHP,
+  constNodeTypes: ['const_declaration'],
+  staticNodeTypes: [],
+  variableNodeTypes: ['expression_statement'],
+
+  extractName(node) {
+    if (node.type === 'const_declaration') {
+      // const_declaration → const_element → name (identifier)
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child?.type === 'const_element') {
+          const name = child.childForFieldName('name');
+          return name?.text;
+        }
+      }
+      return undefined;
+    }
+    // expression_statement → assignment_expression → variable_name
+    const inner = node.firstNamedChild;
+    if (inner?.type === 'assignment_expression') {
+      const left = inner.childForFieldName('left');
+      if (left?.type === 'variable_name') return left.text;
+    }
+    return undefined;
+  },
+
+  extractType(_node) {
+    // PHP is dynamically typed — no inline type annotations for variables
+    return undefined;
+  },
+
+  extractVisibility(_node): VariableVisibility {
+    return 'public';
+  },
+
+  isConst(node) {
+    return node.type === 'const_declaration';
+  },
+
+  isStatic(node) {
+    return hasKeyword(node, 'static');
+  },
+
+  isMutable(node) {
+    return node.type !== 'const_declaration';
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/python.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/python.ts
new file mode 100644
index 000000000..d0f7722fb
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/python.ts
@@ -0,0 +1,109 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/python.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Python variable extraction config.
+ *
+ * Handles module-level assignments and annotated assignments:
+ * - `MAX_SIZE = 100` → const by UPPER_CASE convention
+ * - `name: str = "default"` → annotated assignment with type
+ * - `_private_var = 42` → protected by convention
+ * - `__private_var = 42` → private by convention
+ *
+ * tree-sitter-python uses:
+ * - expression_statement containing assignment or type nodes
+ */
+
+function extractNameFromPython(node: SyntaxNode): string | undefined {
+  const inner = node.firstNamedChild;
+  if (!inner) return undefined;
+
+  // Annotated assignment: name: str = "default"
+  // AST: expression_statement > type > identifier
+  if (inner.type === 'type') {
+    const ident = inner.childForFieldName('name') ?? inner.firstNamedChild;
+    return ident?.type === 'identifier' ? ident.text : undefined;
+  }
+
+  // Plain assignment: x = 5
+  if (inner.type === 'assignment') {
+    const left = inner.childForFieldName('left');
+    if (left?.type === 'identifier') return left.text;
+  }
+
+  return undefined;
+}
+
+function extractTypeFromPython(node: SyntaxNode): string | undefined {
+  const inner = node.firstNamedChild;
+  if (!inner) return undefined;
+
+  // Standalone annotated type without assignment: `name: str`
+  if (inner.type === 'type') {
+    const typeNode = inner.childForFieldName('type') ?? inner.namedChild(1);
+    if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+  }
+
+  // Annotated assignment: `name: str = "hello"`
+  // AST: expression_statement > assignment > [identifier, type > identifier, ...]
+  if (inner.type === 'assignment') {
+    for (let i = 0; i < inner.childCount; i++) {
+      const child = inner.child(i);
+      if (child?.type === 'type') {
+        const typeId = child.firstNamedChild;
+        if (typeId) return extractSimpleTypeName(typeId) ?? typeId.text?.trim();
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function extractVisFromPython(node: SyntaxNode): VariableVisibility {
+  const name = extractNameFromPython(node);
+  if (!name) return 'public';
+  // Dunder names (__name__, __all__) are public Python conventions
+  if (name.startsWith('__') && name.endsWith('__')) return 'public';
+  // Double underscore prefix (name mangled) = private
+  if (name.startsWith('__')) return 'private';
+  // Single underscore prefix = protected by convention
+  if (name.startsWith('_')) return 'protected';
+  return 'public';
+}
+
+export const pythonVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Python,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  // expression_statement is broad — isVariableDeclaration returns true for
+  // all expression_statement nodes, but extract() safely filters non-assignments
+  // by returning null when extractNameFromPython finds no assignment target.
+  variableNodeTypes: ['expression_statement'],
+
+  extractName: extractNameFromPython,
+  extractType: extractTypeFromPython,
+  extractVisibility: extractVisFromPython,
+
+  isConst(node) {
+    // Python convention: UPPER_CASE names are constants
+    const name = extractNameFromPython(node);
+    if (!name) return false;
+    return name === name.toUpperCase() && /^[A-Z][A-Z0-9_]*$/.test(name);
+  },
+
+  isStatic(_node) {
+    return false;
+  },
+
+  isMutable(node) {
+    const name = extractNameFromPython(node);
+    if (!name) return true;
+    // By convention, UPPER_CASE names are immutable constants
+    return !(name === name.toUpperCase() && /^[A-Z][A-Z0-9_]*$/.test(name));
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/ruby.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/ruby.ts
new file mode 100644
index 000000000..4c57cca0d
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/ruby.ts
@@ -0,0 +1,57 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/ruby.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+
+/**
+ * Ruby variable extraction config.
+ *
+ * Ruby module-level constants use UPPER_CASE identifiers or start with
+ * an uppercase letter. Ruby uses:
+ * - assignment for variable declarations at module scope
+ * - Constants: `MAX_SIZE = 100` or `Config = ...`
+ * - Global variables: `$global = ...`
+ */
+export const rubyVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Ruby,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['assignment'],
+
+  extractName(node) {
+    const left = node.childForFieldName('left');
+    if (!left) return undefined;
+    if (left.type === 'identifier' || left.type === 'constant') return left.text;
+    if (left.type === 'global_variable') return left.text;
+    return undefined;
+  },
+
+  extractType(_node) {
+    // Ruby is dynamically typed — no type annotations at module level
+    return undefined;
+  },
+
+  extractVisibility(_node): VariableVisibility {
+    const left = _node.childForFieldName('left');
+    if (!left) return 'public';
+    // Constants (uppercase start) and global variables are effectively public
+    if (left.type === 'constant' || left.type === 'global_variable') return 'public';
+    return 'private';
+  },
+
+  isConst(node) {
+    const left = node.childForFieldName('left');
+    return left?.type === 'constant';
+  },
+
+  isStatic(_node) {
+    return false;
+  },
+
+  isMutable(node) {
+    const left = node.childForFieldName('left');
+    // Constants are immutable by convention
+    return left?.type !== 'constant';
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/rust.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/rust.ts
new file mode 100644
index 000000000..f296756a9
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/rust.ts
@@ -0,0 +1,82 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/rust.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Rust variable extraction config.
+ *
+ * Rust has module-scoped const, static, and let declarations:
+ * - `const MAX_SIZE: usize = 100;`
+ * - `static COUNTER: AtomicUsize = AtomicUsize::new(0);`
+ * - `static mut BUFFER: Vec<u8> = Vec::new();`
+ * - `let x = 5;` (block-scoped, but included for completeness)
+ *
+ * tree-sitter-rust uses:
+ * - const_item → identifier, type
+ * - static_item → identifier, type
+ * - let_declaration → identifier, type
+ */
+
+function hasVisibilityModifier(node: SyntaxNode): boolean {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'visibility_modifier') return true;
+  }
+  return false;
+}
+
+function hasMutKeyword(node: SyntaxNode): boolean {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.text === 'mut') return true;
+  }
+  return false;
+}
+
+export const rustVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Rust,
+  constNodeTypes: ['const_item'],
+  staticNodeTypes: ['static_item'],
+  variableNodeTypes: ['let_declaration'],
+
+  extractName(node) {
+    const name = node.childForFieldName('name');
+    if (name) return name.text;
+    // Fallback: first identifier child
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === 'identifier') return child.text;
+    }
+    return undefined;
+  },
+
+  extractType(node) {
+    const typeNode = node.childForFieldName('type');
+    if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    return undefined;
+  },
+
+  extractVisibility(node): VariableVisibility {
+    return hasVisibilityModifier(node) ? 'public' : 'private';
+  },
+
+  isConst(node) {
+    return node.type === 'const_item';
+  },
+
+  isStatic(node) {
+    return node.type === 'static_item';
+  },
+
+  isMutable(node) {
+    if (node.type === 'const_item') return false;
+    if (node.type === 'static_item') return hasMutKeyword(node);
+    // let_declaration: check for mut keyword
+    if (node.type === 'let_declaration') return hasMutKeyword(node);
+    return true;
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/swift.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/swift.ts
new file mode 100644
index 000000000..018800670
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/swift.ts
@@ -0,0 +1,99 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/swift.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { extractSimpleTypeName } from '../../type-extractors/shared.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * Swift variable extraction config.
+ *
+ * Swift has top-level let/var declarations:
+ * - `let maxSize = 100`
+ * - `var counter = 0`
+ * - `public let apiKey: String = "..."`
+ *
+ * tree-sitter-swift uses:
+ * - property_declaration for both class and top-level declarations
+ */
+
+function extractSwiftVarName(node: SyntaxNode): string | undefined {
+  // property_declaration → pattern → ... → simple_identifier / identifier
+  const pattern = node.namedChildren.find((c: SyntaxNode) => c.type === 'pattern');
+  if (pattern) {
+    const ident = pattern.namedChildren.find(
+      (c: SyntaxNode) => c.type === 'simple_identifier' || c.type === 'identifier',
+    );
+    if (ident) return ident.text;
+  }
+  // Fallback: look for simple_identifier directly
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'simple_identifier') return child.text;
+  }
+  return undefined;
+}
+
+function extractSwiftVarType(node: SyntaxNode): string | undefined {
+  // Look for type_annotation child
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'type_annotation') {
+      const typeNode = child.firstNamedChild;
+      if (typeNode) return extractSimpleTypeName(typeNode) ?? typeNode.text?.trim();
+    }
+  }
+  return undefined;
+}
+
+function hasSwiftKeyword(node: SyntaxNode, keyword: string): boolean {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.text === keyword) return true;
+  }
+  return false;
+}
+
+const SWIFT_VISIBILITY = new Set(['public', 'private', 'internal', 'fileprivate', 'open']);
+
+export const swiftVariableConfig: VariableExtractionConfig = {
+  language: SupportedLanguages.Swift,
+  constNodeTypes: [],
+  staticNodeTypes: [],
+  variableNodeTypes: ['property_declaration'],
+
+  extractName: extractSwiftVarName,
+  extractType: extractSwiftVarType,
+
+  extractVisibility(node): VariableVisibility {
+    // Check modifiers for visibility keywords
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === 'modifiers') {
+        for (let j = 0; j < child.childCount; j++) {
+          const mod = child.child(j);
+          if (mod && SWIFT_VISIBILITY.has(mod.text)) return mod.text as VariableVisibility;
+        }
+      }
+    }
+    // Direct keyword check
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child && SWIFT_VISIBILITY.has(child.text)) return child.text as VariableVisibility;
+    }
+    return 'internal'; // Swift default visibility
+  },
+
+  isConst(node) {
+    return hasSwiftKeyword(node, 'let');
+  },
+
+  isStatic(node) {
+    return hasSwiftKeyword(node, 'static') || hasSwiftKeyword(node, 'class');
+  },
+
+  isMutable(node) {
+    return hasSwiftKeyword(node, 'var');
+  },
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/configs/typescript-javascript.ts b/gitnexus/src/core/ingestion/variable-extractors/configs/typescript-javascript.ts
new file mode 100644
index 000000000..0477899a2
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/configs/typescript-javascript.ts
@@ -0,0 +1,94 @@
+// gitnexus/src/core/ingestion/variable-extractors/configs/typescript-javascript.ts
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import type { VariableExtractionConfig } from '../../variable-types.js';
+import type { VariableVisibility } from '../../variable-types.js';
+import { hasKeyword, typeFromAnnotation } from '../../field-extractors/configs/helpers.js';
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+/**
+ * TypeScript/JavaScript variable extraction config.
+ *
+ * Handles module-scoped const/let/var declarations:
+ * - `export const X = ...` → public, const
+ * - `const X = ...` → private, const
+ * - `let x = ...` → private, mutable
+ * - `var x = ...` → private, mutable
+ *
+ * tree-sitter node structure:
+ *   lexical_declaration (const/let) → variable_declarator → identifier (name)
+ *   variable_declaration (var) → variable_declarator → identifier (name)
+ */
+
+function extractNameFromDecl(node: SyntaxNode): string | undefined {
+  // lexical_declaration / variable_declaration → variable_declarator → name
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'variable_declarator') {
+      const name = child.childForFieldName('name');
+      if (name?.type === 'identifier') return name.text;
+    }
+  }
+  return undefined;
+}
+
+function extractTypeFromDecl(node: SyntaxNode): string | undefined {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'variable_declarator') {
+      return typeFromAnnotation(child);
+    }
+  }
+  return undefined;
+}
+
+function extractVisFromDecl(node: SyntaxNode): VariableVisibility {
+  // Check parent for export_statement wrapper
+  const parent = node.parent;
+  if (parent?.type === 'export_statement') return 'public';
+  // Check for 'export' keyword as direct child
+  if (hasKeyword(node, 'export')) return 'public';
+  return 'private';
+}
+
+const shared: Omit<VariableExtractionConfig, 'language'> = {
+  constNodeTypes: ['lexical_declaration'],
+  staticNodeTypes: [],
+  variableNodeTypes: ['variable_declaration'],
+
+  extractName: extractNameFromDecl,
+  extractType: extractTypeFromDecl,
+  extractVisibility: extractVisFromDecl,
+
+  isConst(node) {
+    // lexical_declaration with 'const' keyword
+    if (node.type === 'lexical_declaration') {
+      return hasKeyword(node, 'const');
+    }
+    return false;
+  },
+
+  isStatic(_node) {
+    // JS/TS module-level variables are not static in the class sense
+    return false;
+  },
+
+  isMutable(node) {
+    // var or let declarations are mutable; const is not
+    if (node.type === 'variable_declaration') return true;
+    if (node.type === 'lexical_declaration') {
+      return hasKeyword(node, 'let');
+    }
+    return false;
+  },
+};
+
+export const typescriptVariableConfig: VariableExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.TypeScript,
+};
+
+export const javascriptVariableConfig: VariableExtractionConfig = {
+  ...shared,
+  language: SupportedLanguages.JavaScript,
+};
diff --git a/gitnexus/src/core/ingestion/variable-extractors/generic.ts b/gitnexus/src/core/ingestion/variable-extractors/generic.ts
new file mode 100644
index 000000000..1128805bd
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-extractors/generic.ts
@@ -0,0 +1,108 @@
+// gitnexus/src/core/ingestion/variable-extractors/generic.ts
+
+/**
+ * Generic table-driven variable extractor factory.
+ *
+ * Follows the same config+factory pattern as field-extractors/generic.ts.
+ * Define a VariableExtractionConfig per language and generate extractors
+ * from configs. The factory converts node type arrays to Sets at construction
+ * time for O(1) lookups.
+ */
+
+import type { SyntaxNode } from '../utils/ast-helpers.js';
+import type {
+  VariableExtractionConfig,
+  VariableExtractor,
+  VariableExtractorContext,
+  VariableInfo,
+  VariableScope,
+} from '../variable-types.js';
+
+/**
+ * Create a VariableExtractor from a declarative config.
+ */
+export function createVariableExtractor(config: VariableExtractionConfig): VariableExtractor {
+  const staticNodeSet = new Set(config.staticNodeTypes);
+  // Combined set for fast isVariableDeclaration checks
+  const allNodeTypes = new Set([
+    ...config.constNodeTypes,
+    ...config.staticNodeTypes,
+    ...config.variableNodeTypes,
+  ]);
+
+  function determineScope(node: SyntaxNode): VariableScope {
+    // Walk up to determine scope:
+    // - 'module': node is inside a top-level program/module/source_file container
+    // - 'block': node is inside a function, method, or block scope
+    // - 'file': fallback when no recognizable container is found (e.g., standalone snippets)
+    let current = node.parent;
+    while (current) {
+      const t = current.type;
+      // Top-level program/module nodes indicate module/file scope
+      if (
+        t === 'program' ||
+        t === 'source_file' ||
+        t === 'module' ||
+        t === 'translation_unit' ||
+        t === 'compilation_unit'
+      ) {
+        return 'module';
+      }
+      // Function/method/block boundaries indicate block scope
+      if (
+        t === 'function_declaration' ||
+        t === 'function_definition' ||
+        t === 'function_item' ||
+        t === 'method_declaration' ||
+        t === 'method_definition' ||
+        t === 'arrow_function' ||
+        t === 'function_expression' ||
+        t === 'lambda' ||
+        t === 'block' ||
+        t === 'function_body' ||
+        t === 'compound_statement'
+      ) {
+        return 'block';
+      }
+      current = current.parent;
+    }
+    return 'file';
+  }
+
+  return {
+    language: config.language,
+
+    isVariableDeclaration(node: SyntaxNode): boolean {
+      return allNodeTypes.has(node.type);
+    },
+
+    extract(node: SyntaxNode, context: VariableExtractorContext): VariableInfo | null {
+      if (!allNodeTypes.has(node.type)) return null;
+
+      const name = config.extractName(node);
+      if (!name) return null;
+
+      const type = config.extractType(node) ?? null;
+      const visibility = config.extractVisibility(node);
+      // isConst/isStatic: node type membership is a hint, but config.isConst/isStatic
+      // has final say. For languages where const and non-const share a node type
+      // (e.g., TS lexical_declaration for both const and let), config.isConst disambiguates.
+      const isConst = config.isConst(node);
+      const isStatic = staticNodeSet.has(node.type) || config.isStatic(node);
+      const isMutable = config.isMutable(node);
+      const scope = determineScope(node);
+
+      return {
+        name,
+        type,
+        visibility,
+        isConst,
+        isStatic,
+        isMutable,
+        scope,
+        sourceFile: context.filePath,
+        line: node.startPosition.row + 1,
+      };
+    },
+  };
+}
diff --git a/gitnexus/src/core/ingestion/variable-types.ts b/gitnexus/src/core/ingestion/variable-types.ts
new file mode 100644
index 000000000..a2006080b
--- /dev/null
+++ b/gitnexus/src/core/ingestion/variable-types.ts
@@ -0,0 +1,91 @@
+// gitnexus/src/core/ingestion/variable-types.ts
+
+import type { SupportedLanguages } from 'gitnexus-shared';
+import type { FieldVisibility } from './field-types.js';
+import type { SyntaxNode } from './utils/ast-helpers.js';
+
+// Reuse FieldVisibility — same set of language visibility levels
+export type VariableVisibility = FieldVisibility;
+
+/**
+ * Scope level for a variable declaration.
+ * - 'module': module/package scope (TypeScript `export const`, Go package-level)
+ * - 'file': file scope (C/C++ static file-scope, Python module-level)
+ * - 'block': block-scoped (JS `let`/`const` inside a function)
+ */
+export type VariableScope = 'module' | 'file' | 'block';
+
+/**
+ * Represents a module/file-scoped variable, constant, or static declaration.
+ */
+export interface VariableInfo {
+  /** Variable name */
+  name: string;
+  /** Declared type annotation (may be null if untyped) */
+  type: string | null;
+  /** Visibility modifier */
+  visibility: VariableVisibility;
+  /** Is this a constant (const, val, final)? */
+  isConst: boolean;
+  /** Is this a static declaration? */
+  isStatic: boolean;
+  /** Is this mutable (let, var vs const, val)? */
+  isMutable: boolean;
+  /** Scope of the declaration */
+  scope: VariableScope;
+  /** Source file path */
+  sourceFile: string;
+  /** Line number (1-based) */
+  line: number;
+}
+
+/**
+ * Context for variable extraction.
+ */
+export interface VariableExtractorContext {
+  /** Current file path */
+  filePath: string;
+  /** Language ID */
+  language: SupportedLanguages;
+}
+
+/**
+ * Variable extractor interface — extracts structured metadata from
+ * module/file-scoped variable, constant, and static declarations.
+ */
+export interface VariableExtractor {
+  /** Language this extractor handles */
+  language: SupportedLanguages;
+  /** Extract variable metadata from a declaration node.
+   *  Returns null if the node is not a recognized variable declaration. */
+  extract(node: SyntaxNode, context: VariableExtractorContext): VariableInfo | null;
+  /** Check if a node is a recognized variable declaration type. */
+  isVariableDeclaration(node: SyntaxNode): boolean;
+}
+
+/**
+ * Declarative config for building a variable extractor via the factory.
+ * Follows the same pattern as FieldExtractionConfig and MethodExtractionConfig.
+ */
+export interface VariableExtractionConfig {
+  /** Language this config applies to */
+  language: SupportedLanguages;
+  /** AST node types for const declarations (e.g., 'const_item', 'lexical_declaration') */
+  constNodeTypes: string[];
+  /** AST node types for static declarations (e.g., 'static_item') */
+  staticNodeTypes: string[];
+  /** AST node types for variable declarations (e.g., 'variable_declaration') */
+  variableNodeTypes: string[];
+  /** Extract the variable name from a declaration node */
+  extractName: (node: SyntaxNode) => string | undefined;
+  /** Extract type annotation from a declaration node */
+  extractType: (node: SyntaxNode) => string | undefined;
+  /** Extract visibility from a declaration node */
+  extractVisibility: (node: SyntaxNode) => VariableVisibility;
+  /** Check if a declaration is const/immutable */
+  isConst: (node: SyntaxNode) => boolean;
+  /** Check if a declaration is static */
+  isStatic: (node: SyntaxNode) => boolean;
+  /** Check if a declaration is mutable */
+  isMutable: (node: SyntaxNode) => boolean;
+}
diff --git a/gitnexus/src/core/ingestion/workers/parse-worker.ts b/gitnexus/src/core/ingestion/workers/parse-worker.ts
index bcafa38d2..8b56c1c16 100644
--- a/gitnexus/src/core/ingestion/workers/parse-worker.ts
+++ b/gitnexus/src/core/ingestion/workers/parse-worker.ts
@@ -53,16 +53,7 @@ import {
   CLASS_CONTAINER_TYPES,
   type SyntaxNode,
 } from '../utils/ast-helpers.js';
-import {
-  countCallArguments,
-  inferCallForm,
-  extractReceiverName,
-  extractReceiverNode,
-  extractMixedChain,
-  extractCallArgTypes,
-  type MixedChainStep,
-} from '../utils/call-analysis.js';
-import { extractParsedCallSite } from '../call-sites/extract-language-call-site.js';
+import { extractCallArgTypes, type MixedChainStep } from '../utils/call-analysis.js';
 import { buildTypeEnv } from '../type-env.js';
 import type { ConstructorBinding } from '../type-env.js';
 import { detectFrameworkFromAST } from '../framework-detection.js';
@@ -77,6 +68,7 @@ import type { NamedBinding } from '../named-bindings/types.js';
 import type { NodeLabel } from 'gitnexus-shared';
 import type { FieldInfo, FieldExtractorContext } from '../field-types.js';
 import type { MethodInfo, MethodExtractorContext } from '../method-types.js';
+import type { VariableExtractorContext } from '../variable-types.js';
 import {
   buildMethodProps,
   arityForIdFromInfo,
@@ -85,6 +77,8 @@ import {
   buildCollisionGroups,
 } from '../utils/method-props.js';
 import type { LanguageProvider } from '../language-provider.js';
+import type { ParsedFile } from 'gitnexus-shared';
+import { extractParsedFile } from '../scope-extractor-bridge.js';
 
 // ============================================================================
 // Types for serializable results
@@ -277,6 +271,14 @@ export interface ParseWorkerResult {
   constructorBindings: FileConstructorBindings[];
   /** All-scope type bindings from TypeEnv for BindingAccumulator (includes function-local). */
   fileScopeBindings: FileScopeBindings[];
+  /**
+   * Per-file `ParsedFile` artifacts from the new scope-based resolution
+   * pipeline (RFC #909 Ring 2). Empty unless the file's provider implements
+   * `emitScopeCaptures` — default for every language today, so this is
+   * additive and leaves the legacy DAG untouched. Consumed by #921's
+   * finalize-orchestrator.
+   */
+  parsedFiles: ParsedFile[];
   skippedLanguages: Record<string, number>;
   fileCount: number;
 }
@@ -719,6 +721,7 @@ const processBatch = (
     ormQueries: [],
     constructorBindings: [],
     fileScopeBindings: [],
+    parsedFiles: [],
     skippedLanguages: {},
     fileCount: 0,
   };
@@ -1404,37 +1407,53 @@ const processFileGroup = (
       continue;
     }
 
+    const provider = getProvider(language);
+
+    // RFC #909 Ring 2: produce a `ParsedFile` for the new scope-based
+    // resolution pipeline. No-op (returns undefined) for every language
+    // today — only fires once a provider implements `emitScopeCaptures`.
+    // Runs BEFORE legacy extraction and its result is independent: a
+    // failure here is caught inside `extractParsedFile` and does NOT
+    // affect the legacy DAG path that follows.
+    const parsedFile = extractParsedFile(provider, parseContent, file.path, (message) => {
+      if (parentPort) parentPort.postMessage({ type: 'warning', message });
+      else console.warn(message);
+    });
+    if (parsedFile !== undefined) result.parsedFiles.push(parsedFile);
+
     // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
     // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
     // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
     // runs. This pre-pass makes parent class information available for type resolution.
     const fileParentMap = new Map<string, string[]>();
-    for (const match of matches) {
-      const captureMap: Record<string, SyntaxNode> = {};
-      for (const c of match.captures) {
-        captureMap[c.name] = c.node;
-      }
-      if (captureMap['heritage.class'] && captureMap['heritage.extends']) {
-        const className: string = captureMap['heritage.class'].text;
-        const parentName: string = captureMap['heritage.extends'].text;
-        // Skip Go named fields (only anonymous fields are struct embedding)
-        const extendsNode = captureMap['heritage.extends'];
-        const fieldDecl = extendsNode.parent;
-        if (fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name'))
-          continue;
-        let parents = fileParentMap.get(className);
-        if (!parents) {
-          parents = [];
-          fileParentMap.set(className, parents);
+    if (provider.heritageExtractor) {
+      for (const match of matches) {
+        const captureMap: Record<string, SyntaxNode> = {};
+        for (const c of match.captures) {
+          captureMap[c.name] = c.node;
+        }
+        if (captureMap['heritage.class']) {
+          const heritageItems = provider.heritageExtractor.extract(captureMap, {
+            filePath: file.path,
+            language,
+          });
+          for (const item of heritageItems) {
+            if (item.kind === 'extends') {
+              let parents = fileParentMap.get(item.className);
+              if (!parents) {
+                parents = [];
+                fileParentMap.set(item.className, parents);
+              }
+              if (!parents.includes(item.parentName)) parents.push(item.parentName);
+            }
+          }
         }
-        if (!parents.includes(parentName)) parents.push(parentName);
       }
     }
 
     // Build per-file type environment + constructor bindings in a single AST walk.
     // Constructor bindings are verified against the SymbolTable in processCallsFromExtracted.
     const parentMap: ReadonlyMap<string, readonly string[]> = fileParentMap;
-    const provider = getProvider(language);
     const typeEnv = buildTypeEnv(tree, language, {
       parentMap,
       enclosingFunctionFinder: provider?.enclosingFunctionFinder,
@@ -1471,6 +1490,11 @@ const processFileGroup = (
     // Per-file map: decorator end-line → decorator info, for associating with definitions
     const fileDecorators = new Map<number, { name: string; arg?: string; isTool?: boolean }>();
 
+    // Track start indices of definition nodes already processed by higher-priority captures
+    // (e.g. @definition.function) to avoid duplicate nodes when @definition.const/@definition.variable
+    // patterns overlap with the same source range.
+    const processedDefinitionNodes = new Set<number>();
+
     for (const match of matches) {
       const captureMap: Record<string, SyntaxNode> = {};
       for (const c of match.captures) {
@@ -1656,109 +1680,146 @@ const processFileGroup = (
 
       // Extract call sites
       if (captureMap['call']) {
-        const callNode0 = captureMap['call'];
-        const languageSeed = extractParsedCallSite(language, callNode0);
-        if (languageSeed) {
-          if (!provider.isBuiltInName(languageSeed.calledName)) {
-            const sourceId =
-              findEnclosingFunctionId(callNode0, file.path, provider) ||
-              generateId('File', file.path);
-            const receiverName =
-              languageSeed.callForm === 'member' ? languageSeed.receiverName : undefined;
-            let receiverTypeName = receiverName
-              ? typeEnv.lookup(receiverName, callNode0)
-              : undefined;
-            // Type-as-receiver (e.g. Java `User::getName`): no TypeEnv binding for the class name
-            if (
-              receiverName !== undefined &&
-              receiverTypeName === undefined &&
-              languageSeed.callForm === 'member' &&
-              (language === SupportedLanguages.Java ||
-                language === SupportedLanguages.CSharp ||
-                language === SupportedLanguages.Kotlin)
-            ) {
-              const c0 = receiverName.charCodeAt(0);
-              if (c0 >= 65 && c0 <= 90) receiverTypeName = receiverName;
-            }
-            result.calls.push({
-              filePath: file.path,
-              calledName: languageSeed.calledName,
-              sourceId,
-              callForm: languageSeed.callForm,
-              ...(receiverName !== undefined ? { receiverName } : {}),
-              ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
-            });
-          }
-          continue;
-        }
-
+        const callNode = captureMap['call'];
         const callNameNode = captureMap['call.name'];
-        if (callNameNode) {
-          const calledName = callNameNode.text;
+        const callExtractor = provider.callExtractor;
 
-          // Dispatch: route language-specific calls (heritage, properties, imports)
-          const routed = callRouter?.(calledName, captureMap['call']);
-          if (routed) {
-            if (routed.kind === 'skip') continue;
-
-            if (routed.kind === 'import') {
-              result.imports.push({
-                filePath: file.path,
-                rawImportPath: routed.importPath,
-                language,
-              });
-              continue;
-            }
-
-            if (routed.kind === 'heritage') {
-              for (const item of routed.items) {
-                result.heritage.push({
-                  filePath: file.path,
-                  className: item.enclosingClass,
-                  parentName: item.mixinName,
-                  kind: item.heritageKind,
-                });
+        if (callExtractor) {
+          // ── Path 1: Language-specific call site (bypasses routing) ────
+          // Try language-specific extraction (e.g. Java `::` method references)
+          // without callNameNode.  If successful, skip routing and the generic
+          // path entirely.
+          const langCallSite = callExtractor.extract(callNode, undefined);
+          if (langCallSite) {
+            if (!provider.isBuiltInName(langCallSite.calledName)) {
+              const sourceId =
+                findEnclosingFunctionId(callNode, file.path, provider) ||
+                generateId('File', file.path);
+              const receiverName =
+                langCallSite.callForm === 'member' ? langCallSite.receiverName : undefined;
+              let receiverTypeName = receiverName
+                ? typeEnv.lookup(receiverName, callNode)
+                : undefined;
+              // Type-as-receiver heuristic (e.g. Java `User::getName`)
+              if (
+                langCallSite.typeAsReceiverHeuristic &&
+                receiverName !== undefined &&
+                receiverTypeName === undefined &&
+                langCallSite.callForm === 'member'
+              ) {
+                const c0 = receiverName.charCodeAt(0);
+                if (c0 >= 65 && c0 <= 90) receiverTypeName = receiverName;
               }
-              continue;
+              result.calls.push({
+                filePath: file.path,
+                calledName: langCallSite.calledName,
+                sourceId,
+                callForm: langCallSite.callForm,
+                ...(receiverName !== undefined ? { receiverName } : {}),
+                ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
+              });
             }
+            continue;
+          }
 
-            if (routed.kind === 'properties') {
-              const propEnclosingInfo = cachedFindEnclosingClassInfo(
-                captureMap['call'],
-                file.path,
-                provider.resolveEnclosingOwner,
+          // ── Path 2: Generic extraction via @call.name ────────────────
+          if (callNameNode) {
+            const calledName = callNameNode.text;
+
+            // Check heritage extractor for call-based heritage (e.g., Ruby include/extend/prepend)
+            if (provider.heritageExtractor?.extractFromCall) {
+              const heritageItems = provider.heritageExtractor.extractFromCall(
+                calledName,
+                callNode,
+                { filePath: file.path, language },
               );
-              const propEnclosingClassId = propEnclosingInfo?.classId ?? null;
-              // Enrich routed properties with FieldExtractor metadata
-              let routedFieldMap: Map<string, FieldInfo> | undefined;
-              if (provider.fieldExtractor && typeEnv) {
-                const classNode = findEnclosingClassNode(captureMap['call']);
-                if (classNode) {
-                  routedFieldMap = getFieldInfo(classNode, provider, {
-                    typeEnv,
-                    symbolTable: NOOP_SYMBOL_TABLE,
+              if (heritageItems !== null) {
+                for (const item of heritageItems) {
+                  result.heritage.push({
                     filePath: file.path,
-                    language,
+                    className: item.className,
+                    parentName: item.parentName,
+                    kind: item.kind,
                   });
                 }
+                continue;
               }
-              for (const item of routed.items) {
-                const routedFieldInfo = routedFieldMap?.get(item.propName);
-                const propQualifiedName = propEnclosingInfo
-                  ? `${propEnclosingInfo.className}.${item.propName}`
-                  : item.propName;
-                const nodeId = generateId('Property', `${file.path}:${propQualifiedName}`);
-                result.nodes.push({
-                  id: nodeId,
-                  label: 'Property',
-                  properties: {
-                    name: item.propName,
+            }
+
+            // Dispatch: route language-specific calls (properties, imports)
+            // Heritage routing is handled by heritageExtractor.extractFromCall above.
+            const routed = callRouter?.(calledName, captureMap['call']);
+            if (routed) {
+              if (routed.kind === 'skip') continue;
+
+              if (routed.kind === 'import') {
+                result.imports.push({
+                  filePath: file.path,
+                  rawImportPath: routed.importPath,
+                  language,
+                });
+                continue;
+              }
+
+              if (routed.kind === 'properties') {
+                const propEnclosingInfo = cachedFindEnclosingClassInfo(
+                  captureMap['call'],
+                  file.path,
+                  provider.resolveEnclosingOwner,
+                );
+                const propEnclosingClassId = propEnclosingInfo?.classId ?? null;
+                // Enrich routed properties with FieldExtractor metadata
+                let routedFieldMap: Map<string, FieldInfo> | undefined;
+                if (provider.fieldExtractor && typeEnv) {
+                  const classNode = findEnclosingClassNode(captureMap['call']);
+                  if (classNode) {
+                    routedFieldMap = getFieldInfo(classNode, provider, {
+                      typeEnv,
+                      symbolTable: NOOP_SYMBOL_TABLE,
+                      filePath: file.path,
+                      language,
+                    });
+                  }
+                }
+                for (const item of routed.items) {
+                  const routedFieldInfo = routedFieldMap?.get(item.propName);
+                  const propQualifiedName = propEnclosingInfo
+                    ? `${propEnclosingInfo.className}.${item.propName}`
+                    : item.propName;
+                  const nodeId = generateId('Property', `${file.path}:${propQualifiedName}`);
+                  result.nodes.push({
+                    id: nodeId,
+                    label: 'Property',
+                    properties: {
+                      name: item.propName,
+                      filePath: file.path,
+                      startLine: item.startLine,
+                      endLine: item.endLine,
+                      language,
+                      isExported: true,
+                      description: item.accessorType,
+                      ...(item.declaredType
+                        ? { declaredType: item.declaredType }
+                        : routedFieldInfo?.type
+                          ? { declaredType: routedFieldInfo.type }
+                          : {}),
+                      ...(routedFieldInfo?.visibility !== undefined
+                        ? { visibility: routedFieldInfo.visibility }
+                        : {}),
+                      ...(routedFieldInfo?.isStatic !== undefined
+                        ? { isStatic: routedFieldInfo.isStatic }
+                        : {}),
+                      ...(routedFieldInfo?.isReadonly !== undefined
+                        ? { isReadonly: routedFieldInfo.isReadonly }
+                        : {}),
+                    },
+                  });
+                  result.symbols.push({
                     filePath: file.path,
-                    startLine: item.startLine,
-                    endLine: item.endLine,
-                    language,
-                    isExported: true,
-                    description: item.accessorType,
+                    name: item.propName,
+                    nodeId,
+                    type: 'Property',
+                    ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
                     ...(item.declaredType
                       ? { declaredType: item.declaredType }
                       : routedFieldInfo?.type
@@ -1773,151 +1834,109 @@ const processFileGroup = (
                     ...(routedFieldInfo?.isReadonly !== undefined
                       ? { isReadonly: routedFieldInfo.isReadonly }
                       : {}),
-                  },
-                });
-                result.symbols.push({
-                  filePath: file.path,
-                  name: item.propName,
-                  nodeId,
-                  type: 'Property',
-                  ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}),
-                  ...(item.declaredType
-                    ? { declaredType: item.declaredType }
-                    : routedFieldInfo?.type
-                      ? { declaredType: routedFieldInfo.type }
-                      : {}),
-                  ...(routedFieldInfo?.visibility !== undefined
-                    ? { visibility: routedFieldInfo.visibility }
-                    : {}),
-                  ...(routedFieldInfo?.isStatic !== undefined
-                    ? { isStatic: routedFieldInfo.isStatic }
-                    : {}),
-                  ...(routedFieldInfo?.isReadonly !== undefined
-                    ? { isReadonly: routedFieldInfo.isReadonly }
-                    : {}),
-                });
-                const fileId = generateId('File', file.path);
-                const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
-                result.relationships.push({
-                  id: relId,
-                  sourceId: fileId,
-                  targetId: nodeId,
-                  type: 'DEFINES',
-                  confidence: 1.0,
-                  reason: '',
-                });
-                if (propEnclosingClassId) {
+                  });
+                  const fileId = generateId('File', file.path);
+                  const relId = generateId('DEFINES', `${fileId}->${nodeId}`);
                   result.relationships.push({
-                    id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
-                    sourceId: propEnclosingClassId,
+                    id: relId,
+                    sourceId: fileId,
                     targetId: nodeId,
-                    type: 'HAS_PROPERTY',
+                    type: 'DEFINES',
                     confidence: 1.0,
                     reason: '',
                   });
-                }
-              }
-              continue;
-            }
-
-            // kind === 'call' — fall through to normal call processing below
-          }
-
-          if (!provider.isBuiltInName(calledName)) {
-            const callNode = captureMap['call'];
-            const sourceId =
-              findEnclosingFunctionId(callNode, file.path, provider) ||
-              generateId('File', file.path);
-            const callForm = inferCallForm(callNode, callNameNode);
-            let receiverName =
-              callForm === 'member' ? extractReceiverName(callNameNode) : undefined;
-            let receiverTypeName = receiverName
-              ? typeEnv.lookup(receiverName, callNode)
-              : undefined;
-            let receiverMixedChain: MixedChainStep[] | undefined;
-
-            // When the receiver is a complex expression (call chain, field chain, or mixed),
-            // extractReceiverName returns undefined. Walk the receiver node to build a unified
-            // mixed chain for deferred resolution in processCallsFromExtracted.
-            if (callForm === 'member' && receiverName === undefined && !receiverTypeName) {
-              const receiverNode = extractReceiverNode(callNameNode);
-              if (receiverNode) {
-                const extracted = extractMixedChain(receiverNode);
-                if (extracted && extracted.chain.length > 0) {
-                  receiverMixedChain = extracted.chain;
-                  receiverName = extracted.baseReceiverName;
-                  // Try the type environment immediately for the base receiver
-                  // (covers explicitly-typed locals and annotated parameters).
-                  if (receiverName) {
-                    receiverTypeName = typeEnv.lookup(receiverName, callNode);
+                  if (propEnclosingClassId) {
+                    result.relationships.push({
+                      id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`),
+                      sourceId: propEnclosingClassId,
+                      targetId: nodeId,
+                      type: 'HAS_PROPERTY',
+                      confidence: 1.0,
+                      reason: '',
+                    });
                   }
                 }
+                continue;
               }
+
+              // kind === 'call' — fall through to normal call processing below
             }
 
-            const inferLiteralType = provider.typeConfig?.inferLiteralType;
-            const argCountForOverloadHints = countCallArguments(callNode);
-            // Skip when no arg list / zero args: nothing to infer for overload typing; saves AST walks + payload size.
-            const argTypes =
-              inferLiteralType &&
-              argCountForOverloadHints !== undefined &&
-              argCountForOverloadHints > 0
-                ? extractCallArgTypes(callNode, inferLiteralType, (varName, cn) =>
-                    typeEnv.lookup(varName, cn),
-                  )
-                : undefined;
+            if (!provider.isBuiltInName(calledName)) {
+              const callSite = callExtractor.extract(callNode, callNameNode);
+              if (callSite) {
+                const sourceId =
+                  findEnclosingFunctionId(callNode, file.path, provider) ||
+                  generateId('File', file.path);
+                let receiverTypeName = callSite.receiverName
+                  ? typeEnv.lookup(callSite.receiverName, callNode)
+                  : undefined;
 
-            result.calls.push({
-              filePath: file.path,
-              calledName,
-              sourceId,
-              argCount: countCallArguments(callNode),
-              ...(callForm !== undefined ? { callForm } : {}),
-              ...(receiverName !== undefined ? { receiverName } : {}),
-              ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
-              ...(receiverMixedChain !== undefined ? { receiverMixedChain } : {}),
-              ...(argTypes !== undefined ? { argTypes } : {}),
-            });
+                // Type-as-receiver heuristic
+                if (
+                  callSite.typeAsReceiverHeuristic &&
+                  callSite.receiverName !== undefined &&
+                  receiverTypeName === undefined &&
+                  callSite.callForm === 'member'
+                ) {
+                  const c0 = callSite.receiverName.charCodeAt(0);
+                  if (c0 >= 65 && c0 <= 90) receiverTypeName = callSite.receiverName;
+                }
+
+                const inferLiteralType = provider.typeConfig?.inferLiteralType;
+                // Skip when no arg list / zero args: nothing to infer for overload typing
+                const argTypes =
+                  inferLiteralType && callSite.argCount !== undefined && callSite.argCount > 0
+                    ? extractCallArgTypes(callNode, inferLiteralType, (varName, cn) =>
+                        typeEnv.lookup(varName, cn),
+                      )
+                    : undefined;
+
+                result.calls.push({
+                  filePath: file.path,
+                  calledName: callSite.calledName,
+                  sourceId,
+                  ...(callSite.argCount !== undefined ? { argCount: callSite.argCount } : {}),
+                  ...(callSite.callForm !== undefined ? { callForm: callSite.callForm } : {}),
+                  ...(callSite.receiverName !== undefined
+                    ? { receiverName: callSite.receiverName }
+                    : {}),
+                  ...(receiverTypeName !== undefined ? { receiverTypeName } : {}),
+                  ...(callSite.receiverMixedChain !== undefined
+                    ? { receiverMixedChain: callSite.receiverMixedChain }
+                    : {}),
+                  ...(argTypes !== undefined ? { argTypes } : {}),
+                });
+              }
+            }
           }
         }
         continue;
       }
 
-      // Extract heritage (extends/implements)
+      // Extract heritage (extends/implements) via provider heritage extractor
       if (captureMap['heritage.class']) {
-        if (captureMap['heritage.extends']) {
-          // Go struct embedding: the query matches ALL field_declarations with
-          // type_identifier, but only anonymous fields (no name) are embedded.
-          // Named fields like `Breed string` also match — skip them.
-          const extendsNode = captureMap['heritage.extends'];
-          const fieldDecl = extendsNode.parent;
-          const isNamedField =
-            fieldDecl?.type === 'field_declaration' && fieldDecl.childForFieldName('name');
-          if (!isNamedField) {
+        if (provider.heritageExtractor) {
+          const heritageItems = provider.heritageExtractor.extract(captureMap, {
+            filePath: file.path,
+            language,
+          });
+          for (const item of heritageItems) {
             result.heritage.push({
               filePath: file.path,
-              className: captureMap['heritage.class'].text,
-              parentName: captureMap['heritage.extends'].text,
-              kind: 'extends',
+              className: item.className,
+              parentName: item.parentName,
+              kind: item.kind,
             });
           }
+          // When the extractor consumes the match, skip symbol processing below.
+          if (heritageItems.length > 0) {
+            continue;
+          }
         }
-        if (captureMap['heritage.implements']) {
-          result.heritage.push({
-            filePath: file.path,
-            className: captureMap['heritage.class'].text,
-            parentName: captureMap['heritage.implements'].text,
-            kind: 'implements',
-          });
-        }
-        if (captureMap['heritage.trait']) {
-          result.heritage.push({
-            filePath: file.path,
-            className: captureMap['heritage.class'].text,
-            parentName: captureMap['heritage.trait'].text,
-            kind: 'trait-impl',
-          });
-        }
+        // Fallback: the extractor returned [] (or is absent), but the match still
+        // carries a heritage-specific capture. The match belongs to a heritage
+        // clause and must not fall through to generic symbol processing.
         if (
           captureMap['heritage.extends'] ||
           captureMap['heritage.implements'] ||
@@ -1940,6 +1959,21 @@ const processFileGroup = (
             })
           : null;
       const nodeLabel = extractedClassSymbol?.type ?? defaultNodeLabel;
+
+      // Dedup: variable captures (Const/Static/Variable) may overlap with higher-priority
+      // captures (e.g. `const fn = () => {}` matches both @definition.function and @definition.const).
+      // Skip variable captures whose definition node was already processed.
+      if (
+        (nodeLabel === 'Const' || nodeLabel === 'Static' || nodeLabel === 'Variable') &&
+        definitionNode &&
+        processedDefinitionNodes.has(definitionNode.startIndex)
+      ) {
+        continue;
+      }
+      if (definitionNode) {
+        processedDefinitionNodes.add(definitionNode.startIndex);
+      }
+
       // Synthesize name for constructors without explicit @name capture (e.g. Swift init)
       if (!nameNode && nodeLabel !== 'Constructor' && !extractedClassSymbol) continue;
       const nodeName = extractedClassSymbol?.name ?? (nameNode ? nameNode.text : 'init');
@@ -2122,6 +2156,27 @@ const processFileGroup = (
         }
       }
 
+      // Variable/Const/Static metadata extraction via VariableExtractor
+      if (
+        (nodeLabel === 'Const' || nodeLabel === 'Static' || nodeLabel === 'Variable') &&
+        definitionNode &&
+        provider.variableExtractor
+      ) {
+        const varCtx: VariableExtractorContext = {
+          filePath: file.path,
+          language,
+        };
+        const varInfo = provider.variableExtractor.extract(definitionNode, varCtx);
+        if (varInfo) {
+          if (varInfo.type) declaredType = varInfo.type;
+          methodProps.visibility = varInfo.visibility;
+          methodProps.isStatic = varInfo.isStatic;
+          methodProps.isConst = varInfo.isConst;
+          methodProps.isMutable = varInfo.isMutable;
+          methodProps.scope = varInfo.scope;
+        }
+      }
+
       result.nodes.push({
         id: nodeId,
         label: nodeLabel,
@@ -2251,6 +2306,7 @@ let accumulated: ParseWorkerResult = {
   ormQueries: [],
   constructorBindings: [],
   fileScopeBindings: [],
+  parsedFiles: [],
   skippedLanguages: {},
   fileCount: 0,
 };
@@ -2278,6 +2334,7 @@ const mergeResult = (target: ParseWorkerResult, src: ParseWorkerResult) => {
   appendAll(target.ormQueries, src.ormQueries);
   appendAll(target.constructorBindings, src.constructorBindings);
   appendAll(target.fileScopeBindings, src.fileScopeBindings);
+  appendAll(target.parsedFiles, src.parsedFiles);
   for (const [lang, count] of Object.entries(src.skippedLanguages)) {
     target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
   }
@@ -2329,6 +2386,7 @@ parentPort!.on('message', (msg: WorkerIncomingMessage) => {
         ormQueries: [],
         constructorBindings: [],
         fileScopeBindings: [],
+        parsedFiles: [],
         skippedLanguages: {},
         fileCount: 0,
       };
diff --git a/gitnexus/src/core/ingestion/workers/worker-pool.ts b/gitnexus/src/core/ingestion/workers/worker-pool.ts
index bc23f0ea4..9fa77ef39 100644
--- a/gitnexus/src/core/ingestion/workers/worker-pool.ts
+++ b/gitnexus/src/core/ingestion/workers/worker-pool.ts
@@ -24,6 +24,7 @@ export interface WorkerPool {
 /** Message shapes sent back by worker threads. */
 type WorkerOutgoingMessage =
   | { type: 'progress'; filesProcessed: number }
+  | { type: 'warning'; message: string }
   | { type: 'sub-batch-done' }
   | { type: 'error'; error: string }
   | { type: 'result'; data: unknown };
@@ -120,6 +121,8 @@ export const createWorkerPool = (workerUrl: URL, poolSize?: number): WorkerPool
               const total = workerProgress.reduce((a, b) => a + b, 0);
               onProgress(total);
             }
+          } else if (msg.type === 'warning') {
+            console.warn(msg.message);
           } else if (msg.type === 'sub-batch-done') {
             sendNextSubBatch();
           } else if (msg.type === 'error') {
diff --git a/gitnexus/src/core/lbug/csv-generator.ts b/gitnexus/src/core/lbug/csv-generator.ts
index 63a1bb947..616a00cac 100644
--- a/gitnexus/src/core/lbug/csv-generator.ts
+++ b/gitnexus/src/core/lbug/csv-generator.ts
@@ -292,6 +292,7 @@ export const streamAllCSVsToDisk = async (
     'TypeAlias',
     'Const',
     'Static',
+    'Variable',
     'Property',
     'Record',
     'Delegate',
diff --git a/gitnexus/src/core/lbug/lbug-adapter.ts b/gitnexus/src/core/lbug/lbug-adapter.ts
index b5cd3e2ad..f019960c5 100644
--- a/gitnexus/src/core/lbug/lbug-adapter.ts
+++ b/gitnexus/src/core/lbug/lbug-adapter.ts
@@ -15,6 +15,7 @@ import {
   NodeTableName,
 } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
+import type { CachedEmbedding } from '../embeddings/types.js';
 
 // ---------------------------------------------------------------------------
 // Relationship CSV splitting — extracted for testability (PR #818)
@@ -881,33 +882,47 @@ export const getLbugStats = async (): Promise<{ nodes: number; edges: number }>
  * Load cached embeddings from LadybugDB before a rebuild.
  * Returns all embedding vectors so they can be re-inserted after the graph is reloaded,
  * avoiding expensive re-embedding of unchanged nodes.
+ *
+ * Detects old schema (no chunkIndex column) and returns empty cache to trigger rebuild.
  */
 export const loadCachedEmbeddings = async (): Promise<{
   embeddingNodeIds: Set<string>;
-  embeddings: Array<{ nodeId: string; embedding: number[]; contentHash?: string }>;
+  embeddings: CachedEmbedding[];
 }> => {
   if (!conn) {
     return { embeddingNodeIds: new Set(), embeddings: [] };
   }
 
   const embeddingNodeIds = new Set<string>();
-  const embeddings: Array<{ nodeId: string; embedding: number[]; contentHash?: string }> = [];
+  const embeddings: CachedEmbedding[] = [];
   try {
-    // Try to read contentHash alongside the embedding
+    // Schema migration detection: query with new columns to verify schema version.
+    // Old schema only had (nodeId, embedding); new schema adds (id, chunkIndex, startLine, endLine, contentHash).
+    // If the query fails (column missing), we return empty cache to force a full rebuild.
+    try {
+      const check = await conn.query(
+        `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex LIMIT 1`,
+      );
+      const checkResult = Array.isArray(check) ? check[0] : check;
+      await checkResult.getAll();
+    } catch {
+      return { embeddingNodeIds: new Set(), embeddings: [] };
+    }
+
+    // Try to read contentHash alongside chunk columns
     let rows: any;
     let hasContentHash = true;
     try {
       rows = await conn.query(
-        `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding, e.contentHash AS contentHash`,
+        `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding, e.contentHash AS contentHash`,
       );
     } catch (err: any) {
-      // Only fall back for missing-column errors (legacy DBs without contentHash).
-      // Rethrow transient / connection errors so callers see them.
+      // Fallback for legacy DBs without contentHash column
       const msg = err?.message ?? '';
       if (isMissingColumnOrTableError(msg)) {
         hasContentHash = false;
         rows = await conn.query(
-          `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.embedding AS embedding`,
+          `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding`,
         );
       } else {
         throw err;
@@ -918,14 +933,17 @@ export const loadCachedEmbeddings = async (): Promise<{
       const nodeId = String(row.nodeId ?? row[0] ?? '');
       if (!nodeId) continue;
       embeddingNodeIds.add(nodeId);
-      const embedding = row.embedding ?? row[1];
+      const embedding = row.embedding ?? row[4];
       if (embedding) {
         embeddings.push({
           nodeId,
+          chunkIndex: Number(row.chunkIndex ?? row[1] ?? 0),
+          startLine: Number(row.startLine ?? row[2] ?? 0),
+          endLine: Number(row.endLine ?? row[3] ?? 0),
           embedding: Array.isArray(embedding)
             ? embedding.map(Number)
             : Array.from(embedding as any).map(Number),
-          contentHash: hasContentHash ? (row.contentHash ?? row[2] ?? undefined) : undefined,
+          contentHash: hasContentHash ? (row.contentHash ?? row[5] ?? undefined) : undefined,
         });
       }
     }
@@ -949,33 +967,43 @@ export const fetchExistingEmbeddingHashes = async (
 ): Promise<Map<string, string> | undefined> => {
   try {
     const rows = await execQuery(
-      `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.contentHash AS contentHash`,
+      `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.contentHash AS contentHash`,
     );
     if (!rows || rows.length === 0) return undefined;
     const map = new Map<string, string>();
     for (const r of rows) {
       const nodeId = r.nodeId ?? r[0];
-      const hash = r.contentHash ?? r[1] ?? STALE_HASH_SENTINEL;
+      const chunkIndex = r.chunkIndex ?? r[1];
+      const startLine = r.startLine ?? r[2];
+      const endLine = r.endLine ?? r[3];
+      const hash = r.contentHash ?? r[4] ?? STALE_HASH_SENTINEL;
       if (nodeId) {
-        // Empty/null contentHash means legacy row — treat as stale so it gets re-embedded
-        map.set(nodeId, hash || STALE_HASH_SENTINEL);
+        const hasChunkMetadata =
+          chunkIndex !== undefined &&
+          chunkIndex !== null &&
+          startLine !== undefined &&
+          startLine !== null &&
+          endLine !== undefined &&
+          endLine !== null;
+        // Empty/null contentHash or missing chunk metadata means legacy row — treat as stale.
+        map.set(nodeId, hasChunkMetadata && hash ? hash : STALE_HASH_SENTINEL);
       }
     }
     return map;
   } catch (err: any) {
     const msg = err?.message ?? '';
     if (isMissingColumnOrTableError(msg)) {
-      // Column or table missing — try fallback without contentHash
+      // Legacy rows missing chunk-aware columns — treat every row as stale.
       try {
         const rows = await execQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId`);
         if (!rows || rows.length === 0) return undefined;
         const map = new Map<string, string>();
         for (const r of rows) {
           const nodeId = r.nodeId ?? r[0];
-          if (nodeId) map.set(nodeId, STALE_HASH_SENTINEL); // no contentHash — treat as stale
+          if (nodeId) map.set(nodeId, STALE_HASH_SENTINEL);
         }
         console.log(
-          `[embed] ${map.size} nodes in legacy DB (no contentHash) — all treated as stale`,
+          `[embed] ${map.size} nodes in legacy DB (missing chunk-aware columns) — all treated as stale`,
         );
         return map;
       } catch (fallbackErr: any) {
diff --git a/gitnexus/src/core/lbug/schema.ts b/gitnexus/src/core/lbug/schema.ts
index c0ba10d4d..5579036f1 100644
--- a/gitnexus/src/core/lbug/schema.ts
+++ b/gitnexus/src/core/lbug/schema.ts
@@ -166,6 +166,7 @@ export const IMPL_SCHEMA = CODE_ELEMENT_BASE('Impl');
 export const TYPE_ALIAS_SCHEMA = CODE_ELEMENT_BASE('TypeAlias');
 export const CONST_SCHEMA = CODE_ELEMENT_BASE('Const');
 export const STATIC_SCHEMA = CODE_ELEMENT_BASE('Static');
+export const VARIABLE_SCHEMA = CODE_ELEMENT_BASE('Variable');
 export const PROPERTY_SCHEMA = CODE_ELEMENT_BASE('Property');
 export const RECORD_SCHEMA = CODE_ELEMENT_BASE('Record');
 export const DELEGATE_SCHEMA = CODE_ELEMENT_BASE('Delegate');
@@ -234,6 +235,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM File TO \`TypeAlias\`,
   FROM File TO \`Const\`,
   FROM File TO \`Static\`,
+  FROM File TO \`Variable\`,
   FROM File TO \`Property\`,
   FROM File TO \`Record\`,
   FROM File TO \`Delegate\`,
@@ -365,6 +367,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`TypeAlias\` TO Class,
   FROM \`Const\` TO Community,
   FROM \`Static\` TO Community,
+  FROM \`Variable\` TO Community,
   FROM \`Property\` TO Community,
   FROM \`Record\` TO Method,
   FROM \`Record\` TO \`Constructor\`,
@@ -408,6 +411,7 @@ CREATE REL TABLE ${REL_TABLE_NAME} (
   FROM \`Trait\` TO Process,
   FROM \`Const\` TO Process,
   FROM \`Static\` TO Process,
+  FROM \`Variable\` TO Process,
   FROM \`Property\` TO Process,
   FROM \`Record\` TO Process,
   FROM \`Delegate\` TO Process,
@@ -447,10 +451,14 @@ export const STALE_HASH_SENTINEL = '';
 
 export const EMBEDDING_SCHEMA = `
 CREATE NODE TABLE ${EMBEDDING_TABLE_NAME} (
+  id STRING,
   nodeId STRING,
+  chunkIndex INT32,
+  startLine INT64,
+  endLine INT64,
   embedding FLOAT[${EMBEDDING_DIMS}],
   contentHash STRING,
-  PRIMARY KEY (nodeId)
+  PRIMARY KEY (id)
 )`;
 
 /**
@@ -488,6 +496,7 @@ export const NODE_SCHEMA_QUERIES = [
   TYPE_ALIAS_SCHEMA,
   CONST_SCHEMA,
   STATIC_SCHEMA,
+  VARIABLE_SCHEMA,
   PROPERTY_SCHEMA,
   RECORD_SCHEMA,
   DELEGATE_SCHEMA,
diff --git a/gitnexus/src/core/run-analyze.ts b/gitnexus/src/core/run-analyze.ts
index 7c72fb592..5c2191003 100644
--- a/gitnexus/src/core/run-analyze.ts
+++ b/gitnexus/src/core/run-analyze.ts
@@ -30,7 +30,8 @@ import {
   registerRepo,
   cleanupOldKuzuFiles,
 } from '../storage/repo-manager.js';
-import { getCurrentCommit, hasGitDir } from '../storage/git.js';
+import { getCurrentCommit, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import type { CachedEmbedding } from './embeddings/types.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './lbug/schema.js';
 import { STALE_HASH_SENTINEL } from './lbug/schema.js';
@@ -45,6 +46,12 @@ export interface AnalyzeCallbacks {
 }
 
 export interface AnalyzeOptions {
+  /**
+   * Force a full re-index of the pipeline. Callers may OR this with
+   * other flags that imply re-analysis (e.g. `--skills`), so the value
+   * here is the PIPELINE-force signal, NOT the registry-collision
+   * bypass. See `allowDuplicateName` below.
+   */
   force?: boolean;
   embeddings?: boolean;
   skipGit?: boolean;
@@ -52,6 +59,21 @@ export interface AnalyzeOptions {
   skipAgentsMd?: boolean;
   /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */
   noStats?: boolean;
+  /**
+   * User-provided alias for the registry `name` (#829). When set,
+   * forwarded to `registerRepo` so the indexed repo is stored under
+   * this alias instead of the path-derived basename.
+   */
+  registryName?: string;
+  /**
+   * Bypass the `RegistryNameCollisionError` guard and allow two paths
+   * to register under the same `name` (#829). Controlled by the
+   * dedicated `--allow-duplicate-name` CLI flag, intentionally
+   * independent from `--force` — users who hit the collision guard
+   * should be able to accept the duplicate without paying the cost
+   * of a pipeline re-index.
+   */
+  allowDuplicateName?: boolean;
 }
 
 export interface AnalyzeResult {
@@ -130,7 +152,7 @@ export async function runFullAnalysis(
     // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
     if (currentCommit !== '') {
       return {
-        repoName: path.basename(repoPath),
+        repoName: options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath),
         repoPath,
         stats: existingMeta.stats ?? {},
         alreadyUpToDate: true,
@@ -140,7 +162,7 @@ export async function runFullAnalysis(
 
   // ── Cache embeddings from existing index before rebuild ────────────
   let cachedEmbeddingNodeIds = new Set<string>();
-  let cachedEmbeddings: Array<{ nodeId: string; embedding: number[]; contentHash?: string }> = [];
+  let cachedEmbeddings: CachedEmbedding[] = [];
 
   if (options.embeddings && existingMeta && !options.force) {
     try {
@@ -218,19 +240,14 @@ export async function runFullAnalysis(
         cachedEmbeddingNodeIds = new Set();
       } else {
         progress('embeddings', 88, `Restoring ${cachedEmbeddings.length} cached embeddings...`);
+        const { batchInsertEmbeddings: batchInsert } =
+          await import('./embeddings/embedding-pipeline.js');
         const EMBED_BATCH = 200;
         for (let i = 0; i < cachedEmbeddings.length; i += EMBED_BATCH) {
           const batch = cachedEmbeddings.slice(i, i + EMBED_BATCH);
-          const paramsList = batch.map((e) => ({
-            nodeId: e.nodeId,
-            embedding: e.embedding,
-            contentHash: e.contentHash ?? STALE_HASH_SENTINEL,
-          }));
+
           try {
-            await executeWithReusedStatement(
-              `MERGE (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) SET e.embedding = $embedding, e.contentHash = $contentHash`,
-              paramsList,
-            );
+            await batchInsert(executeWithReusedStatement, batch);
           } catch {
             /* some may fail if node was removed, that's fine */
           }
@@ -265,6 +282,10 @@ export async function runFullAnalysis(
           existingEmbeddings.set(e.nodeId, e.contentHash ?? STALE_HASH_SENTINEL);
         }
       }
+
+      const { readServerMapping } = await import('./embeddings/server-mapping.js');
+      const projectName = path.basename(repoPath);
+      const serverName = await readServerMapping(projectName);
       await runEmbeddingPipeline(
         executeQuery,
         executeWithReusedStatement,
@@ -279,6 +300,8 @@ export async function runFullAnalysis(
           progress('embeddings', scaled, label);
         },
         {},
+        cachedEmbeddingNodeIds.size > 0 ? cachedEmbeddingNodeIds : undefined,
+        { repoName: projectName, serverName },
         existingEmbeddings,
       );
     }
@@ -311,15 +334,25 @@ export async function runFullAnalysis(
       },
     };
     await saveMeta(storagePath, meta);
-    await registerRepo(repoPath, meta);
+    // Forward the --name alias and the registry-collision bypass bit.
+    // `allowDuplicateName` is its own concern — independent from the
+    // pipeline `force` above. The CLI maps it from
+    // `--allow-duplicate-name` only; `--force` and `--skills` both
+    // trigger pipeline re-run but never bypass the registry guard.
+    // The returned name is the one actually written to the registry
+    // (after applying the precedence chain in registerRepo) — reuse it
+    // so AGENTS.md / skill files reference the same name MCP clients
+    // will look up (#979).
+    const projectName = await registerRepo(repoPath, meta, {
+      name: options.registryName,
+      allowDuplicateName: options.allowDuplicateName,
+    });
 
     // Only attempt to update .gitignore when a .git directory is present.
     if (hasGitDir(repoPath)) {
       await addToGitignore(repoPath);
     }
 
-    const projectName = path.basename(repoPath);
-
     // ── Generate AI context files (best-effort) ───────────────────────
     let aggregatedClusterCount = 0;
     if (pipelineResult.communityResult?.communities) {
diff --git a/gitnexus/src/core/search/phase-timer.ts b/gitnexus/src/core/search/phase-timer.ts
new file mode 100644
index 000000000..3a6fd745a
--- /dev/null
+++ b/gitnexus/src/core/search/phase-timer.ts
@@ -0,0 +1,108 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export class PhaseTimer {
+  private phases: Map<string, number> = new Map();
+  private current: string | null = null;
+  private t0 = 0;
+
+  /** Start a new phase. Implicitly stops the previous one, if any. */
+  start(phase: string): void {
+    this.stop();
+    this.current = phase;
+    this.t0 = performance.now();
+  }
+
+  /** Stop the current phase. No-op if no phase is active. */
+  stop(): void {
+    if (this.current !== null) {
+      const elapsed = performance.now() - this.t0;
+      this.phases.set(this.current, (this.phases.get(this.current) ?? 0) + elapsed);
+      this.current = null;
+    }
+  }
+
+  /**
+   * Record a pre-measured duration without touching the active phase.
+   * Use for concurrent operations inside `Promise.all` where
+   * `start`/`stop` would step on each other, or for durations imported
+   * from sub-systems. Additive across repeated calls with the same
+   * phase name. Ignores negative / non-finite inputs.
+   */
+  mark(phase: string, durationMs: number): void {
+    if (!Number.isFinite(durationMs) || durationMs < 0) return;
+    this.phases.set(phase, (this.phases.get(phase) ?? 0) + durationMs);
+  }
+
+  /**
+   * Wrap a promise with automatic timing. Records wall time via
+   * {@link PhaseTimer.mark} regardless of which other phases are
+   * active — safe to use inside `Promise.all`.
+   */
+  async time<T>(phase: string, promise: Promise<T>): Promise<T> {
+    const t0 = performance.now();
+    try {
+      return await promise;
+    } finally {
+      this.mark(phase, performance.now() - t0);
+    }
+  }
+
+  /**
+   * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+   * current phase if one is still running.
+   */
+  summary(): Record<string, number> {
+    this.stop();
+    const out: Record<string, number> = {};
+    for (const [k, v] of this.phases) out[k] = Math.round(v * 10) / 10;
+    return out;
+  }
+
+  /**
+   * Sum of every recorded phase duration.
+   *
+   * Note: for phases recorded via {@link PhaseTimer.time} or
+   * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+   * concurrent work overlaps and the sum can exceed the end-to-end
+   * wall time. Record wall time separately with `mark('wall', …)` if
+   * that distinction matters.
+   */
+  totalMs(): number {
+    this.stop();
+    let t = 0;
+    for (const v of this.phases.values()) t += v;
+    return Math.round(t * 10) / 10;
+  }
+}
diff --git a/gitnexus/src/core/tree-sitter/parser-loader.ts b/gitnexus/src/core/tree-sitter/parser-loader.ts
index a4ca94c4b..c19cffcf1 100644
--- a/gitnexus/src/core/tree-sitter/parser-loader.ts
+++ b/gitnexus/src/core/tree-sitter/parser-loader.ts
@@ -54,6 +54,20 @@ const languageMap: Record<string, any> = {
 export const isLanguageAvailable = (language: SupportedLanguages): boolean =>
   language in languageMap;
 
+export const resolveLanguageKey = (language: SupportedLanguages, filePath?: string): string =>
+  language === SupportedLanguages.TypeScript && filePath?.endsWith('.tsx')
+    ? `${language}:tsx`
+    : language;
+
+export const getLanguageGrammar = (language: SupportedLanguages, filePath?: string): any => {
+  const key = resolveLanguageKey(language, filePath);
+  const lang = languageMap[key];
+  if (!lang) {
+    throw new Error(`Unsupported language: ${language}`);
+  }
+  return lang;
+};
+
 export const loadParser = async (): Promise<Parser> => {
   if (parser) return parser;
   parser = new Parser();
@@ -65,14 +79,14 @@ export const loadLanguage = async (
   filePath?: string,
 ): Promise<void> => {
   if (!parser) await loadParser();
-  const key =
-    language === SupportedLanguages.TypeScript && filePath?.endsWith('.tsx')
-      ? `${language}:tsx`
-      : language;
-
-  const lang = languageMap[key];
-  if (!lang) {
-    throw new Error(`Unsupported language: ${language}`);
-  }
-  parser!.setLanguage(lang);
+  parser!.setLanguage(getLanguageGrammar(language, filePath));
+};
+
+export const createParserForLanguage = async (
+  language: SupportedLanguages,
+  filePath?: string,
+): Promise<Parser> => {
+  const freshParser = new Parser();
+  freshParser.setLanguage(getLanguageGrammar(language, filePath));
+  return freshParser;
 };
diff --git a/gitnexus/src/mcp/local/local-backend.ts b/gitnexus/src/mcp/local/local-backend.ts
index edf5eb5b0..c37ebf4a9 100644
--- a/gitnexus/src/mcp/local/local-backend.ts
+++ b/gitnexus/src/mcp/local/local-backend.ts
@@ -29,6 +29,9 @@ import {
 } from '../../storage/repo-manager.js';
 import { GroupService, type GroupToolPort } from '../../core/group/service.js';
 import { resolveAtGroupMemberRepoPath } from '../../core/group/resolve-at-member.js';
+import { collectBestChunks } from '../../core/embeddings/types.js';
+import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { PhaseTimer } from '../../core/search/phase-timer.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 
@@ -155,6 +158,28 @@ function logQueryError(context: string, err: unknown): void {
   console.error(`GitNexus [${context}]: ${msg}`);
 }
 
+/**
+ * Structured per-query latency log for production aggregation (#553).
+ *
+ * Emitted on stderr — NOT stdout — because the MCP stdio transport uses
+ * stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
+ * `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
+ * as JSON. Any `console.log` from inside a tool handler would corrupt the
+ * protocol. Matches the existing `logQueryError` convention above, which
+ * uses stderr for the same reason.
+ *
+ * The `GitNexus [query:timing] …` prefix keeps lines greppable; the
+ * `phases` payload is JSON so log-scraping pipelines can parse it
+ * without custom format knowledge.
+ */
+function logQueryTiming(query: string, phases: Record<string, number>): void {
+  const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
+  const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
+  console.error(
+    `GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`,
+  );
+}
+
 export interface CodebaseContext {
   projectName: string;
   stats: {
@@ -319,13 +344,25 @@ export class LocalBackend {
     if (this.repos.size === 0) {
       throw new Error('No indexed repositories. Run: gitnexus analyze');
     }
-    if (repoParam) {
-      const names = [...this.repos.values()].map((h) => h.name);
-      throw new Error(`Repository "${repoParam}" not found. Available: ${names.join(', ')}`);
+
+    // Build a disambiguated "Available: …" list (#829). When two handles
+    // share a name, annotate each colliding label with its path so the
+    // caller can actually pick the right one. Single-name entries render
+    // identically to pre-#829 output.
+    const nameCounts = new Map<string, number>();
+    for (const h of this.repos.values()) {
+      const key = h.name.toLowerCase();
+      nameCounts.set(key, (nameCounts.get(key) ?? 0) + 1);
+    }
+    const labels = [...this.repos.values()].map((h) =>
+      (nameCounts.get(h.name.toLowerCase()) ?? 0) > 1 ? `${h.name} (${h.repoPath})` : h.name,
+    );
+
+    if (repoParam) {
+      throw new Error(`Repository "${repoParam}" not found. Available: ${labels.join(', ')}`);
     }
-    const names = [...this.repos.values()].map((h) => h.name);
     throw new Error(
-      `Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${names.join(', ')}`,
+      `Multiple repositories indexed. Specify which one with the "repo" parameter. Available: ${labels.join(', ')}`,
     );
   }
 
@@ -543,17 +580,29 @@ export class LocalBackend {
     const includeContent = params.include_content ?? false;
     const searchQuery = params.query.trim();
 
-    // Step 1: Run hybrid search to get matching symbols
+    // Per-phase timing instrumentation (#553). Records wall time for each
+    // observable sub-step of the search pipeline so production latency can
+    // be aggregated offline for Pareto analysis and bottleneck detection.
+    // Overhead is <0.1 ms per phase; the timer is passive and never alters
+    // query behaviour.
+    const timer = new PhaseTimer();
+    const wallStart = performance.now();
+
+    // Step 1: Run hybrid search to get matching symbols. BM25 and vector
+    // search run concurrently via Promise.all — use `timer.time()` for
+    // each so both get independent wall-time records without fighting
+    // over a single `current` phase slot.
     const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
     const [bm25SearchResult, semanticResults] = await Promise.all([
-      this.bm25Search(repo, searchQuery, searchLimit),
-      this.semanticSearch(repo, searchQuery, searchLimit),
+      timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
+      timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
     ]);
 
     const bm25Results = bm25SearchResult.results;
     const ftsUsed = bm25SearchResult.ftsUsed;
 
     // Merge via reciprocal rank fusion
+    timer.start('merge');
     const scoreMap = new Map<string, { score: number; data: any }>();
 
     for (let i = 0; i < bm25Results.length; i++) {
@@ -583,8 +632,10 @@ export class LocalBackend {
     const merged = Array.from(scoreMap.entries())
       .sort((a, b) => b[1].score - a[1].score)
       .slice(0, searchLimit);
+    timer.stop(); // merge
 
     // Step 2: For each match with a nodeId, trace to process(es)
+    timer.start('symbol_lookup');
     const processMap = new Map<
       string,
       {
@@ -717,7 +768,10 @@ export class LocalBackend {
       }
     }
 
+    timer.stop(); // symbol_lookup
+
     // Step 3: Rank processes by aggregate score + internal cohesion boost
+    timer.start('ranking');
     const rankedProcesses = Array.from(processMap.values())
       .map((p) => ({
         ...p,
@@ -725,8 +779,10 @@ export class LocalBackend {
       }))
       .sort((a, b) => b.priority - a.priority)
       .slice(0, processLimit);
+    timer.stop(); // ranking
 
     // Step 4: Build response
+    timer.start('formatting');
     const processes = rankedProcesses.map((p) => ({
       id: p.id,
       summary: p.heuristicLabel || p.label,
@@ -750,11 +806,20 @@ export class LocalBackend {
       seen.add(s.id);
       return true;
     });
+    timer.stop(); // formatting
+
+    // End-to-end wall time — deliberately a separate mark so callers can
+    // compare sum(phases) vs wall to see how much Promise.all concurrency
+    // saved. Must come before summary() so it's included.
+    timer.mark('wall', performance.now() - wallStart);
+    const timing = timer.summary();
+    logQueryTiming(searchQuery, timing);
 
     return {
       processes,
       process_symbols: dedupedSymbols,
       definitions: definitions.slice(0, 20), // cap standalone definitions
+      timing,
       ...(!ftsUsed && {
         warning:
           'FTS extension unavailable - keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
@@ -840,7 +905,7 @@ export class LocalBackend {
       // Check if embedding table exists before loading the model (avoids heavy model init when embeddings are off)
       const tableCheck = await executeQuery(
         repo.id,
-        `MATCH (e:CodeEmbedding) RETURN COUNT(*) AS cnt LIMIT 1`,
+        `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN COUNT(*) AS cnt LIMIT 1`,
       );
       if (!tableCheck.length || (tableCheck[0].cnt ?? tableCheck[0][0]) === 0) return [];
 
@@ -849,26 +914,33 @@ export class LocalBackend {
       const dims = getEmbeddingDims();
       const queryVecStr = `[${queryVec.join(',')}]`;
 
-      const vectorQuery = `
-        CALL QUERY_VECTOR_INDEX('CodeEmbedding', 'code_embedding_idx', 
-          CAST(${queryVecStr} AS FLOAT[${dims}]), ${limit})
-        YIELD node AS emb, distance
-        WITH emb, distance
-        WHERE distance < 0.6
-        RETURN emb.nodeId AS nodeId, distance
-        ORDER BY distance
-      `;
+      const bestChunks = await collectBestChunks(limit, async (fetchLimit) => {
+        const vectorQuery = `
+          CALL QUERY_VECTOR_INDEX('${EMBEDDING_TABLE_NAME}', '${EMBEDDING_INDEX_NAME}',
+            CAST(${queryVecStr} AS FLOAT[${dims}]), ${fetchLimit})
+          YIELD node AS emb, distance
+          WITH emb, distance
+          WHERE distance < 0.6
+          RETURN emb.nodeId AS nodeId, emb.chunkIndex AS chunkIndex,
+                 emb.startLine AS startLine, emb.endLine AS endLine, distance
+          ORDER BY distance
+        `;
 
-      const embResults = await executeQuery(repo.id, vectorQuery);
+        const embResults = await executeQuery(repo.id, vectorQuery);
+        return embResults.map((row) => ({
+          nodeId: row.nodeId ?? row[0],
+          chunkIndex: row.chunkIndex ?? row[1] ?? 0,
+          startLine: row.startLine ?? row[2] ?? 0,
+          endLine: row.endLine ?? row[3] ?? 0,
+          distance: row.distance ?? row[4],
+        }));
+      });
 
-      if (embResults.length === 0) return [];
+      if (bestChunks.size === 0) return [];
 
       const results: any[] = [];
 
-      for (const embRow of embResults) {
-        const nodeId = embRow.nodeId ?? embRow[0];
-        const distance = embRow.distance ?? embRow[1];
-
+      for (const [nodeId, chunk] of Array.from(bestChunks.entries()).slice(0, limit)) {
         const labelEndIdx = nodeId.indexOf(':');
         const label = labelEndIdx > 0 ? nodeId.substring(0, labelEndIdx) : 'Unknown';
 
@@ -879,7 +951,7 @@ export class LocalBackend {
           const nodeQuery =
             label === 'File'
               ? `MATCH (n:File {id: $nodeId}) RETURN n.name AS name, n.filePath AS filePath`
-              : `MATCH (n:\`${label}\` {id: $nodeId}) RETURN n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine`;
+              : `MATCH (n:\`${label}\` {id: $nodeId}) RETURN n.name AS name, n.filePath AS filePath`;
 
           const nodeRows = await executeParameterized(repo.id, nodeQuery, { nodeId });
           if (nodeRows.length > 0) {
@@ -889,9 +961,9 @@ export class LocalBackend {
               name: nodeRow.name ?? nodeRow[0] ?? '',
               type: label,
               filePath: nodeRow.filePath ?? nodeRow[1] ?? '',
-              distance,
-              startLine: label !== 'File' ? (nodeRow.startLine ?? nodeRow[2]) : undefined,
-              endLine: label !== 'File' ? (nodeRow.endLine ?? nodeRow[3]) : undefined,
+              distance: chunk.distance,
+              startLine: chunk.startLine,
+              endLine: chunk.endLine,
             });
           }
         } catch {}
@@ -1081,9 +1153,296 @@ export class LocalBackend {
     return result;
   }
 
+  /**
+   * Patch the `type` field on candidates whose `labels(n)[0]` projection
+   * came back empty — a known LadybugDB behaviour for several node types.
+   *
+   * Uses one scoped UNION query across the five priority labels rather
+   * than per-candidate round-trips, so cost is a single DB call regardless
+   * of how many candidates need enrichment. No-op when every candidate
+   * already has a non-empty type.
+   *
+   * Failures are swallowed: label enrichment is an optimisation for
+   * downstream scoring and #480 Class/Interface BFS seeding; if it fails
+   * the symbol still resolves, just without the kind-priority bonus.
+   */
+  private async enrichCandidateLabels(
+    repo: RepoHandle,
+    candidates: Array<{ id: string; type: string }>,
+  ): Promise<void> {
+    const ids = candidates.filter((c) => c.type === '' && c.id).map((c) => c.id);
+    if (ids.length === 0) return;
+    try {
+      const rows = await executeParameterized(
+        repo.id,
+        `
+        MATCH (n:\`Class\`) WHERE n.id IN $ids RETURN n.id AS id, 'Class' AS label
+        UNION ALL
+        MATCH (n:\`Interface\`) WHERE n.id IN $ids RETURN n.id AS id, 'Interface' AS label
+        UNION ALL
+        MATCH (n:\`Function\`) WHERE n.id IN $ids RETURN n.id AS id, 'Function' AS label
+        UNION ALL
+        MATCH (n:\`Method\`) WHERE n.id IN $ids RETURN n.id AS id, 'Method' AS label
+        UNION ALL
+        MATCH (n:\`Constructor\`) WHERE n.id IN $ids RETURN n.id AS id, 'Constructor' AS label
+        `,
+        { ids },
+      );
+      const labelById = new Map<string, string>();
+      for (const r of rows as any[]) {
+        const id = (r.id ?? r[0]) as string;
+        const label = (r.label ?? r[1]) as string;
+        if (id && label && !labelById.has(id)) labelById.set(id, label);
+      }
+      for (const c of candidates) {
+        if (c.type === '' && labelById.has(c.id)) c.type = labelById.get(c.id) as string;
+      }
+    } catch {
+      /* best-effort — downstream resolvers still work without the label */
+    }
+  }
+
+  /**
+   * Score a symbol candidate for disambiguation ranking.
+   *
+   * Deterministic, no DB round-trip:
+   *   - base 0.50
+   *   - +0.40 when file_path hint matches (substring, case-insensitive)
+   *   - +0.20 when kind hint exactly matches the candidate's kind
+   *   - when no kind hint, a small priority bonus (Class > Interface >
+   *     Function > Method > Constructor) to preserve the intuition that
+   *     class-level names are usually what the user wanted.
+   *
+   * Capped at 1.0. Intentionally simple and inspectable — a future v2 can
+   * plug in BM25/embedding signals here without changing the surrounding
+   * resolver shape.
+   */
+  private scoreCandidate(
+    c: { kind: string; filePath: string },
+    hints: { file_path?: string; kind?: string },
+  ): number {
+    let s = 0.5;
+    if (hints.file_path && c.filePath && typeof c.filePath === 'string') {
+      if (c.filePath.toLowerCase().includes(hints.file_path.toLowerCase())) {
+        s += 0.4;
+      }
+    }
+    if (hints.kind && c.kind === hints.kind) {
+      s += 0.2;
+    }
+    if (!hints.kind) {
+      const priority: Record<string, number> = {
+        Class: 5,
+        Interface: 4,
+        Function: 3,
+        Method: 2,
+        Constructor: 1,
+      };
+      s += (priority[c.kind] ?? 0) * 0.02;
+    }
+    return Math.min(1.0, s);
+  }
+
+  /**
+   * Shared symbol resolver used by `context` and `impact`.
+   *
+   * Returns one of:
+   *   - `{ kind: 'ok', symbol, resolvedLabel }` — single confident match
+   *     (either direct UID, only one candidate after filtering, Class/
+   *     Constructor collapse, or a top-scoring candidate with a clear gap
+   *     to the runner-up).
+   *   - `{ kind: 'ambiguous', candidates }` — multiple viable matches,
+   *     sorted by score desc. Each candidate carries a relevance score.
+   *   - `{ kind: 'not_found' }` — no matches at all.
+   *
+   * Preserves the #480 Class/Constructor preference: when the only
+   * ambiguity is between a Class and its own Constructor (same name,
+   * same filePath), the Class wins silently.
+   */
+  private async resolveSymbolCandidates(
+    repo: RepoHandle,
+    query: { uid?: string; name?: string; include_content?: boolean },
+    hints: { file_path?: string; kind?: string },
+  ): Promise<
+    | {
+        kind: 'ok';
+        symbol: {
+          id: string;
+          name: string;
+          type: string;
+          filePath: string;
+          startLine: number;
+          endLine: number;
+          content?: string;
+        };
+        resolvedLabel: string;
+      }
+    | {
+        kind: 'ambiguous';
+        candidates: Array<{
+          id: string;
+          name: string;
+          type: string;
+          filePath: string;
+          startLine: number;
+          endLine: number;
+          score: number;
+        }>;
+      }
+    | { kind: 'not_found' }
+  > {
+    const { uid, name, include_content } = query;
+    const selectClause = `n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}`;
+
+    // Direct UID — zero-ambiguity path.
+    if (uid) {
+      const rows = await executeParameterized(
+        repo.id,
+        `MATCH (n {id: $uid}) RETURN ${selectClause} LIMIT 1`,
+        { uid },
+      );
+      if (rows.length === 0) return { kind: 'not_found' };
+      const r = rows[0] as any;
+      const symbol = {
+        id: (r.id ?? r[0]) as string,
+        name: (r.name ?? r[1]) as string,
+        type: (r.type ?? r[2] ?? '') as string,
+        filePath: (r.filePath ?? r[3]) as string,
+        startLine: (r.startLine ?? r[4]) as number,
+        endLine: (r.endLine ?? r[5]) as number,
+        ...(include_content ? { content: (r.content ?? r[6]) as string | undefined } : {}),
+      };
+      // Same LadybugDB label-enrichment as the name-based path: a UID
+      // pointing at a Class must still surface `type: 'Class'` so impact's
+      // Class/Interface BFS seed fires. No-op when type is already set.
+      await this.enrichCandidateLabels(repo, [symbol]);
+      return { kind: 'ok', symbol, resolvedLabel: symbol.type };
+    }
+
+    if (!name) return { kind: 'not_found' };
+
+    const isQualified = name.includes('/') || name.includes(':');
+    let whereClause: string;
+    const queryParams: Record<string, any> = { symName: name };
+    if (hints.file_path) {
+      whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
+      queryParams.filePath = hints.file_path;
+    } else if (isQualified) {
+      whereClause = `WHERE n.id = $symName OR n.name = $symName`;
+    } else {
+      whereClause = `WHERE n.name = $symName`;
+    }
+
+    // LIMIT 20 (was 10) — scoring is the point now, so give the ranker
+    // headroom instead of arbitrary truncation.
+    const rows = await executeParameterized(
+      repo.id,
+      `MATCH (n) ${whereClause} RETURN ${selectClause} LIMIT 20`,
+      queryParams,
+    );
+
+    if (rows.length === 0) return { kind: 'not_found' };
+
+    // Normalise row shape across object / tuple returns from LadybugDB.
+    const normalized = rows.map((r: any) => ({
+      id: (r.id ?? r[0]) as string,
+      name: (r.name ?? r[1]) as string,
+      type: (r.type ?? r[2] ?? '') as string,
+      filePath: (r.filePath ?? r[3]) as string,
+      startLine: (r.startLine ?? r[4]) as number,
+      endLine: (r.endLine ?? r[5]) as number,
+      ...(include_content ? { content: (r.content ?? r[6]) as string | undefined } : {}),
+    }));
+
+    // Enrich labels for any candidates where `labels(n)[0]` came back empty.
+    // LadybugDB returns an empty string for that projection on certain node
+    // types (notably Class), which left downstream consumers (impact's
+    // Class/Interface BFS seed, the kind-priority scoring bonus) unable to
+    // distinguish a Class target from "unknown kind". One scoped UNION
+    // across the five priority labels patches the type in-place without
+    // per-candidate round-trips.
+    await this.enrichCandidateLabels(repo, normalized);
+
+    // Preserve #480 Class/Constructor collapse: if we have exactly one
+    // Class (or Interface) candidate and one Constructor sharing name +
+    // filePath, fold into the Class. This used to require a follow-up
+    // label query because LadybugDB sometimes returns an empty labels()[0]
+    // for Class nodes — enrichment above handles the empty-type case, but
+    // the `type === 'Constructor'` gate still correctly triggers when a
+    // Class and its Constructor share the name.
+    if (!hints.kind && normalized.length > 1) {
+      const ambiguousType = normalized.some((s) => s.type === '' || s.type === 'Constructor');
+      if (ambiguousType) {
+        const candidateIds = normalized.map((s) => s.id).filter(Boolean);
+        for (const label of ['Class', 'Interface']) {
+          const labelRows = await executeParameterized(
+            repo.id,
+            `MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1`,
+            { candidateIds },
+          ).catch(() => []);
+          if (labelRows.length > 0) {
+            const preferredId = (labelRows[0] as any).id ?? (labelRows[0] as any)[0];
+            const preferred = normalized.find((s) => s.id === preferredId);
+            if (preferred) {
+              return {
+                kind: 'ok',
+                symbol: preferred,
+                resolvedLabel: label,
+              };
+            }
+          }
+        }
+      }
+    }
+
+    if (normalized.length === 1) {
+      return {
+        kind: 'ok',
+        symbol: normalized[0],
+        resolvedLabel: '',
+      };
+    }
+
+    // Score, sort desc, stable tiebreak on shorter filePath then lex uid.
+    const scored = normalized.map((s) => ({
+      ...s,
+      score: this.scoreCandidate({ kind: s.type, filePath: s.filePath || '' }, hints),
+    }));
+    scored.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      const fpA = (a.filePath || '').length;
+      const fpB = (b.filePath || '').length;
+      if (fpA !== fpB) return fpA - fpB;
+      return String(a.id).localeCompare(String(b.id));
+    });
+
+    // Confident single-result: top score ≥ 0.95 AND beats runner-up by a
+    // clear margin. This lets a very strong file_path/kind hint resolve
+    // cleanly instead of forcing the caller through a disambiguation
+    // round-trip.
+    //
+    // The gap threshold uses `> 0.09` rather than `>= 0.10` on purpose:
+    // IEEE754 addition of the scoring terms (0.50 + 0.40 + 0.20 - 0.90
+    // yields 0.09999999999999998, not exactly 0.10) would otherwise break
+    // the comparison for legitimate "top is 1.00, runner is 0.90" cases.
+    // The intent is a clearly-dominant winner; 0.09 is a large enough
+    // margin to mean that unambiguously.
+    //
+    // The `scored.length >= 2` guard is defensive. The `normalized.length === 1`
+    // early return above already handles the single-candidate path, so in
+    // practice `scored` always has at least two elements by the time we get
+    // here — keeping the guard means changes to the upstream early-return
+    // logic cannot accidentally index out of bounds at `scored[1]`.
+    if (scored.length >= 2 && scored[0].score >= 0.95 && scored[0].score - scored[1].score > 0.09) {
+      return { kind: 'ok', symbol: scored[0], resolvedLabel: scored[0].type };
+    }
+
+    return { kind: 'ambiguous', candidates: scored };
+  }
+
   /**
    * Context tool — 360-degree symbol view with categorized refs.
-   * Disambiguation when multiple symbols share a name.
+   * Disambiguation (ranked) when multiple symbols share a name.
    * UID-based direct lookup. No cluster in output.
    */
   private async context(
@@ -1092,124 +1451,47 @@ export class LocalBackend {
       name?: string;
       uid?: string;
       file_path?: string;
+      kind?: string;
       include_content?: boolean;
     },
   ): Promise<any> {
     await this.ensureInitialized(repo.id);
 
-    const { name, uid, file_path, include_content } = params;
+    const { name, uid, file_path, kind, include_content } = params;
 
     if (!name && !uid) {
       return { error: 'Either "name" or "uid" parameter is required.' };
     }
 
-    // Step 1: Find the symbol
-    let symbols: any[];
+    const outcome = await this.resolveSymbolCandidates(
+      repo,
+      { uid, name, include_content },
+      { file_path, kind },
+    );
 
-    if (uid) {
-      symbols = await executeParameterized(
-        repo.id,
-        `
-        MATCH (n {id: $uid})
-        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
-        LIMIT 1
-      `,
-        { uid },
-      );
-    } else {
-      const isQualified = name!.includes('/') || name!.includes(':');
-
-      let whereClause: string;
-      let queryParams: Record<string, any>;
-      if (file_path) {
-        whereClause = `WHERE n.name = $symName AND n.filePath CONTAINS $filePath`;
-        queryParams = { symName: name!, filePath: file_path };
-      } else if (isQualified) {
-        whereClause = `WHERE n.id = $symName OR n.name = $symName`;
-        queryParams = { symName: name! };
-      } else {
-        whereClause = `WHERE n.name = $symName`;
-        queryParams = { symName: name! };
-      }
-
-      symbols = await executeParameterized(
-        repo.id,
-        `
-        MATCH (n) ${whereClause}
-        RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine${include_content ? ', n.content AS content' : ''}
-        LIMIT 10
-      `,
-        queryParams,
-      );
-    }
-
-    if (symbols.length === 0) {
+    if (outcome.kind === 'not_found') {
       return { error: `Symbol '${name || uid}' not found` };
     }
 
-    // Step 2: Disambiguation
-    // When multiple nodes share the same name (e.g. a Java Class and its
-    // Constructor both named 'SessionTracker'), prefer the Class node so
-    // context() returns the semantically meaningful result rather than
-    // triggering ambiguous disambiguation (#480).
-    // labels(n)[0] returns empty string in LadybugDB, so we resolve the
-    // preferred node by re-querying with explicit label filters, scoped to
-    // the candidate IDs already in symbols.
-    //
-    // Guard: only attempt Class-preference when at least one candidate has an
-    // empty/unknown type (LadybugDB limitation) or is a Constructor — meaning
-    // the ambiguity may be a Class/Constructor name collision rather than two
-    // genuinely distinct symbols (e.g. two Functions in different files).
-    //
-    // resolvedLabel is set here and threaded to Step 3 to avoid a redundant
-    // classCheck round-trip later.
-    let resolvedLabel = '';
-    if (symbols.length > 1 && !uid) {
-      const hasAmbiguousType = symbols.some((s: any) => {
-        const t = s.type || s[2] || '';
-        return t === '' || t === 'Constructor';
-      });
-      if (hasAmbiguousType) {
-        const candidateIds = symbols.map((s: any) => s.id || s[0]).filter(Boolean);
-        const PREFER_LABELS = ['Class', 'Interface'];
-        let preferred: any = null;
-        for (const label of PREFER_LABELS) {
-          const match = await executeParameterized(
-            repo.id,
-            `
-            MATCH (n:\`${label}\`) WHERE n.id IN $candidateIds RETURN n.id AS id LIMIT 1
-          `,
-            { candidateIds },
-          ).catch(() => []);
-          if (match.length > 0) {
-            preferred = symbols.find((s: any) => (s.id || s[0]) === (match[0].id || match[0][0]));
-            if (preferred) {
-              resolvedLabel = label;
-              break;
-            }
-          }
-        }
-        if (preferred) symbols = [preferred];
-      }
-    }
-
-    if (symbols.length > 1 && !uid) {
+    if (outcome.kind === 'ambiguous') {
       return {
         status: 'ambiguous',
-        message: `Found ${symbols.length} symbols matching '${name}'. Use uid or file_path to disambiguate.`,
-        candidates: symbols.map((s: any) => ({
-          uid: s.id || s[0],
-          name: s.name || s[1],
-          kind: s.type || s[2],
-          filePath: s.filePath || s[3],
-          line: s.startLine || s[4],
+        message: `Found ${outcome.candidates.length} symbols matching '${name}'. Use uid, file_path, or kind to disambiguate.`,
+        candidates: outcome.candidates.map((c) => ({
+          uid: c.id,
+          name: c.name,
+          kind: c.type,
+          filePath: c.filePath,
+          line: c.startLine,
+          score: Number(c.score.toFixed(2)),
         })),
       };
     }
 
     // Step 3: Build full context
-    const sym = symbols[0];
-    const symId = sym.id || sym[0];
+    const sym = outcome.symbol;
+    const resolvedLabel = outcome.resolvedLabel;
+    const symId = sym.id;
 
     // Categorized incoming refs
     const incomingRows = await executeParameterized(
@@ -1557,7 +1839,14 @@ export class LocalBackend {
 
     let diffOutput: string;
     try {
-      diffOutput = execFileSync('git', diffArgs, { cwd: repo.repoPath, encoding: 'utf-8' });
+      // maxBuffer raised from Node's 1MB default to 256MB to avoid ENOBUFS on
+      // repos with large unstaged/untracked diffs (e.g. unignored build folders).
+      // See issue: spawnSync git ENOBUFS in detect_changes(scope="unstaged").
+      diffOutput = execFileSync('git', diffArgs, {
+        cwd: repo.repoPath,
+        encoding: 'utf-8',
+        maxBuffer: 256 * 1024 * 1024,
+      });
     } catch (err: any) {
       return { error: `Git diff failed: ${err.message}` };
     }
@@ -1831,6 +2120,8 @@ export class LocalBackend {
         cwd: repo.repoPath,
         encoding: 'utf-8',
         timeout: 5000,
+        // Avoid ENOBUFS on large repos: rg -l can list many files.
+        maxBuffer: 256 * 1024 * 1024,
       });
       const files = output
         .trim()
@@ -1903,6 +2194,9 @@ export class LocalBackend {
     repo: RepoHandle,
     params: {
       target: string;
+      target_uid?: string;
+      file_path?: string;
+      kind?: string;
       direction: 'upstream' | 'downstream';
       maxDepth?: number;
       relationTypes?: string[];
@@ -1929,6 +2223,9 @@ export class LocalBackend {
     repo: RepoHandle,
     params: {
       target: string;
+      target_uid?: string;
+      file_path?: string;
+      kind?: string;
       direction: 'upstream' | 'downstream';
       maxDepth?: number;
       relationTypes?: string[];
@@ -1971,65 +2268,57 @@ export class LocalBackend {
     const includeTests = params.includeTests ?? false;
     const minConfidence = params.minConfidence ?? 0;
 
-    // Resolve target by name, preferring Class/Interface over Constructor
-    // (fix #480: Java class and constructor share the same name).
-    // labels(n)[0] returns empty string in LadybugDB, so we use explicit
-    // label-typed sub-queries in a single UNION ordered by priority to avoid
-    // up to 6 serial round-trips for non-Class targets.
-    let sym: any = null;
-    let symType = '';
+    // Resolve target via the shared symbol resolver. When the caller passes
+    // target_uid we skip the name lookup entirely (zero-ambiguity). Otherwise
+    // we rank candidates (#470) and either proceed with a confident single
+    // match, or return a structured ambiguous response instead of silently
+    // picking the wrong symbol.
+    //
+    // The resolver preserves the #480 Class/Constructor preference heuristic:
+    // when a Class and its Constructor share name + filePath, the Class is
+    // selected silently.
+    const outcome = await this.resolveSymbolCandidates(
+      repo,
+      { uid: params.target_uid, name: target },
+      { file_path: params.file_path, kind: params.kind },
+    );
 
-    try {
-      const rows = await executeParameterized(
-        repo.id,
-        `
-        MATCH (n:\`Class\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 0 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Interface\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 1 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Function\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 2 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Method\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 3 AS priority LIMIT 1
-        UNION ALL
-        MATCH (n:\`Constructor\`) WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath, 4 AS priority LIMIT 1
-      `,
-        { targetName: target },
-      ).catch(() => []);
-
-      if (rows.length > 0) {
-        // Pick the row with the lowest priority value (Class wins over Constructor)
-        const best = rows.reduce((a: any, b: any) =>
-          (a.priority ?? a[3] ?? 99) <= (b.priority ?? b[3] ?? 99) ? a : b,
-        );
-        sym = best;
-        const priorityToLabel = ['Class', 'Interface', 'Function', 'Method', 'Constructor'];
-        symType = priorityToLabel[best.priority ?? best[3]] ?? '';
-      }
-    } catch {
-      /* fall through to unlabeled match */
+    if (outcome.kind === 'not_found') {
+      const missing = params.target_uid ?? target;
+      return {
+        error: `Target '${missing}' not found`,
+        target: { name: target },
+        direction,
+        impactedCount: 0,
+        risk: 'UNKNOWN',
+      };
     }
 
-    // Fall back to unlabeled match for any other node type
-    if (!sym) {
-      const rows = await executeParameterized(
-        repo.id,
-        `
-        MATCH (n)
-        WHERE n.name = $targetName
-        RETURN n.id AS id, n.name AS name, n.filePath AS filePath
-        LIMIT 1
-      `,
-        { targetName: target },
-      );
-      if (rows.length > 0) sym = rows[0];
+    if (outcome.kind === 'ambiguous') {
+      return {
+        status: 'ambiguous',
+        message: `Found ${outcome.candidates.length} symbols matching '${target}'. Use target_uid, file_path, or kind to disambiguate.`,
+        target: { name: target },
+        direction,
+        impactedCount: 0,
+        risk: 'UNKNOWN',
+        candidates: outcome.candidates.map((c) => ({
+          uid: c.id,
+          name: c.name,
+          kind: c.type,
+          filePath: c.filePath,
+          line: c.startLine,
+          score: Number(c.score.toFixed(2)),
+        })),
+      };
     }
 
-    if (!sym) return { error: `Target '${target}' not found` };
+    const sym = {
+      id: outcome.symbol.id,
+      name: outcome.symbol.name,
+      filePath: outcome.symbol.filePath,
+    };
+    const symType = outcome.resolvedLabel || outcome.symbol.type || '';
 
     return this._runImpactBFS(repo, sym, symType, direction, {
       maxDepth,
diff --git a/gitnexus/src/mcp/tools.ts b/gitnexus/src/mcp/tools.ts
index 9e15cb375..f5fc31f47 100644
--- a/gitnexus/src/mcp/tools.ts
+++ b/gitnexus/src/mcp/tools.ts
@@ -176,7 +176,7 @@ Shows categorized incoming/outgoing references (calls, imports, extends, impleme
 WHEN TO USE: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.
 AFTER THIS: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.
 
-Handles disambiguation: if multiple symbols share the same name, returns candidates for you to pick from. Use uid param for zero-ambiguity lookup from prior results.
+Handles disambiguation: if multiple symbols share the same name, returns ranked candidates (each with a relevance score) for you to pick from. Use uid for zero-ambiguity lookup, or narrow the search with file_path and/or kind hints.
 
 NOTE: ACCESSES edges (field read/write tracking) are included in context results with reason 'read' or 'write'. CALLS edges resolve through field access chains and method-call chains (e.g., user.address.getCity().save() produces CALLS edges at each step).
 
@@ -192,6 +192,11 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
           description: 'Direct symbol UID from prior tool results (zero-ambiguity lookup)',
         },
         file_path: { type: 'string', description: 'File path to disambiguate common names' },
+        kind: {
+          type: 'string',
+          description:
+            "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
+        },
         include_content: {
           type: 'boolean',
           description: 'Include full symbol source code (default: false)',
@@ -298,6 +303,8 @@ Depth groups:
 
 TIP: Default traversal uses CALLS/IMPORTS/EXTENDS/IMPLEMENTS. For class members, include HAS_METHOD and HAS_PROPERTY in relationTypes. For field access analysis, include ACCESSES in relationTypes.
 
+Handles disambiguation: when multiple symbols share the target name, returns ranked candidates (each with a relevance score) instead of silently picking one. Use target_uid for zero-ambiguity lookup, or narrow with file_path and/or kind hints.
+
 EdgeType: CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, METHOD_OVERRIDES, METHOD_IMPLEMENTS, ACCESSES
 Confidence: 1.0 = certain, <0.8 = fuzzy match
 
@@ -308,10 +315,24 @@ SERVICE: optional monorepo path prefix (case-sensitive path segments). When "rep
       type: 'object',
       properties: {
         target: { type: 'string', description: 'Name of function, class, or file to analyze' },
+        target_uid: {
+          type: 'string',
+          description:
+            'Direct symbol UID from prior tool results (zero-ambiguity lookup, skips target resolution)',
+        },
         direction: {
           type: 'string',
           description: 'upstream (what depends on this) or downstream (what this depends on)',
         },
+        file_path: {
+          type: 'string',
+          description: 'File path hint to disambiguate common names',
+        },
+        kind: {
+          type: 'string',
+          description:
+            "Kind filter to disambiguate common names (e.g. 'Function', 'Class', 'Method', 'Interface', 'Constructor')",
+        },
         maxDepth: {
           type: 'number',
           description: 'Max relationship depth (default: 3, server clamps to 1–32)',
diff --git a/gitnexus/src/server/api.ts b/gitnexus/src/server/api.ts
index b0e47e019..6cae3bbe1 100644
--- a/gitnexus/src/server/api.ts
+++ b/gitnexus/src/server/api.ts
@@ -1481,6 +1481,8 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
                 });
               },
               {}, // config: use defaults
+              undefined, // skipNodeIds
+              undefined, // context
               existingEmbeddings,
             );
           });
diff --git a/gitnexus/src/storage/git.ts b/gitnexus/src/storage/git.ts
index b0e9e6d3e..c8d05ac4b 100644
--- a/gitnexus/src/storage/git.ts
+++ b/gitnexus/src/storage/git.ts
@@ -53,6 +53,58 @@ export const hasGitDir = (dirPath: string): boolean => {
   }
 };
 
+/**
+ * Read `remote.origin.url` from a git repository, or `null` if not a
+ * git repo, has no `origin` remote, or git is unavailable.
+ *
+ * Used by the registry-name inference path (#979) to recover a
+ * meaningful repo name when `path.basename(repoPath)` is generic
+ * (e.g. monorepo subprojects, git worktrees, Gas-Town-style
+ * `<rig>/refinery/rig/` layouts).
+ */
+export const getRemoteOriginUrl = (repoPath: string): string | null => {
+  try {
+    const url = execSync('git config --get remote.origin.url', {
+      cwd: repoPath,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+    return url || null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Parse a repository name out of a git remote URL. Handles the common
+ * SSH (`git@host:owner/repo.git`), HTTPS (`https://host/owner/repo.git`),
+ * `git://`, `ssh://`, and `file://` shapes. Returns `null` for empty /
+ * unparseable input.
+ *
+ * The heuristic: strip a trailing `.git` and trailing slashes, then
+ * take the segment after the last `/` or `:`.
+ */
+export const parseRepoNameFromUrl = (url: string | null | undefined): string | null => {
+  if (!url) return null;
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+  // Strip `.git` suffix (case-insensitive) and any trailing slashes.
+  const withoutSuffix = trimmed.replace(/\.git\/*$/i, '').replace(/\/+$/, '');
+  // Last path segment, splitting on either `/` or `:` (covers SSH form).
+  const m = withoutSuffix.match(/[/:]([^/:]+)$/);
+  const candidate = m ? m[1] : withoutSuffix;
+  return candidate || null;
+};
+
+/**
+ * Convenience wrapper: derive a registry-friendly name from the repo's
+ * `origin` remote, or `null` when it cannot be inferred.
+ */
+export const getInferredRepoName = (repoPath: string): string | null => {
+  return parseRepoNameFromUrl(getRemoteOriginUrl(repoPath));
+};
+
 export interface DiffHunk {
   startLine: number;
   endLine: number;
diff --git a/gitnexus/src/storage/repo-manager.ts b/gitnexus/src/storage/repo-manager.ts
index b233d44fb..1b151cec1 100644
--- a/gitnexus/src/storage/repo-manager.ts
+++ b/gitnexus/src/storage/repo-manager.ts
@@ -9,6 +9,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
+import { getInferredRepoName } from './git.js';
 
 export interface RepoMeta {
   repoPath: string;
@@ -244,21 +245,160 @@ const writeRegistry = async (entries: RegistryEntry[]): Promise<void> => {
   await fs.writeFile(getGlobalRegistryPath(), JSON.stringify(entries, null, 2), 'utf-8');
 };
 
+/**
+ * Options for {@link registerRepo}. All optional — callers without any
+ * disambiguation requirement can keep calling `registerRepo(path, meta)`
+ * unchanged.
+ */
+export interface RegisterRepoOptions {
+  /**
+   * User-provided alias from `analyze --name <alias>` (#829). Overrides
+   * the default basename-derived registry `name`. Persisted — subsequent
+   * re-analyses of the same path without `--name` preserve the alias.
+   */
+  name?: string;
+  /**
+   * Allow two DIFFERENT repo paths to register under the same alias
+   * (#829). Mapped from the `--allow-duplicate-name` CLI flag.
+   *
+   * Scope: this flag governs cross-path alias sharing only — one repo
+   * path always has exactly one registry entry (and therefore exactly
+   * one alias). Re-analyzing the same path with `--name Y` overwrites
+   * a previous `--name X`; it does NOT create a second entry or a
+   * second alias for the same path (see the upsert-by-resolved-path
+   * logic in {@link registerRepo} and the
+   * `re-registerRepo with a different name overrides the previous
+   * alias` test in `test/unit/repo-manager.test.ts`).
+   *
+   * Distinct from `--force` (which only triggers pipeline re-index);
+   * a user accepting a duplicate alias should not be forced to also
+   * re-run the full pipeline.
+   */
+  allowDuplicateName?: boolean;
+}
+
+/**
+ * Thrown by {@link registerRepo} when a requested name is already in
+ * use by a DIFFERENT path. The CLI layer surfaces this as an actionable
+ * error instead of relying on `.message` string-matching.
+ *
+ * The colliding alias is exposed as `err.registryName` (not `err.name`).
+ * `err.name` keeps its inherited `Error.prototype.name` semantics (the
+ * class name) so downstream code can do the usual `err.name ===
+ * 'RegistryNameCollisionError'` checks; use the `kind` discriminant or
+ * `instanceof RegistryNameCollisionError` for type-safe narrowing.
+ */
+export class RegistryNameCollisionError extends Error {
+  readonly kind = 'RegistryNameCollisionError' as const;
+  constructor(
+    public readonly registryName: string,
+    public readonly existingPath: string,
+    public readonly requestedPath: string,
+  ) {
+    super(
+      `Registry name "${registryName}" is already used by "${existingPath}".\n` +
+        `Pass --name <alias> to register "${requestedPath}" under a different name, ` +
+        `or --allow-duplicate-name to allow both paths under the same name (leaves -r <name> ambiguous for these two).`,
+    );
+    this.name = 'RegistryNameCollisionError';
+  }
+}
+
+/** Returns true when a previously-registered entry's `name` differs from
+ *  both `path.basename(entry.path)` and the git-remote-derived name —
+ *  i.e. a user explicitly aliased it via `analyze --name <alias>` on a
+ *  prior run. Used to preserve the alias across re-analyses that omit
+ *  `--name`. The remote-derived name is treated as an inference, not a
+ *  custom alias, so re-analyses keep tracking remote renames.
+ *
+ *  `inferredName` is passed in (rather than re-derived) so callers can
+ *  avoid a second `git config` subprocess invocation. */
+const hasCustomAlias = (entry: RegistryEntry, inferredName: string | null): boolean => {
+  const resolved = path.resolve(entry.path);
+  if (entry.name === path.basename(resolved)) return false;
+  if (inferredName && entry.name === inferredName) return false;
+  return true;
+};
+
 /**
  * Register (add or update) a repo in the global registry.
  * Called after `gitnexus analyze` completes.
+ *
+ * Name resolution precedence (#829, #979):
+ *   1. explicit `opts.name` (from `analyze --name <alias>`)
+ *   2. preserved alias on an existing entry for this path
+ *   3. `git config --get remote.origin.url` repo name (#979 — recovers
+ *      a meaningful name for monorepo subprojects, git worktrees, and
+ *      Gas-Town-style `<rig>/refinery/rig/` layouts where the basename
+ *      is generic)
+ *   4. `path.basename(repoPath)` (the original default)
+ *
+ * Duplicate-name guard: if another path already uses the resolved
+ * `name`, throw {@link RegistryNameCollisionError} unless
+ * `opts.allowDuplicateName` is set. The guard ONLY fires when the user explicitly passed a
+ * `name`; un-aliased basename collisions continue to register silently
+ * so existing users who don't know about `--name` see no behaviour
+ * change.
+ *
+ * Returns the `name` that was actually written to the registry — the
+ * caller can re-use it to keep AGENTS.md / skill files aligned with the
+ * MCP-visible repo name (#979).
  */
-export const registerRepo = async (repoPath: string, meta: RepoMeta): Promise<void> => {
+export const registerRepo = async (
+  repoPath: string,
+  meta: RepoMeta,
+  opts?: RegisterRepoOptions,
+): Promise<string> => {
   const resolved = path.resolve(repoPath);
-  const name = path.basename(resolved);
   const { storagePath } = getStoragePaths(resolved);
 
   const entries = await readRegistry();
-  const existing = entries.findIndex((e) => {
+  const existingIdx = entries.findIndex((e) => {
     const a = path.resolve(e.path);
     const b = resolved;
     return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
   });
+  const existing = existingIdx >= 0 ? entries[existingIdx] : null;
+
+  // Precedence: explicit --name > preserved alias > remote-inferred > basename.
+  // Skip the `git config` subprocess entirely when --name was passed —
+  // the remote isn't consulted in that case.
+  let name: string;
+  let isPreservedAlias = false;
+  if (opts?.name !== undefined) {
+    name = opts.name;
+  } else {
+    // Compute the remote-derived name at most once. It feeds both the
+    // alias-preservation check (`hasCustomAlias` needs it to distinguish
+    // a sticky user alias from a previously-stored remote inference) and
+    // the fallback name when neither --name nor a preserved alias apply.
+    const inferred = getInferredRepoName(resolved);
+    if (existing && hasCustomAlias(existing, inferred)) {
+      name = existing.name;
+      isPreservedAlias = true;
+    } else {
+      name = inferred ?? path.basename(resolved);
+    }
+  }
+
+  // Duplicate-name guard: only fire when the user EXPLICITLY asked for
+  // this name (via opts.name or a preserved alias). Unqualified basename
+  // and remote-inferred collisions are preserved for backward-compat —
+  // they still register, and the user sees the ambiguity at `-r` / `list`
+  // resolution time (which is already improved by the disambiguated error
+  // messages and list output #829 ships).
+  const explicitName = opts?.name !== undefined || isPreservedAlias;
+  if (explicitName && !opts?.allowDuplicateName) {
+    const collidingEntry = entries.find(
+      (e, i) =>
+        i !== existingIdx &&
+        e.name.toLowerCase() === name.toLowerCase() &&
+        path.resolve(e.path) !== resolved,
+    );
+    if (collidingEntry) {
+      throw new RegistryNameCollisionError(name, collidingEntry.path, resolved);
+    }
+  }
 
   const entry: RegistryEntry = {
     name,
@@ -269,13 +409,14 @@ export const registerRepo = async (repoPath: string, meta: RepoMeta): Promise<vo
     stats: meta.stats,
   };
 
-  if (existing >= 0) {
-    entries[existing] = entry;
+  if (existingIdx >= 0) {
+    entries[existingIdx] = entry;
   } else {
     entries.push(entry);
   }
 
   await writeRegistry(entries);
+  return name;
 };
 
 /**
diff --git a/gitnexus/src/types/pipeline.ts b/gitnexus/src/types/pipeline.ts
index d8b4cbd69..331bdd6fc 100644
--- a/gitnexus/src/types/pipeline.ts
+++ b/gitnexus/src/types/pipeline.ts
@@ -11,4 +11,10 @@ export interface PipelineResult {
   totalFileCount: number;
   communityResult?: CommunityDetectionResult;
   processResult?: ProcessDetectionResult;
+  /**
+   * True if the parse phase spawned a worker pool for this run. False means
+   * the sequential fallback handled every chunk. Primarily a test affordance
+   * so regression suites can prove which path executed.
+   */
+  usedWorkerPool: boolean;
 }
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/__init__.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/admin.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/admin.py
new file mode 100644
index 000000000..8c38f3f3d
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/admin.py
@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/apps.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/apps.py
new file mode 100644
index 000000000..9b3fc5a44
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/apps.py
@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+    name = 'accounts'
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/migrations/__init__.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/migrations/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/models.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/models.py
new file mode 100644
index 000000000..8d3ec18e5
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/models.py
@@ -0,0 +1,5 @@
+from django.db import models
+
+
+class Customer(models.Model):
+    email = models.EmailField(unique=True)
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/tests.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/tests.py
new file mode 100644
index 000000000..7ce503c2d
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/tests.py
@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# Create your tests here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/views.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/views.py
new file mode 100644
index 000000000..91ea44a21
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/accounts/views.py
@@ -0,0 +1,3 @@
+from django.shortcuts import render
+
+# Create your views here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/__init__.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/admin.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/admin.py
new file mode 100644
index 000000000..8c38f3f3d
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/admin.py
@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/apps.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/apps.py
new file mode 100644
index 000000000..21d70f8e0
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/apps.py
@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class BillingConfig(AppConfig):
+    name = 'billing'
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/migrations/__init__.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/migrations/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/models.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/models.py
new file mode 100644
index 000000000..a3ea3f967
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/models.py
@@ -0,0 +1,9 @@
+from django.db import models
+from accounts.models import Customer
+
+
+class Invoice(models.Model):
+    customer = models.ForeignKey(
+        Customer, on_delete=models.CASCADE, related_name="invoices"
+    )
+    total_cents = models.PositiveIntegerField()
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/tests.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/tests.py
new file mode 100644
index 000000000..7ce503c2d
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/tests.py
@@ -0,0 +1,3 @@
+from django.test import TestCase
+
+# Create your tests here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/views.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/views.py
new file mode 100644
index 000000000..91ea44a21
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/billing/views.py
@@ -0,0 +1,3 @@
+from django.shortcuts import render
+
+# Create your views here.
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/__init__.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/asgi.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/asgi.py
new file mode 100644
index 000000000..ffbb5f509
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/asgi.py
@@ -0,0 +1,16 @@
+"""
+ASGI config for config project.
+
+It exposes the ASGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/6.0/howto/deployment/asgi/
+"""
+
+import os
+
+from django.core.asgi import get_asgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+
+application = get_asgi_application()
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/settings.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/settings.py
new file mode 100644
index 000000000..9465a6ebe
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/settings.py
@@ -0,0 +1,119 @@
+"""
+Django settings for config project.
+
+Generated by 'django-admin startproject' using Django 6.0.4.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/6.0/topics/settings/
+
+For the full list of settings and their values, see
+https://docs.djangoproject.com/en/6.0/ref/settings/
+"""
+
+from pathlib import Path
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+# Quick-start development settings - unsuitable for production
+# See https://docs.djangoproject.com/en/6.0/howto/deployment/checklist/
+
+# SECURITY WARNING: keep the secret key used in production secret!
+SECRET_KEY = "django-insecure-l(ss*u=y_x)vb!nuq*s1$eayoopfz4^kv2@s&o7wh_6==4&9#^"
+
+# SECURITY WARNING: don't run with debug turned on in production!
+DEBUG = True
+
+ALLOWED_HOSTS = []
+
+
+# Application definition
+
+INSTALLED_APPS = [
+    "django.contrib.admin",
+    "django.contrib.auth",
+    "django.contrib.contenttypes",
+    "django.contrib.sessions",
+    "django.contrib.messages",
+    "django.contrib.staticfiles",
+    "accounts.apps.AccountsConfig",
+    "billing.apps.BillingConfig",
+]
+
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.common.CommonMiddleware",
+    "django.middleware.csrf.CsrfViewMiddleware",
+    "django.contrib.auth.middleware.AuthenticationMiddleware",
+    "django.contrib.messages.middleware.MessageMiddleware",
+    "django.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ROOT_URLCONF = "config.urls"
+
+TEMPLATES = [
+    {
+        "BACKEND": "django.template.backends.django.DjangoTemplates",
+        "DIRS": [],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            "context_processors": [
+                "django.template.context_processors.request",
+                "django.contrib.auth.context_processors.auth",
+                "django.contrib.messages.context_processors.messages",
+            ],
+        },
+    },
+]
+
+WSGI_APPLICATION = "config.wsgi.application"
+
+
+# Database
+# https://docs.djangoproject.com/en/6.0/ref/settings/#databases
+
+DATABASES = {
+    "default": {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": BASE_DIR / "db.sqlite3",
+    }
+}
+
+
+# Password validation
+# https://docs.djangoproject.com/en/6.0/ref/settings/#auth-password-validators
+
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        "NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.CommonPasswordValidator",
+    },
+    {
+        "NAME": "django.contrib.auth.password_validation.NumericPasswordValidator",
+    },
+]
+
+
+# Internationalization
+# https://docs.djangoproject.com/en/6.0/topics/i18n/
+
+LANGUAGE_CODE = "en-us"
+
+TIME_ZONE = "UTC"
+
+USE_I18N = True
+
+USE_TZ = True
+
+
+# Static files (CSS, JavaScript, Images)
+# https://docs.djangoproject.com/en/6.0/howto/static-files/
+
+STATIC_URL = "static/"
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/urls.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/urls.py
new file mode 100644
index 000000000..c74036a0c
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/urls.py
@@ -0,0 +1,22 @@
+"""
+URL configuration for config project.
+
+The `urlpatterns` list routes URLs to views. For more information please see:
+    https://docs.djangoproject.com/en/6.0/topics/http/urls/
+Examples:
+Function views
+    1. Add an import:  from my_app import views
+    2. Add a URL to urlpatterns:  path('', views.home, name='home')
+Class-based views
+    1. Add an import:  from other_app.views import Home
+    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
+Including another URLconf
+    1. Import the include() function: from django.urls import include, path
+    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
+"""
+from django.contrib import admin
+from django.urls import path
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+]
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/wsgi.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/wsgi.py
new file mode 100644
index 000000000..4ced57491
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/config/wsgi.py
@@ -0,0 +1,16 @@
+"""
+WSGI config for config project.
+
+It exposes the WSGI callable as a module-level variable named ``application``.
+
+For more information on this file, see
+https://docs.djangoproject.com/en/6.0/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+
+application = get_wsgi_application()
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/manage.py b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/manage.py
new file mode 100755
index 000000000..8e7ac79b9
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/manage.py
@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+
+def main():
+    """Run administrative tasks."""
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings')
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/requirements.txt b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/requirements.txt
new file mode 100644
index 000000000..6f45e8236
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/python-django-app-imports/requirements.txt
@@ -0,0 +1 @@
+Django==6.0.4
diff --git a/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/account.rb b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/account.rb
new file mode 100644
index 000000000..a0193f83c
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/account.rb
@@ -0,0 +1,25 @@
+require_relative 'greetable'
+require_relative 'logger_mixin'
+require_relative 'prepended_override'
+
+class Account
+  include Greetable
+  extend LoggerMixin
+  prepend PrependedOverride
+
+  def serialize
+    "account"
+  end
+
+  def call_greet
+    greet
+  end
+
+  def call_serialize
+    serialize
+  end
+
+  def call_prepended_marker
+    prepended_marker
+  end
+end
diff --git a/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/greetable.rb b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/greetable.rb
new file mode 100644
index 000000000..84b8b81cc
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/greetable.rb
@@ -0,0 +1,5 @@
+module Greetable
+  def greet
+    "hello from greetable"
+  end
+end
diff --git a/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/logger_mixin.rb b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/logger_mixin.rb
new file mode 100644
index 000000000..48ea441f1
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/logger_mixin.rb
@@ -0,0 +1,5 @@
+module LoggerMixin
+  def log(msg)
+    puts msg
+  end
+end
diff --git a/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/prepended_override.rb b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/prepended_override.rb
new file mode 100644
index 000000000..c2ab67107
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/prepended_override.rb
@@ -0,0 +1,13 @@
+module PrependedOverride
+  def serialize
+    "prepended"
+  end
+
+  # Unique method name not defined elsewhere in the fixture. Calling this
+  # from Account proves the prepend heritage edge adds PrependedOverride to
+  # the MRO at all. Shadowed-name resolution (prepend > self) is deferred —
+  # see plan 001's "Deferred to Separate Tasks: Ruby MRO kind-ordering".
+  def prepended_marker
+    "prepended-only"
+  end
+end
diff --git a/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/usage.rb b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/usage.rb
new file mode 100644
index 000000000..9eb37dd8b
--- /dev/null
+++ b/gitnexus/test/fixtures/lang-resolution/ruby-sequential-mixin/lib/usage.rb
@@ -0,0 +1,10 @@
+require_relative 'account'
+
+class Usage
+  def run
+    a = Account.new
+    a.call_greet
+    a.call_serialize
+    Account.log("from Usage")
+  end
+end
diff --git a/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json b/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json
index 7c9818696..0d66fd3a7 100644
--- a/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json
+++ b/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json
@@ -1,29 +1,29 @@
 {
   "capture": "initial capture (U8, post-U1–U7)",
   "fixture": "mini-repo",
-  "totalFileCount": 9,
-  "symbols": 57,
-  "relationships": 92,
+  "totalFileCount": 7,
+  "symbols": 37,
+  "relationships": 74,
   "processes": 4,
   "byType": {
     "Class": 1,
     "Community": 4,
-    "File": 9,
+    "Const": 4,
+    "File": 7,
     "Folder": 1,
     "Function": 12,
     "Interface": 3,
     "Method": 1,
-    "Process": 4,
-    "Section": 22
+    "Process": 4
   },
   "byRelType": {
     "CALLS": 9,
-    "CONTAINS": 29,
-    "DEFINES": 17,
+    "CONTAINS": 7,
+    "DEFINES": 21,
     "HAS_METHOD": 1,
     "IMPORTS": 12,
     "MEMBER_OF": 12,
     "STEP_IN_PROCESS": 12
   },
-  "edgeDigest": "fdf012d4b4197377ab43e27217f9fe08ec46352945140f8b3406dacc3294b715"
+  "edgeDigest": "a418debec537cf959fe56fd1fbbbfb59a640398cdb3c61ce0bcb8056c1f45110"
 }
diff --git a/gitnexus/test/integration/cli-e2e.test.ts b/gitnexus/test/integration/cli-e2e.test.ts
index 678d8f271..844e3978d 100644
--- a/gitnexus/test/integration/cli-e2e.test.ts
+++ b/gitnexus/test/integration/cli-e2e.test.ts
@@ -20,7 +20,22 @@ import { createRequire } from 'module';
 const testDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(testDir, '../..');
 const cliEntry = path.join(repoRoot, 'src/cli/index.ts');
-const MINI_REPO = path.resolve(testDir, '..', 'fixtures', 'mini-repo');
+const FIXTURE_SRC = path.resolve(testDir, '..', 'fixtures', 'mini-repo');
+
+// `MINI_REPO` is a *per-run temp copy* of the fixture, not the shared
+// source. Writing into the shared source races with other suites that
+// ingest it read-only (pipeline-graph-golden, pipeline.test) — those
+// suites copy the source to their own tmp dir but the copy happens at
+// `beforeAll`, so if this suite's analyze has already created AGENTS.md
+// / CLAUDE.md / .claude/ in the source when the other suite's cpSync
+// runs, the pollution is captured before the isolation kicks in.
+//
+// The deterministic fix: this suite never touches the shared source.
+// `beforeAll` copies the fixture to a fresh mkdtemp'd directory whose
+// basename is `mini-repo` (so `--repo mini-repo` lookup by basename
+// still works), `afterAll` rms the parent tmpdir.
+let MINI_REPO: string;
+let tmpParent: string;
 
 // Absolute file:// URL to tsx loader — needed when spawning CLI with cwd
 // outside the project tree (bare 'tsx' specifier won't resolve there).
@@ -31,38 +46,39 @@ const tsxPkgDir = path.dirname(_require.resolve('tsx/package.json'));
 const tsxImportUrl = pathToFileURL(path.join(tsxPkgDir, 'dist', 'loader.mjs')).href;
 
 beforeAll(() => {
+  // Copy the fixture into an isolated tmpdir named `mini-repo` so that the
+  // `--repo mini-repo` CLI arg (which matches by basename) still works.
+  tmpParent = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-cli-e2e-'));
+  MINI_REPO = path.join(tmpParent, 'mini-repo');
+  fs.cpSync(FIXTURE_SRC, MINI_REPO, { recursive: true });
+
   // Initialize mini-repo as a git repo so the CLI analyze command
   // can run the full pipeline (it requires a .git directory).
-  const gitDir = path.join(MINI_REPO, '.git');
-  if (!fs.existsSync(gitDir)) {
-    spawnSync('git', ['init'], { cwd: MINI_REPO, stdio: 'pipe' });
-    spawnSync('git', ['add', '-A'], { cwd: MINI_REPO, stdio: 'pipe' });
-    spawnSync('git', ['commit', '-m', 'initial commit'], {
-      cwd: MINI_REPO,
-      stdio: 'pipe',
-      env: {
-        ...process.env,
-        GIT_AUTHOR_NAME: 'test',
-        GIT_AUTHOR_EMAIL: 'test@test',
-        GIT_COMMITTER_NAME: 'test',
-        GIT_COMMITTER_EMAIL: 'test@test',
-      },
-    });
-  }
+  spawnSync('git', ['init'], { cwd: MINI_REPO, stdio: 'pipe' });
+  spawnSync('git', ['add', '-A'], { cwd: MINI_REPO, stdio: 'pipe' });
+  spawnSync('git', ['commit', '-m', 'initial commit'], {
+    cwd: MINI_REPO,
+    stdio: 'pipe',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'test',
+      GIT_AUTHOR_EMAIL: 'test@test',
+      GIT_COMMITTER_NAME: 'test',
+      GIT_COMMITTER_EMAIL: 'test@test',
+    },
+  });
 });
 
 afterAll(() => {
-  // Clean up .git/ and .gitnexus/ directories created during the test
-  for (const dir of ['.git', '.gitnexus']) {
-    const fullPath = path.join(MINI_REPO, dir);
-    if (fs.existsSync(fullPath)) {
-      fs.rmSync(fullPath, { recursive: true, force: true });
-    }
+  // Entire tmp copy goes away — no selective cleanup needed. The shared
+  // `test/fixtures/mini-repo/` source was never touched.
+  if (tmpParent) {
+    fs.rmSync(tmpParent, { recursive: true, force: true });
   }
 });
 
 function runCli(command: string, cwd: string, timeoutMs = 15000) {
-  return spawnSync(process.execPath, ['--import', 'tsx', cliEntry, command], {
+  return spawnSync(process.execPath, ['--import', tsxImportUrl, cliEntry, command], {
     cwd,
     encoding: 'utf8',
     timeout: timeoutMs,
@@ -82,7 +98,7 @@ function runCli(command: string, cwd: string, timeoutMs = 15000) {
  * can pass flags (e.g. --help) or omit a command entirely.
  */
 function runCliRaw(extraArgs: string[], cwd: string, timeoutMs = 15000) {
-  return spawnSync(process.execPath, ['--import', 'tsx', cliEntry, ...extraArgs], {
+  return spawnSync(process.execPath, ['--import', tsxImportUrl, cliEntry, ...extraArgs], {
     cwd,
     encoding: 'utf8',
     timeout: timeoutMs,
@@ -94,6 +110,55 @@ function runCliRaw(extraArgs: string[], cwd: string, timeoutMs = 15000) {
   });
 }
 
+/**
+ * Like runCliRaw but accepts extra env vars. Used by tests that need to
+ * isolate the global registry via GITNEXUS_HOME so they don't touch the
+ * developer / CI agent's real ~/.gitnexus/registry.json (#829).
+ */
+function runCliWithEnv(
+  extraArgs: string[],
+  cwd: string,
+  extraEnv: Record<string, string>,
+  timeoutMs = 15000,
+) {
+  return spawnSync(process.execPath, ['--import', tsxImportUrl, cliEntry, ...extraArgs], {
+    cwd,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(),
+      ...extraEnv,
+    },
+  });
+}
+
+/**
+ * Create a fresh git-initialised throwaway repo at `<parentTmp>/<basename>`
+ * and return its path. Used for tests that need multiple repos whose
+ * basenames intentionally collide (#829 reproduction).
+ */
+function makeMiniRepoCopy(basename: string, prefix: string): string {
+  const parent = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  const repo = path.join(parent, basename);
+  fs.cpSync(FIXTURE_SRC, repo, { recursive: true });
+  spawnSync('git', ['init'], { cwd: repo, stdio: 'pipe' });
+  spawnSync('git', ['add', '-A'], { cwd: repo, stdio: 'pipe' });
+  spawnSync('git', ['commit', '-m', 'initial commit'], {
+    cwd: repo,
+    stdio: 'pipe',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'test',
+      GIT_AUTHOR_EMAIL: 'test@test',
+      GIT_COMMITTER_NAME: 'test',
+      GIT_COMMITTER_EMAIL: 'test@test',
+    },
+  });
+  return repo;
+}
+
 describe('CLI end-to-end', () => {
   it('status command exits cleanly', () => {
     const result = runCli('status', MINI_REPO);
@@ -128,6 +193,158 @@ describe('CLI end-to-end', () => {
     expect(fs.statSync(gitnexusDir).isDirectory()).toBe(true);
   });
 
+  // ─── analyze --name <alias> + --allow-duplicate-name (#829) ──────
+  //
+  // End-to-end regression guard for the name-collision feature:
+  //   1. `analyze --name X` persists the alias to ~/.gitnexus/registry.json
+  //   2. A second `analyze --name X` on a DIFFERENT path is rejected with
+  //      a collision error (exit code 1, "already used" in output)
+  //   3. `analyze --name X --allow-duplicate-name` bypasses the guard;
+  //      both entries coexist in registry.json
+  //   4. Pipeline-re-index flags (e.g. --skills) WITHOUT
+  //      --allow-duplicate-name must STILL hit the collision guard —
+  //      the bypass must stay gated on its dedicated flag so it isn't
+  //      silently triggered by unrelated pipeline signals
+  //      (review round 2/3 design decision).
+  //
+  // This test invokes the real CLI → runFullAnalysis → registerRepo
+  // chain, so any wiring regression fails here.
+  describe('analyze --name <alias> and --allow-duplicate-name (#829)', () => {
+    // Path-equality assertions across CLI spawn boundaries are fragile
+    // cross-platform:
+    //   - macOS: os.tmpdir() returns /var/folders/...; child processes
+    //     resolve the symlink to /private/var/folders/...
+    //   - Windows: os.tmpdir() on GitHub runners returns 8.3 short-name
+    //     form (C:\Users\RUNNER~1\...); the child sees the long form
+    //     (C:\Users\runneradmin\...). fs.realpathSync does NOT reliably
+    //     expand 8.3 to long form.
+    // Rather than fight the platform-path quagmire, we assert STRUCTURAL
+    // properties: entry count, alias value, path basename, path
+    // distinctness. That covers the behavior this test is here to
+    // protect without depending on exact-string path equality.
+
+    it('--name alias stores; collision rejects; --allow-duplicate-name bypasses', () => {
+      // Isolate the global registry so this test never touches the
+      // developer's real ~/.gitnexus.
+      const gnHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-home-'));
+
+      // Two mini-repo copies whose basenames intentionally collide.
+      const repoA = makeMiniRepoCopy('collide-app', 'gn-collide-a-');
+      const repoB = makeMiniRepoCopy('collide-app', 'gn-collide-b-');
+      const parentA = path.dirname(repoA);
+      const parentB = path.dirname(repoB);
+
+      try {
+        // Step 1: analyze repoA with --name shared → registry entry created.
+        const r1 = runCliWithEnv(
+          ['analyze', '--name', 'shared'],
+          repoA,
+          { GITNEXUS_HOME: gnHome },
+          60000,
+        );
+        if (r1.status === null) return; // CI timeout tolerance
+        expect(
+          r1.status,
+          [`step 1 exited with ${r1.status}`, `stdout: ${r1.stdout}`, `stderr: ${r1.stderr}`].join(
+            '\n',
+          ),
+        ).toBe(0);
+
+        const registryPath = path.join(gnHome, 'registry.json');
+        const afterStep1 = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+        expect(Array.isArray(afterStep1)).toBe(true);
+        expect(afterStep1).toHaveLength(1);
+        expect(afterStep1[0].name).toBe('shared');
+        expect(path.basename(afterStep1[0].path)).toBe('collide-app');
+
+        // Step 2: analyze repoB with the SAME --name → collision error.
+        const r2 = runCliWithEnv(
+          ['analyze', '--name', 'shared'],
+          repoB,
+          { GITNEXUS_HOME: gnHome },
+          60000,
+        );
+        if (r2.status === null) return;
+        expect(r2.status).toBe(1);
+        const r2Output = `${r2.stdout}${r2.stderr}`;
+        expect(r2Output).toMatch(/Registry name collision|already used/i);
+
+        // Registry still has just the first entry — step 2 must not have
+        // silently added, overwritten, or corrupted anything.
+        const afterStep2 = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+        expect(afterStep2).toHaveLength(1);
+        // Registry still has only the step-1 entry — the failed call
+        // must not have silently added, overwritten, or corrupted state.
+        expect(afterStep2[0].path).toBe(afterStep1[0].path);
+
+        // Step 3: REGRESSION GUARD for the missing collision-bypass wire
+        // (originally a --force passthrough bug; per review round 3 the
+        // bypass moved to its own --allow-duplicate-name flag to avoid
+        // conflating it with pipeline re-index).
+        const r3 = runCliWithEnv(
+          ['analyze', '--name', 'shared', '--allow-duplicate-name'],
+          repoB,
+          { GITNEXUS_HOME: gnHome },
+          60000,
+        );
+        if (r3.status === null) return;
+        expect(
+          r3.status,
+          [
+            `step 3 (--allow-duplicate-name bypass) exited with ${r3.status}`,
+            `stdout: ${r3.stdout}`,
+            `stderr: ${r3.stderr}`,
+          ].join('\n'),
+        ).toBe(0);
+
+        const afterStep3 = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+        expect(afterStep3).toHaveLength(2);
+        expect(afterStep3.every((e: { name: string }) => e.name === 'shared')).toBe(true);
+        // Both entries point to distinct paths (we registered two different
+        // repos under the same alias) and both have the right basename.
+        const step3Basenames = afterStep3.map((e: { path: string }) => path.basename(e.path));
+        expect(step3Basenames).toEqual(['collide-app', 'collide-app']);
+        const step3Paths = new Set(afterStep3.map((e: { path: string }) => e.path));
+        expect(step3Paths.size).toBe(2);
+        // One of the two entries is the original from step 1 — unchanged.
+        expect(afterStep3.map((e: { path: string }) => e.path)).toContain(afterStep1[0].path);
+
+        // Step 4: REGRESSION GUARD for the design decision in review
+        // round 2/3 — pipeline-re-index flags must NOT bypass the
+        // registry collision guard. `--skills` triggers pipeline
+        // re-run (skills generation needs a fresh pipelineResult) but
+        // must leave the registry guard in force. Bypass requires the
+        // explicit --allow-duplicate-name flag.
+        const repoC = makeMiniRepoCopy('collide-app', 'gn-collide-c-');
+        const parentC = path.dirname(repoC);
+        try {
+          const r4 = runCliWithEnv(
+            ['analyze', '--name', 'shared', '--skills'],
+            repoC,
+            { GITNEXUS_HOME: gnHome },
+            60000,
+          );
+          if (r4.status === null) return;
+          expect(r4.status).toBe(1);
+          const r4Output = `${r4.stdout}${r4.stderr}`;
+          expect(r4Output).toMatch(/Registry name collision|already used/i);
+          // The error hint should point at the new flag.
+          expect(r4Output).toMatch(/--allow-duplicate-name/);
+
+          // Registry unchanged — still only A + B under "shared".
+          const afterStep4 = JSON.parse(fs.readFileSync(registryPath, 'utf-8'));
+          expect(afterStep4).toHaveLength(2);
+        } finally {
+          fs.rmSync(parentC, { recursive: true, force: true });
+        }
+      } finally {
+        fs.rmSync(gnHome, { recursive: true, force: true });
+        fs.rmSync(parentA, { recursive: true, force: true });
+        fs.rmSync(parentB, { recursive: true, force: true });
+      }
+    }, 360000); // 6-min outer budget (4 × ~60s analyze calls + fixture setup)
+  });
+
   describe('unhappy path', () => {
     it('exits with error when no command is given', () => {
       const result = runCliRaw([], MINI_REPO);
@@ -188,9 +405,11 @@ describe('CLI end-to-end', () => {
     }
 
     it('status on non-indexed repo reports not indexed', () => {
-      // MINI_REPO is inside the project tree so findRepo() walks up and
-      // finds the parent project's .gitnexus. Use an isolated temp git
-      // repo to guarantee no .gitnexus exists anywhere in the path.
+      // Even though MINI_REPO is now in an isolated tmpdir, previous tests
+      // in this suite may have created MINI_REPO/.gitnexus via analyze,
+      // and findRepo() walks up so any `.gitnexus` along the path still
+      // counts. This test needs a GUARANTEED pristine repo to assert the
+      // "not indexed" output, so it mints its own throwaway tmp git repo.
       const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-noindex-'));
       try {
         spawnSync('git', ['init'], { cwd: tmpDir, stdio: 'pipe' });
@@ -408,7 +627,7 @@ describe('CLI end-to-end', () => {
           process.execPath,
           [
             '--import',
-            'tsx',
+            tsxImportUrl,
             cliEntry,
             'cypher',
             'MATCH (n) RETURN n LIMIT 500',
@@ -467,7 +686,7 @@ describe('CLI end-to-end', () => {
       return new Promise<void>((resolve, reject) => {
         const child = spawn(
           process.execPath,
-          ['--import', 'tsx', cliEntry, 'eval-server', '--port', '0', '--idle-timeout', '3'],
+          ['--import', tsxImportUrl, cliEntry, 'eval-server', '--port', '0', '--idle-timeout', '3'],
           {
             cwd: MINI_REPO,
             stdio: ['ignore', 'pipe', 'pipe'],
diff --git a/gitnexus/test/integration/heritage-extractor-wiring.test.ts b/gitnexus/test/integration/heritage-extractor-wiring.test.ts
new file mode 100644
index 000000000..47e62fda3
--- /dev/null
+++ b/gitnexus/test/integration/heritage-extractor-wiring.test.ts
@@ -0,0 +1,186 @@
+/**
+ * Integration tests for heritage extractor wiring via real tree-sitter output.
+ *
+ * Complements test/unit/heritage-extraction.test.ts, which exercises the
+ * configs and factory against mocked AST nodes. These tests drive the same
+ * extractors against **real** tree-sitter parses so that a drift between
+ * the per-language tree-sitter queries and the extractor configs would be
+ * caught here even if mocked unit tests keep passing.
+ *
+ * Context: PR #890 review follow-up. See
+ * docs/plans/2026-04-16-005-refactor-pr890-review-followups-plan.md Unit 3a.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import Parser from 'tree-sitter';
+import { loadParser, loadLanguage } from '../../src/core/tree-sitter/parser-loader.js';
+import { SupportedLanguages } from 'gitnexus-shared';
+import { getProvider } from '../../src/core/ingestion/languages/index.js';
+import type { CaptureMap } from '../../src/core/ingestion/language-provider.js';
+import { rubyHeritageConfig } from '../../src/core/ingestion/heritage-extractors/configs/ruby.js';
+
+let parser: Parser;
+
+beforeAll(async () => {
+  parser = await loadParser();
+});
+
+/** Run the provider's tree-sitter queries over `code` and yield per-match capture maps. */
+function runQueries(code: string, lang: SupportedLanguages): CaptureMap[] {
+  const tree = parser.parse(code);
+  const provider = getProvider(lang);
+  const query = new Parser.Query(parser.getLanguage(), provider.treeSitterQueries);
+  const matches = query.matches(tree.rootNode);
+
+  return matches.map((match) => {
+    const captureMap: Record<string, any> = {};
+    for (const capture of match.captures) {
+      captureMap[capture.name] = capture.node;
+    }
+    return captureMap as unknown as CaptureMap;
+  });
+}
+
+/** Parse `code` and return the first AST node whose type matches `nodeType`. */
+function findFirstNode(code: string, nodeType: string): any | null {
+  const tree = parser.parse(code);
+  const stack: any[] = [tree.rootNode];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node.type === nodeType) return node;
+    for (let i = node.childCount - 1; i >= 0; i--) {
+      stack.push(node.child(i));
+    }
+  }
+  return null;
+}
+
+// ─── Ruby extractFromCall — real AST ─────────────────────────────────────────
+
+describe('Ruby heritage extractFromCall (real tree-sitter AST)', () => {
+  beforeAll(async () => {
+    await loadLanguage(SupportedLanguages.Ruby);
+  });
+
+  const extract = rubyHeritageConfig.callBasedHeritage!.extract;
+
+  it('3a-1: class Foo; include Bar; end → single include entry', () => {
+    const code = `class Foo\n  include Bar\nend\n`;
+    const callNode = findFirstNode(code, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('include', callNode, 'foo.rb');
+    expect(result).toEqual([{ className: 'Foo', parentName: 'Bar', kind: 'include' }]);
+  });
+
+  it('3a-2: include A, B, C produces three entries, one per constant arg', () => {
+    const code = `class Multi\n  include A, B, C\nend\n`;
+    const callNode = findFirstNode(code, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('include', callNode, 'multi.rb');
+    expect(result).toEqual([
+      { className: 'Multi', parentName: 'A', kind: 'include' },
+      { className: 'Multi', parentName: 'B', kind: 'include' },
+      { className: 'Multi', parentName: 'C', kind: 'include' },
+    ]);
+  });
+
+  it('3a-3: extend ActiveSupport::Concern (scope_resolution arg)', () => {
+    const code = `class Post\n  extend ActiveSupport::Concern\nend\n`;
+    const callNode = findFirstNode(code, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('extend', callNode, 'post.rb');
+    expect(result).toEqual([
+      { className: 'Post', parentName: 'ActiveSupport::Concern', kind: 'extend' },
+    ]);
+  });
+
+  it('3a-4: nested module/class resolves to the nearest class, not the module', () => {
+    const code = `module Outer\n  class Inner\n    include X\n  end\nend\n`;
+    const callNode = findFirstNode(code, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('include', callNode, 'nested.rb');
+    expect(result).toEqual([{ className: 'Inner', parentName: 'X', kind: 'include' }]);
+  });
+
+  it('3a-5: top-level include with no enclosing class returns []', () => {
+    const code = `include Foo\n`;
+    // NOTE: `include Foo` at top level may not produce a `call` node in tree-sitter-ruby;
+    // it often lowers to an `identifier` body_statement. Construct a realistic top-level
+    // call (`Kernel.include Foo`) to exercise the no-enclosing-class branch.
+    const fallback = `Kernel.include(Foo)\n`;
+    const callNode = findFirstNode(fallback, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('include', callNode, 'top.rb');
+    expect(result).toEqual([]);
+  });
+
+  it('prepend inside a module uses the module as enclosingClass', () => {
+    const code = `module AppHelper\n  prepend Logged\nend\n`;
+    const callNode = findFirstNode(code, 'call');
+    expect(callNode).not.toBeNull();
+
+    const result = extract('prepend', callNode, 'helper.rb');
+    expect(result).toEqual([{ className: 'AppHelper', parentName: 'Logged', kind: 'prepend' }]);
+  });
+});
+
+// ─── TypeScript heritage.extract — real AST + real query captures ────────────
+
+describe('TypeScript heritage extract (real tree-sitter captures)', () => {
+  beforeAll(async () => {
+    await loadLanguage(SupportedLanguages.TypeScript);
+  });
+
+  it('3a-6: class Child extends Parent {} produces one extends entry', () => {
+    const code = `class Child extends Parent {}\n`;
+    const captureMaps = runQueries(code, SupportedLanguages.TypeScript);
+    const heritageMatches = captureMaps.filter((m) => (m as any)['heritage.class']);
+    expect(heritageMatches.length).toBeGreaterThan(0);
+
+    const provider = getProvider(SupportedLanguages.TypeScript);
+    const extractor = provider.heritageExtractor!;
+    const items = extractor.extract(heritageMatches[0], {
+      filePath: 'child.ts',
+      language: SupportedLanguages.TypeScript,
+    });
+
+    expect(items).toEqual([{ className: 'Child', parentName: 'Parent', kind: 'extends' }]);
+  });
+
+  it('3a-7: class Child extends Parent implements IFoo {} yields extends + implements', () => {
+    const code = `interface IFoo {}\nclass Parent {}\nclass Child extends Parent implements IFoo {}\n`;
+    const captureMaps = runQueries(code, SupportedLanguages.TypeScript);
+    const heritageMatches = captureMaps.filter(
+      (m) =>
+        (m as any)['heritage.class'] &&
+        ((m as any)['heritage.extends'] || (m as any)['heritage.implements']),
+    );
+    expect(heritageMatches.length).toBeGreaterThan(0);
+
+    const provider = getProvider(SupportedLanguages.TypeScript);
+    const extractor = provider.heritageExtractor!;
+
+    const kinds = new Set<string>();
+    const parents = new Set<string>();
+    for (const cm of heritageMatches) {
+      const items = extractor.extract(cm, {
+        filePath: 'child.ts',
+        language: SupportedLanguages.TypeScript,
+      });
+      for (const item of items) {
+        expect(item.className).toBe('Child');
+        kinds.add(item.kind);
+        parents.add(item.parentName);
+      }
+    }
+
+    expect(kinds).toContain('extends');
+    expect(kinds).toContain('implements');
+    expect(parents).toContain('Parent');
+    expect(parents).toContain('IFoo');
+  });
+});
diff --git a/gitnexus/test/integration/local-backend-calltool.test.ts b/gitnexus/test/integration/local-backend-calltool.test.ts
index 55e4110f3..b32aad270 100644
--- a/gitnexus/test/integration/local-backend-calltool.test.ts
+++ b/gitnexus/test/integration/local-backend-calltool.test.ts
@@ -104,6 +104,14 @@ withTestLbugDB(
           (result.process_symbols?.length || 0) +
           (result.definitions?.length || 0);
         expect(totalResults).toBeGreaterThanOrEqual(1);
+
+        // #553: query response carries per-phase timing metadata.
+        expect(result.timing).toBeDefined();
+        expect(typeof result.timing.wall).toBe('number');
+        expect(result.timing.wall).toBeGreaterThanOrEqual(0);
+        // At least one of the search phases must have fired for any
+        // non-error response — bm25 and/or vector always runs.
+        expect(result.timing.bm25 ?? result.timing.vector).toBeGreaterThanOrEqual(0);
       });
 
       it('unknown tool throws', async () => {
@@ -141,12 +149,20 @@ withTestLbugDB(
       });
 
       it('filters by OVERRIDES only', async () => {
+        // The seed has two Method nodes named 'authenticate' (AuthService's
+        // override and BaseService's base). Per #470, `impact` now returns
+        // a ranked-ambiguous response when the target name hits multiple
+        // symbols, so we must disambiguate with file_path to get the
+        // AuthService override (the one with the outgoing METHOD_OVERRIDES
+        // edge we want to follow downstream).
         const result = await backend.callTool('impact', {
           target: 'authenticate',
+          file_path: 'src/auth.ts',
           direction: 'downstream',
           relationTypes: ['METHOD_OVERRIDES'],
         });
         expect(result).not.toHaveProperty('error');
+        expect(result.status).not.toBe('ambiguous');
         // AuthService.authenticate overrides BaseService.authenticate
         expect(result.impactedCount).toBeGreaterThanOrEqual(1);
         const d1 = result.byDepth[1] || result.byDepth['1'] || [];
@@ -158,12 +174,15 @@ withTestLbugDB(
         // Pass the LEGACY alias 'OVERRIDES' — impactByUid should flatMap-expand
         // it to ['OVERRIDES', 'METHOD_OVERRIDES'] so the METHOD_OVERRIDES edge
         // between BaseService.authenticate and AuthService.authenticate is found.
+        // file_path hint disambiguates the two 'authenticate' methods per #470.
         const result = await backend.callTool('impact', {
           target: 'authenticate',
+          file_path: 'src/auth.ts',
           direction: 'downstream',
           relationTypes: ['OVERRIDES'],
         });
         expect(result).not.toHaveProperty('error');
+        expect(result.status).not.toBe('ambiguous');
         expect(result.impactedCount).toBeGreaterThanOrEqual(1);
         const d1 = result.byDepth[1] || result.byDepth['1'] || [];
         const names = d1.map((d: any) => d.name);
diff --git a/gitnexus/test/integration/pipeline-graph-golden.test.ts b/gitnexus/test/integration/pipeline-graph-golden.test.ts
index f008bdadb..abd6377e3 100644
--- a/gitnexus/test/integration/pipeline-graph-golden.test.ts
+++ b/gitnexus/test/integration/pipeline-graph-golden.test.ts
@@ -18,14 +18,15 @@
  *
  * Nothing path-dependent, time-dependent, or id-opaque leaks into the snapshot.
  */
-import { describe, it, expect, beforeAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import path from 'path';
 import fs from 'fs';
+import os from 'os';
 import crypto from 'crypto';
 import { runPipelineFromRepo } from '../../src/core/ingestion/pipeline.js';
 import type { PipelineResult } from '../../src/types/pipeline.js';
 
-const MINI_REPO = path.resolve(__dirname, '..', 'fixtures', 'mini-repo');
+const FIXTURE_SRC = path.resolve(__dirname, '..', 'fixtures', 'mini-repo');
 const GOLDEN_DIR = path.resolve(__dirname, '..', 'fixtures', 'pipeline-golden', 'mini-repo');
 const GOLDEN_FILE = path.join(GOLDEN_DIR, 'expected-graph.json');
 
@@ -128,12 +129,26 @@ function diffCounts(
 describe('pipeline graph golden', () => {
   let result: PipelineResult;
   let snapshot: GraphSnapshot;
+  let tmpDir: string;
 
   beforeAll(async () => {
-    result = await runPipelineFromRepo(MINI_REPO, () => {});
+    // Copy the fixture to a temp directory as defense-in-depth against
+    // parallel tests writing into the shared fixture source. cli-e2e
+    // was the historical offender — it now copies to its own tmpdir
+    // (see test/integration/cli-e2e.test.ts `beforeAll`) — but this
+    // cpSync stays as a belt-and-suspenders guarantee that any future
+    // test adding files to the source won't pollute the golden snapshot.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-golden-'));
+    fs.cpSync(FIXTURE_SRC, tmpDir, { recursive: true });
+
+    result = await runPipelineFromRepo(tmpDir, () => {});
     snapshot = buildSnapshot(result);
   }, 60000);
 
+  afterAll(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
   it('matches committed golden snapshot on mini-repo', () => {
     if (UPDATE || !fs.existsSync(GOLDEN_FILE)) {
       fs.mkdirSync(GOLDEN_DIR, { recursive: true });
diff --git a/gitnexus/test/integration/resolvers/python.test.ts b/gitnexus/test/integration/resolvers/python.test.ts
index b7d60b20e..72f23edeb 100644
--- a/gitnexus/test/integration/resolvers/python.test.ts
+++ b/gitnexus/test/integration/resolvers/python.test.ts
@@ -1846,6 +1846,61 @@ describe('Python module import CALLS resolution (Issue #337)', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// External dotted imports: framework modules like django.apps must not resolve
+// to unrelated local basename matches such as accounts/apps.py or config/urls.py.
+// ---------------------------------------------------------------------------
+
+describe('Python external dotted imports do not self-resolve to local files', () => {
+  let result: PipelineResult;
+
+  beforeAll(async () => {
+    result = await runPipelineFromRepo(path.join(FIXTURES, 'python-django-app-imports'), () => {});
+  }, 60000);
+
+  it('keeps the real local cross-app import: billing/models.py -> accounts/models.py', () => {
+    const imports = getRelationships(result, 'IMPORTS');
+    const localImport = imports.find(
+      (e) => e.sourceFilePath === 'billing/models.py' && e.targetFilePath === 'accounts/models.py',
+    );
+    expect(localImport).toBeDefined();
+  });
+
+  it('does not resolve django.apps in app configs to local apps.py files', () => {
+    const imports = getRelationships(result, 'IMPORTS');
+    const appConfigImports = imports.filter((e) => e.sourceFilePath.endsWith('/apps.py'));
+    expect(appConfigImports.length).toBe(0);
+  });
+
+  it('does not resolve django.urls in config/urls.py to config/urls.py', () => {
+    const imports = getRelationships(result, 'IMPORTS');
+    const urlsImport = imports.find(
+      (e) => e.sourceFilePath === 'config/urls.py' && e.targetFilePath === 'config/urls.py',
+    );
+    expect(urlsImport).toBeUndefined();
+  });
+
+  it('does not resolve django.core.asgi or django.core.wsgi to local config modules', () => {
+    const imports = getRelationships(result, 'IMPORTS');
+    const asgiImport = imports.find(
+      (e) => e.sourceFilePath === 'config/asgi.py' && e.targetFilePath === 'config/asgi.py',
+    );
+    const wsgiImport = imports.find(
+      (e) => e.sourceFilePath === 'config/wsgi.py' && e.targetFilePath === 'config/wsgi.py',
+    );
+
+    expect(asgiImport).toBeUndefined();
+    expect(wsgiImport).toBeUndefined();
+  });
+
+  it('does not resolve other django.* imports to local same-basename files', () => {
+    const imports = getRelationships(result, 'IMPORTS');
+    const wrongTargets = new Set(['config/asgi.py', 'config/wsgi.py', 'config/urls.py']);
+    const misresolvedFrameworkImports = imports.filter((e) => wrongTargets.has(e.targetFilePath));
+    expect(misresolvedFrameworkImports.length).toBe(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Phase 16: Method enrichment (isAbstract, parameterTypes, static methods)
 // models.py: Animal(ABC) with @abstractmethod speak, @staticmethod classify, breathe
diff --git a/gitnexus/test/integration/resolvers/ruby-sequential-mixin.test.ts b/gitnexus/test/integration/resolvers/ruby-sequential-mixin.test.ts
new file mode 100644
index 000000000..c3e105a15
--- /dev/null
+++ b/gitnexus/test/integration/resolvers/ruby-sequential-mixin.test.ts
@@ -0,0 +1,232 @@
+/**
+ * Regression: Ruby mixin heritage resolution must work on the sequential
+ * ingestion fallback AND the worker-pool path, with identical output.
+ *
+ * Guards the two Codex adversarial review findings addressed by plan
+ * `docs/plans/2026-04-17-001-fix-codex-adversarial-ruby-mixin-heritage-plan.md`:
+ *
+ * 1. Sequential-mode `sequentialHeritageMap` must include Ruby `include` /
+ *    `extend` / `prepend` mixin ancestry before `processCalls` resolves calls
+ *    against it. `extractExtractedHeritageFromFiles` now also runs
+ *    `heritageExtractor.extractFromCall` during its prepass.
+ *
+ * 2. Ruby `module` declarations are relabeled to `Trait` so they participate
+ *    in `lookupClassByName` / `buildHeritageMap`.
+ *
+ * The follow-up plan `docs/plans/2026-04-17-002-fix-ce-review-ruby-mixin-followups-plan.md`
+ * Units 1 and 2 harden this suite:
+ *   - Worker mode actually spawns a worker pool (verified via
+ *     `PipelineResult.usedWorkerPool`) instead of silently falling back.
+ *   - The prepend-only `prepended_marker` assertion checks the resolved
+ *     method's OWNER, so reverting the Module→Trait relabel (Unit 2 of
+ *     plan 001) makes the test fail with a clear owner-mismatch instead
+ *     of passing trivially on `Account`'s own method.
+ *
+ * Plan 003 adds the `'ruby-mixin'` MroStrategy and kind-aware ancestry
+ * (prepend / include / extend split). Plan 005 (the call-resolution DAG)
+ * installs `inferImplicitReceiver` and `selectDispatch` provider hooks that
+ * let Ruby self-rewrite bare-identifier calls to `self.method` so they take
+ * the owner-scoped MRO path. The shadow-name assertion below exercises the
+ * full chain: Module→Trait relabel + kind-aware MRO + self-inference.
+ *
+ * Known guard limitation (documented residual): reverting plan 001 Unit 1
+ * alone (the sequential prepass extractFromCall) does NOT make these tests
+ * fail, because `processCalls` independently extracts call-based heritage
+ * into `rubyHeritage`, feeds it to `processHeritageFromExtracted` for graph
+ * edges, and the call resolver's global-name fallback can still locate
+ * mixin-provided methods without MRO ancestry. A stronger guard would need
+ * an ambiguous method name that only MRO can disambiguate; that requires
+ * cross-chunk or multi-class shadowing scenarios not covered by this
+ * fixture. Tracked as residual work in plan 002's Unit 3 (cross-chunk).
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import path from 'path';
+import type { GraphRelationship } from '../../../src/core/graph/types.js';
+import {
+  FIXTURES,
+  getRelationships,
+  getNodesByLabel,
+  runPipelineFromRepo,
+  type PipelineOptions,
+  type PipelineResult,
+} from './helpers.js';
+
+const FIXTURE = path.join(FIXTURES, 'ruby-sequential-mixin');
+
+async function runMode(opts: PipelineOptions): Promise<PipelineResult> {
+  return runPipelineFromRepo(FIXTURE, () => {}, opts);
+}
+
+/** CALLS edges from `sourceName` whose target is a Method node. */
+function methodCallEdges(result: PipelineResult, sourceName: string): Set<string> {
+  const edges = getRelationships(result, 'CALLS').filter(
+    (e) => e.source === sourceName && e.targetLabel === 'Method',
+  );
+  return new Set(edges.map((e) => `${e.source} → ${e.target}`));
+}
+
+/**
+ * Find the name of the node that `HAS_METHOD`s this target node, if any.
+ * Returns `undefined` when no owner edge exists (e.g., top-level function).
+ */
+function findMethodOwner(result: PipelineResult, methodNodeId: string): string | undefined {
+  for (const rel of result.graph.iterRelationships() as IterableIterator<GraphRelationship>) {
+    if (rel.type === 'HAS_METHOD' && rel.targetId === methodNodeId) {
+      return result.graph.getNode(rel.sourceId)?.properties.name;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Return the owner names of every `Method` target reached by a CALLS edge
+ * starting at `sourceName` whose target's name matches `targetMethodName`.
+ * Used to assert WHICH provider resolved a shadowed method name like
+ * `serialize` (provided by both Account and PrependedOverride).
+ */
+function resolvedMethodOwners(
+  result: PipelineResult,
+  sourceName: string,
+  targetMethodName: string,
+): string[] {
+  const owners: string[] = [];
+  for (const e of getRelationships(result, 'CALLS')) {
+    if (e.source === sourceName && e.targetLabel === 'Method' && e.target === targetMethodName) {
+      const owner = findMethodOwner(result, e.rel.targetId);
+      if (owner) owners.push(owner);
+    }
+  }
+  return owners.sort();
+}
+
+describe('Ruby mixin heritage: sequential vs worker parity', () => {
+  let sequential: PipelineResult;
+  let workers: PipelineResult;
+
+  beforeAll(async () => {
+    sequential = await runMode({ skipWorkers: true });
+    // Force the worker pool to spawn even though the fixture is tiny.
+    // Without this override, the pipeline's MIN_FILES_FOR_WORKERS / MIN_BYTES_FOR_WORKERS
+    // gate would fall back to sequential and the "worker vs sequential" parity
+    // assertion below would degenerate into sequential-vs-sequential.
+    workers = await runMode({
+      skipWorkers: false,
+      workerThresholdsForTest: { minFiles: 1, minBytes: 0 },
+    });
+  }, 120000);
+
+  it('exercises both pipeline paths (sequential and worker)', () => {
+    // If either of these assertions fails, every downstream parity check
+    // below is meaningless — both modes would be running the same path.
+    expect(sequential.usedWorkerPool).toBe(false);
+    expect(workers.usedWorkerPool).toBe(true);
+  });
+
+  it('labels Ruby modules as Trait in both modes', () => {
+    const expected = ['Greetable', 'LoggerMixin', 'PrependedOverride'];
+    expect(getNodesByLabel(sequential, 'Trait').sort()).toEqual(expected);
+    expect(getNodesByLabel(workers, 'Trait').sort()).toEqual(expected);
+    // No Ruby modules leak through as the inert `Module` label.
+    // The 'lib' module node is the fixture's top-level directory node, which
+    // the ingestion pipeline emits for every fixture root — unrelated to
+    // Ruby `module` declarations. Filtering it keeps the assertion specific
+    // to Ruby-module relabeling without being coupled to how directory nodes
+    // are emitted.
+    expect(getNodesByLabel(sequential, 'Module').filter((n) => n !== 'lib')).toEqual([]);
+    expect(getNodesByLabel(workers, 'Module').filter((n) => n !== 'lib')).toEqual([]);
+  });
+
+  it('sequential mode resolves include-provided method: call_greet → greet', () => {
+    const edges = methodCallEdges(sequential, 'call_greet');
+    expect([...edges]).toContain('call_greet → greet');
+
+    // Stronger: the resolved `greet` must be owned by the `Greetable` module
+    // (relabeled to Trait). A regression in Unit 2 of plan 001 would either
+    // fail to resolve (owners = []) or resolve to some other owner.
+    const owners = resolvedMethodOwners(sequential, 'call_greet', 'greet');
+    expect(owners).toContain('Greetable');
+  });
+
+  it('sequential mode resolves prepend-only method: call_prepended_marker → PrependedOverride#prepended_marker', () => {
+    // `prepended_marker` is defined ONLY on PrependedOverride — not on
+    // Account, Greetable, or LoggerMixin. Narrow guard for the prepend
+    // provider entering the MRO (plan 001 / plan 003).
+    const owners = resolvedMethodOwners(sequential, 'call_prepended_marker', 'prepended_marker');
+    expect(owners).toContain('PrependedOverride');
+  });
+
+  it('sequential mode resolves prepend shadow: call_serialize → PrependedOverride#serialize (not Account#serialize)', () => {
+    // `Account` defines `def serialize` AND `prepend PrependedOverride` which
+    // also defines `serialize`. Ruby MRO says the prepended module wins.
+    // This assertion exercises the full chain:
+    //   - Module→Trait relabel (plan 001 Unit 2) — PrependedOverride resolvable via lookupClassByName
+    //   - `'ruby-mixin'` MroStrategy (plan 003 Unit 3) — prepend walks before direct owner
+    //   - `inferImplicitReceiver` hook (plan 005 / DAG) — bare `serialize` call rewritten
+    //     as `self.serialize` so it takes the owner-scoped MRO path
+    // Reverting ANY of the three makes this assertion fail.
+    const owners = resolvedMethodOwners(sequential, 'call_serialize', 'serialize');
+    expect(owners).toContain('PrependedOverride');
+  });
+
+  it('sequential mode resolves extend-provided class method: Usage#run → LoggerMixin#log', () => {
+    // `Account extend LoggerMixin` means `LoggerMixin#log` is a CLASS method
+    // on `Account`. The fixture's `Usage#run` calls `Account.log("from Usage")`
+    // — a class-constant receiver, not an instance call. This exercises the
+    // `selectDispatch` hook's `receiverSource === 'class-as-receiver'` branch,
+    // which returns `ancestryView: 'singleton'` so the walker uses
+    // `getSingletonAncestry(Account)` = [LoggerMixin] instead of the instance
+    // MRO (which would have resolved nothing, since `log` is not an instance
+    // method on Account).
+    //
+    // Reverting the singleton branch in Ruby's selectDispatch (or dropping
+    // 'Trait'/'Class' from the class-as-receiver filter in call-processor)
+    // makes this assertion fail.
+    const owners = resolvedMethodOwners(sequential, 'run', 'log');
+    expect(owners).toContain('LoggerMixin');
+  });
+
+  // TODO(plan-003-followup): assert that prepend shadows self for
+  // `call_serialize → PrependedOverride#serialize`. Blocked on Ruby bare-call
+  // self-inference: bare identifier calls like `serialize` inside `Account#call_serialize`
+  // currently flow through `resolveFreeCall` (global name lookup), not
+  // `resolveMemberCall` (owner-scoped + MRO walk). The `'ruby-mixin'` MroStrategy
+  // added by plan 003 is correctly wired and will apply as soon as Ruby bare calls
+  // are threaded as `self.method` with receiverTypeName = enclosing class. Until then,
+  // shadow-name resolution lands on `Account#serialize` regardless of prepend MRO.
+  //
+  // The `prepended_marker` test above is the narrower guard that works today
+  // (non-shadowed method only reachable via the prepend provider).
+
+  it('sequential mode emits IMPLEMENTS edges for all three mixin kinds', () => {
+    // Ruby mixins (include / extend / prepend) flow through the IMPLEMENTS
+    // branch of processHeritageFromExtracted with the mixin kind recorded in
+    // rel.reason. See heritage-processor.ts L146-168.
+    const kinds = getRelationships(sequential, 'IMPLEMENTS')
+      .filter((e) => e.source === 'Account')
+      .map((e) => e.rel.reason ?? '')
+      .sort();
+    expect(kinds).toEqual(['extend', 'include', 'prepend']);
+  });
+
+  it('worker mode resolves the same include and prepend-only targets', () => {
+    // Cross-mode ownership parity for the mixin providers. If Unit 1 of
+    // plan 001 regressed on the sequential side only, the `greet` /
+    // `prepended_marker` owners would diverge between modes here — the
+    // sequential side would lose the mixin-provided edges while worker
+    // mode kept them (or vice versa).
+    expect(resolvedMethodOwners(workers, 'call_greet', 'greet')).toContain('Greetable');
+    expect(resolvedMethodOwners(workers, 'call_prepended_marker', 'prepended_marker')).toContain(
+      'PrependedOverride',
+    );
+  });
+
+  it('sequential and worker modes produce the same mixin-method CALLS edges', () => {
+    const seqEdges = methodCallEdges(sequential, 'call_greet');
+    const workerEdges = methodCallEdges(workers, 'call_greet');
+    expect([...seqEdges].sort()).toEqual([...workerEdges].sort());
+
+    const seqMarker = methodCallEdges(sequential, 'call_prepended_marker');
+    const workerMarker = methodCallEdges(workers, 'call_prepended_marker');
+    expect([...seqMarker].sort()).toEqual([...workerMarker].sort());
+  });
+});
diff --git a/gitnexus/test/integration/resolvers/ruby.test.ts b/gitnexus/test/integration/resolvers/ruby.test.ts
index 8cb7a29e3..82806aac5 100644
--- a/gitnexus/test/integration/resolvers/ruby.test.ts
+++ b/gitnexus/test/integration/resolvers/ruby.test.ts
@@ -33,8 +33,12 @@ describe('Ruby require_relative, heritage & property resolution', () => {
     expect(getNodesByLabel(result, 'Class')).toEqual(['BaseModel', 'User', 'UserService']);
   });
 
-  it('detects 3 modules', () => {
-    expect(getNodesByLabel(result, 'Module')).toEqual(['Cacheable', 'Loggable', 'Serializable']);
+  it('detects 3 modules (labeled as Trait for class-like registry lookup)', () => {
+    // Ruby `module` declarations are relabeled to `Trait` during ingestion so
+    // they participate in `lookupClassByName` and `buildHeritageMap`. This is
+    // the single source of truth for Ruby module detection in the graph.
+    expect(getNodesByLabel(result, 'Trait')).toEqual(['Cacheable', 'Loggable', 'Serializable']);
+    expect(getNodesByLabel(result, 'Module')).toEqual([]);
   });
 
   it('detects methods on classes and modules', () => {
@@ -431,9 +435,10 @@ describe('Ruby parent resolution', () => {
     result = await runPipelineFromRepo(path.join(FIXTURES, 'ruby-parent-resolution'), () => {});
   }, 60000);
 
-  it('detects BaseModel and User classes plus Serializable module', () => {
+  it('detects BaseModel and User classes plus Serializable module (Trait)', () => {
     expect(getNodesByLabel(result, 'Class')).toEqual(['BaseModel', 'User']);
-    expect(getNodesByLabel(result, 'Module')).toEqual(['Serializable']);
+    // Ruby modules are labeled Trait — see the "detects 3 modules" test above.
+    expect(getNodesByLabel(result, 'Trait')).toEqual(['Serializable']);
   });
 
   it('emits EXTENDS edge: User < BaseModel', () => {
diff --git a/gitnexus/test/integration/worker-pool.test.ts b/gitnexus/test/integration/worker-pool.test.ts
index 48a7c506a..072d9e24c 100644
--- a/gitnexus/test/integration/worker-pool.test.ts
+++ b/gitnexus/test/integration/worker-pool.test.ts
@@ -6,11 +6,12 @@
  * This is critical for cross-platform CI where vitest runs from src/
  * but workers need compiled .js files.
  */
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { createWorkerPool, WorkerPool } from '../../src/core/ingestion/workers/worker-pool.js';
 import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import fs from 'node:fs';
+import os from 'node:os';
 
 const DIST_WORKER = path.resolve(
   __dirname,
@@ -185,6 +186,43 @@ describe('worker pool integration', () => {
     },
   );
 
+  it('treats warning messages as non-terminal and still resolves the worker result', async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-worker-warning-'));
+    const workerPath = path.join(tempDir, 'warning-worker.js');
+    fs.writeFileSync(
+      workerPath,
+      `
+      const { parentPort } = require('node:worker_threads');
+      parentPort.on('message', (msg) => {
+        if (msg && msg.type === 'sub-batch') {
+          parentPort.postMessage({ type: 'warning', message: 'warning before result' });
+          parentPort.postMessage({ type: 'sub-batch-done' });
+          return;
+        }
+        if (msg && msg.type === 'flush') {
+          parentPort.postMessage({ type: 'result', data: { nodes: [], relationships: [], symbols: [], imports: [], calls: [], heritage: [], routes: [], fileCount: 1 } });
+        }
+      });
+    `,
+    );
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const workerUrl = pathToFileURL(workerPath) as URL;
+    pool = createWorkerPool(workerUrl, 1);
+
+    try {
+      const results = await pool.dispatch<any, any>([
+        { path: 'warning.ts', content: 'const x = 1;' },
+      ]);
+      expect(results).toHaveLength(1);
+      expect(results[0].fileCount).toBe(1);
+      expect(warnSpy).toHaveBeenCalledWith('warning before result');
+    } finally {
+      warnSpy.mockRestore();
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   it.skipIf(!hasDistWorker)('createWorkerPool with size 0 creates pool with zero workers', () => {
     const workerUrl = pathToFileURL(DIST_WORKER) as URL;
     const zeroPool = createWorkerPool(workerUrl, 0);
diff --git a/gitnexus/test/unit/ai-context.test.ts b/gitnexus/test/unit/ai-context.test.ts
index 0a9f52a68..7a8ed0e9b 100644
--- a/gitnexus/test/unit/ai-context.test.ts
+++ b/gitnexus/test/unit/ai-context.test.ts
@@ -45,6 +45,63 @@ describe('generateAIContextFiles', () => {
     expect(content).toContain('TestProject');
   });
 
+  it('keeps the load-bearing repo-specific sections in the CLAUDE.md block (#856)', async () => {
+    // The trimmed block must still contain everything that is genuinely
+    // unique per repo or load-bearing for the agent: the freshness warning,
+    // the Always Do / Never Do imperative lists, the Resources URI table
+    // (projectName-interpolated), and the skills routing table that tells
+    // the agent which skill file to read for each task.
+    const stats = { nodes: 50, edges: 100, processes: 5 };
+    await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats);
+
+    const content = await fs.readFile(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+
+    expect(content).toContain('If any GitNexus tool warns the index is stale');
+    expect(content).toContain('## Always Do');
+    expect(content).toContain('## Never Do');
+    expect(content).toContain('## Resources');
+    expect(content).toContain('gitnexus://repo/TestProject/context');
+    expect(content).toContain('gitnexus-impact-analysis/SKILL.md');
+    expect(content).toContain('gitnexus-refactoring/SKILL.md');
+    expect(content).toContain('gitnexus-debugging/SKILL.md');
+    expect(content).toContain('gitnexus-cli/SKILL.md');
+  });
+
+  it('does not duplicate content that already lives in skill files (#856)', async () => {
+    // The six sections listed in issue #856 are redundant with the skill
+    // files shipped alongside the CLAUDE.md block (both are loaded into
+    // every Claude Code session). Their absence is the whole point of the
+    // trim — assert each header is gone so a future regression that pads
+    // the block back out fails here.
+    const stats = { nodes: 50, edges: 100, processes: 5 };
+    await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats);
+
+    const content = await fs.readFile(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+
+    expect(content).not.toContain('## Tools Quick Reference');
+    expect(content).not.toContain('## Impact Risk Levels');
+    expect(content).not.toContain('## Self-Check Before Finishing');
+    expect(content).not.toContain('## When Debugging');
+    expect(content).not.toContain('## When Refactoring');
+    expect(content).not.toContain('## Keeping the Index Fresh');
+  });
+
+  it('keeps the CLAUDE.md GitNexus block under the token-cost budget (#856)', async () => {
+    // The pre-trim block was ~5465 chars. After #856 it's ~2580 — about a
+    // 52% reduction. 2700 is a soft ceiling that still leaves headroom for
+    // legitimate future additions but will fail loudly if the trim is
+    // reverted or someone pads the block back out toward the original size.
+    const stats = { nodes: 50, edges: 100, processes: 5 };
+    await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats);
+
+    const content = await fs.readFile(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+    const block = content.slice(
+      content.indexOf('<!-- gitnexus:start -->'),
+      content.indexOf('<!-- gitnexus:end -->'),
+    );
+    expect(block.length).toBeLessThan(2700);
+  });
+
   it('handles empty stats', async () => {
     const stats = {};
     const result = await generateAIContextFiles(tmpDir, storagePath, 'EmptyProject', stats);
diff --git a/gitnexus/test/unit/ast-utils.test.ts b/gitnexus/test/unit/ast-utils.test.ts
new file mode 100644
index 000000000..f736d7e77
--- /dev/null
+++ b/gitnexus/test/unit/ast-utils.test.ts
@@ -0,0 +1,75 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { createParserForLanguage, getLanguageFromFilename } = vi.hoisted(() => ({
+  createParserForLanguage: vi.fn(),
+  getLanguageFromFilename: vi.fn((filePath: string) =>
+    filePath.endsWith('.py') ? 'python' : 'typescript',
+  ),
+}));
+
+vi.mock('../../src/core/tree-sitter/parser-loader.js', () => ({
+  createParserForLanguage,
+  isLanguageAvailable: vi.fn().mockReturnValue(true),
+  resolveLanguageKey: vi.fn((language: string, filePath?: string) =>
+    language === 'typescript' && filePath?.endsWith('.tsx') ? 'typescript:tsx' : language,
+  ),
+}));
+
+vi.mock('gitnexus-shared', () => ({
+  getLanguageFromFilename,
+}));
+
+describe('ensureAndParse', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    createParserForLanguage.mockReset();
+    getLanguageFromFilename.mockClear();
+  });
+
+  it('reuses the parser for the same grammar key across interleaved languages', async () => {
+    const tsParse = vi
+      .fn()
+      .mockReturnValueOnce({ lang: 'ts', content: 'first' })
+      .mockReturnValueOnce({ lang: 'ts', content: 'second' });
+    const pyParse = vi.fn().mockReturnValue({ lang: 'py', content: 'middle' });
+
+    createParserForLanguage.mockImplementation(async (language: string, filePath?: string) => {
+      if (language === 'typescript') return { parse: tsParse, key: filePath };
+      if (language === 'python') return { parse: pyParse, key: filePath };
+      throw new Error(`unexpected language ${language}`);
+    });
+
+    const { ensureAndParse } = await import('../../src/core/embeddings/ast-utils.js');
+
+    const tsFirst = await ensureAndParse('const one = 1;', 'first.ts');
+    const pyMiddle = await ensureAndParse('value = 1', 'middle.py');
+    const tsSecond = await ensureAndParse('const two = 2;', 'second.ts');
+
+    expect(tsFirst).toEqual({ lang: 'ts', content: 'first' });
+    expect(pyMiddle).toEqual({ lang: 'py', content: 'middle' });
+    expect(tsSecond).toEqual({ lang: 'ts', content: 'second' });
+    expect(createParserForLanguage).toHaveBeenCalledTimes(2);
+    expect(tsParse).toHaveBeenCalledTimes(2);
+    expect(pyParse).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses separate parser instances for .ts and .tsx', async () => {
+    const tsParse = vi.fn().mockReturnValue({ lang: 'ts' });
+    const tsxParse = vi.fn().mockReturnValue({ lang: 'tsx' });
+
+    createParserForLanguage.mockImplementation(async (_language: string, filePath?: string) => {
+      if (filePath?.endsWith('.tsx')) return { parse: tsxParse };
+      return { parse: tsParse };
+    });
+
+    const { ensureAndParse } = await import('../../src/core/embeddings/ast-utils.js');
+
+    await ensureAndParse('const value = 1;', 'plain.ts');
+    await ensureAndParse('export const View = <div />;', 'view.tsx');
+    await ensureAndParse('const other = 2;', 'other.ts');
+
+    expect(createParserForLanguage).toHaveBeenCalledTimes(2);
+    expect(tsParse).toHaveBeenCalledTimes(2);
+    expect(tsxParse).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/gitnexus/test/unit/call-extraction.test.ts b/gitnexus/test/unit/call-extraction.test.ts
new file mode 100644
index 000000000..85921f1f8
--- /dev/null
+++ b/gitnexus/test/unit/call-extraction.test.ts
@@ -0,0 +1,527 @@
+import { describe, it, expect } from 'vitest';
+import { createCallExtractor } from '../../src/core/ingestion/call-extractors/generic.js';
+import {
+  javaCallConfig,
+  kotlinCallConfig,
+} from '../../src/core/ingestion/call-extractors/configs/jvm.js';
+import { csharpCallConfig } from '../../src/core/ingestion/call-extractors/configs/csharp.js';
+import {
+  typescriptCallConfig,
+  javascriptCallConfig,
+} from '../../src/core/ingestion/call-extractors/configs/typescript-javascript.js';
+import {
+  cCallConfig,
+  cppCallConfig,
+} from '../../src/core/ingestion/call-extractors/configs/c-cpp.js';
+import { pythonCallConfig } from '../../src/core/ingestion/call-extractors/configs/python.js';
+import { rubyCallConfig } from '../../src/core/ingestion/call-extractors/configs/ruby.js';
+import { rustCallConfig } from '../../src/core/ingestion/call-extractors/configs/rust.js';
+import { dartCallConfig } from '../../src/core/ingestion/call-extractors/configs/dart.js';
+import { phpCallConfig } from '../../src/core/ingestion/call-extractors/configs/php.js';
+import { swiftCallConfig } from '../../src/core/ingestion/call-extractors/configs/swift.js';
+import { goCallConfig } from '../../src/core/ingestion/call-extractors/configs/go.js';
+import type { CallExtractionConfig } from '../../src/core/ingestion/call-types.js';
+import type { SyntaxNode } from '../../src/core/ingestion/utils/ast-helpers.js';
+import { SupportedLanguages } from '../../src/config/supported-languages.js';
+import { getProvider } from '../../src/core/ingestion/languages/index.js';
+import Parser from 'tree-sitter';
+import TypeScript from 'tree-sitter-typescript';
+import Python from 'tree-sitter-python';
+import Java from 'tree-sitter-java';
+import CSharp from 'tree-sitter-c-sharp';
+import Go from 'tree-sitter-go';
+import Rust from 'tree-sitter-rust';
+import CPP from 'tree-sitter-cpp';
+import PHP from 'tree-sitter-php';
+import Ruby from 'tree-sitter-ruby';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse code with a tree-sitter language and run the language's query to find
+ * @call / @call.name captures.
+ */
+function extractCallCaptures(
+  parser: Parser,
+  code: string,
+  language: SupportedLanguages,
+): Array<{
+  callNode: SyntaxNode;
+  nameNode: SyntaxNode | undefined;
+  calledName: string | undefined;
+}> {
+  const provider = getProvider(language);
+  const queryStr = provider.treeSitterQueries;
+  if (!queryStr) throw new Error(`No query for ${language}`);
+
+  const tree = parser.parse(code);
+  const lang = parser.getLanguage();
+  const query = new Parser.Query(lang, queryStr);
+  const matches = query.matches(tree.rootNode);
+
+  const results: Array<{
+    callNode: SyntaxNode;
+    nameNode: SyntaxNode | undefined;
+    calledName: string | undefined;
+  }> = [];
+
+  for (const match of matches) {
+    const captureMap: Record<string, SyntaxNode> = {};
+    for (const c of match.captures) {
+      captureMap[c.name] = c.node;
+    }
+    if (captureMap['call']) {
+      results.push({
+        callNode: captureMap['call'],
+        nameNode: captureMap['call.name'],
+        calledName: captureMap['call.name']?.text,
+      });
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Factory construction tests
+// ---------------------------------------------------------------------------
+
+describe('createCallExtractor', () => {
+  it('constructs all currently registered language configs', () => {
+    const configs: CallExtractionConfig[] = [
+      javaCallConfig,
+      kotlinCallConfig,
+      csharpCallConfig,
+      typescriptCallConfig,
+      javascriptCallConfig,
+      cCallConfig,
+      cppCallConfig,
+      pythonCallConfig,
+      rubyCallConfig,
+      rustCallConfig,
+      dartCallConfig,
+      phpCallConfig,
+      swiftCallConfig,
+      goCallConfig,
+    ];
+    for (const cfg of configs) {
+      expect(
+        () => createCallExtractor(cfg),
+        `config for ${cfg.language} must construct cleanly`,
+      ).not.toThrow();
+    }
+  });
+
+  it('preserves language on the extractor', () => {
+    const extractor = createCallExtractor(javaCallConfig);
+    expect(extractor.language).toBe(SupportedLanguages.Java);
+  });
+
+  it('returns null when no callNameNode and no language seed', () => {
+    const extractor = createCallExtractor(typescriptCallConfig);
+    // A minimal stub SyntaxNode — extract should return null since
+    // there's no callNameNode and no language-specific hook
+    const stub = { type: 'call_expression' } as unknown as SyntaxNode;
+    expect(extractor.extract(stub, undefined)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LanguageProvider.callExtractor wiring
+// ---------------------------------------------------------------------------
+
+describe('callExtractor on LanguageProvider', () => {
+  it('all tree-sitter providers have callExtractor defined', () => {
+    const languages: SupportedLanguages[] = [
+      SupportedLanguages.TypeScript,
+      SupportedLanguages.JavaScript,
+      SupportedLanguages.Python,
+      SupportedLanguages.Java,
+      SupportedLanguages.Kotlin,
+      SupportedLanguages.Go,
+      SupportedLanguages.Rust,
+      SupportedLanguages.CSharp,
+      SupportedLanguages.C,
+      SupportedLanguages.CPlusPlus,
+      SupportedLanguages.PHP,
+      SupportedLanguages.Ruby,
+      SupportedLanguages.Swift,
+      SupportedLanguages.Dart,
+      SupportedLanguages.Vue,
+    ];
+    for (const lang of languages) {
+      const provider = getProvider(lang);
+      expect(provider.callExtractor, `${lang} should have a callExtractor`).toBeDefined();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Generic extraction via @call.name
+// ---------------------------------------------------------------------------
+
+describe('generic call extraction', () => {
+  const parser = new Parser();
+
+  describe('TypeScript', () => {
+    const extractor = createCallExtractor(typescriptCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(TypeScript.typescript);
+      const captures = extractCallCaptures(parser, 'doStuff()', SupportedLanguages.TypeScript);
+      const match = captures.find((c) => c.calledName === 'doStuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('doStuff');
+      expect(result!.callForm).toBe('free');
+      expect(result!.receiverName).toBeUndefined();
+    });
+
+    it('extracts member call with receiver', () => {
+      parser.setLanguage(TypeScript.typescript);
+      const captures = extractCallCaptures(parser, 'user.save()', SupportedLanguages.TypeScript);
+      const match = captures.find((c) => c.calledName === 'save');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('save');
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('user');
+    });
+
+    it('extracts constructor call', () => {
+      parser.setLanguage(TypeScript.typescript);
+      const captures = extractCallCaptures(parser, 'new User()', SupportedLanguages.TypeScript);
+      const match = captures.find((c) => c.calledName === 'User');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('User');
+      expect(result!.callForm).toBe('constructor');
+    });
+
+    it('extracts argCount', () => {
+      parser.setLanguage(TypeScript.typescript);
+      const captures = extractCallCaptures(parser, 'foo(a, b, c)', SupportedLanguages.TypeScript);
+      const match = captures.find((c) => c.calledName === 'foo');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.argCount).toBe(3);
+    });
+
+    it('does not set typeAsReceiverHeuristic', () => {
+      parser.setLanguage(TypeScript.typescript);
+      const captures = extractCallCaptures(parser, 'User.find()', SupportedLanguages.TypeScript);
+      const match = captures.find((c) => c.calledName === 'find');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result!.typeAsReceiverHeuristic).toBeFalsy();
+    });
+  });
+
+  describe('Python', () => {
+    const extractor = createCallExtractor(pythonCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(Python);
+      const captures = extractCallCaptures(parser, 'do_stuff()', SupportedLanguages.Python);
+      const match = captures.find((c) => c.calledName === 'do_stuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('do_stuff');
+      expect(result!.callForm).toBe('free');
+    });
+
+    it('extracts member call', () => {
+      parser.setLanguage(Python);
+      const captures = extractCallCaptures(parser, 'user.save()', SupportedLanguages.Python);
+      const match = captures.find((c) => c.calledName === 'save');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('user');
+    });
+  });
+
+  describe('Java', () => {
+    const extractor = createCallExtractor(javaCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(Java);
+      const captures = extractCallCaptures(
+        parser,
+        'class A { void m() { doStuff(); } }',
+        SupportedLanguages.Java,
+      );
+      const match = captures.find((c) => c.calledName === 'doStuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('doStuff');
+      expect(result!.callForm).toBe('free');
+    });
+
+    it('extracts member call with receiver', () => {
+      parser.setLanguage(Java);
+      const captures = extractCallCaptures(
+        parser,
+        'class A { void m() { user.save(); } }',
+        SupportedLanguages.Java,
+      );
+      const match = captures.find((c) => c.calledName === 'save');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('user');
+    });
+
+    it('sets typeAsReceiverHeuristic', () => {
+      parser.setLanguage(Java);
+      const captures = extractCallCaptures(
+        parser,
+        'class A { void m() { User.find(); } }',
+        SupportedLanguages.Java,
+      );
+      const match = captures.find((c) => c.calledName === 'find');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.typeAsReceiverHeuristic).toBe(true);
+    });
+  });
+
+  describe('C#', () => {
+    const extractor = createCallExtractor(csharpCallConfig);
+
+    it('extracts member call with receiver and typeAsReceiverHeuristic', () => {
+      parser.setLanguage(CSharp);
+      const captures = extractCallCaptures(
+        parser,
+        'class A { void M() { Console.WriteLine(); } }',
+        SupportedLanguages.CSharp,
+      );
+      const match = captures.find((c) => c.calledName === 'WriteLine');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('WriteLine');
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('Console');
+      expect(result!.typeAsReceiverHeuristic).toBe(true);
+    });
+
+    it('sets typeAsReceiverHeuristic flag even for lowercase receivers', () => {
+      parser.setLanguage(CSharp);
+      const captures = extractCallCaptures(
+        parser,
+        'class A { void M() { logger.Info(); } }',
+        SupportedLanguages.CSharp,
+      );
+      const match = captures.find((c) => c.calledName === 'Info');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      // typeAsReceiverHeuristic is set on the config/extractor level (true for C#),
+      // but the uppercase check happens in parse-worker, not the extractor itself
+      expect(result!.typeAsReceiverHeuristic).toBe(true);
+      expect(result!.receiverName).toBe('logger');
+    });
+  });
+
+  describe('Go', () => {
+    const extractor = createCallExtractor(goCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(Go);
+      const captures = extractCallCaptures(
+        parser,
+        'package main\nfunc main() { doStuff() }',
+        SupportedLanguages.Go,
+      );
+      const match = captures.find((c) => c.calledName === 'doStuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('doStuff');
+      expect(result!.callForm).toBe('free');
+    });
+  });
+
+  describe('Rust', () => {
+    const extractor = createCallExtractor(rustCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(Rust);
+      const captures = extractCallCaptures(
+        parser,
+        'fn main() { do_stuff(); }',
+        SupportedLanguages.Rust,
+      );
+      const match = captures.find((c) => c.calledName === 'do_stuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('do_stuff');
+    });
+  });
+
+  describe('C++', () => {
+    const extractor = createCallExtractor(cppCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(CPP);
+      const captures = extractCallCaptures(
+        parser,
+        'void f() { doStuff(); }',
+        SupportedLanguages.CPlusPlus,
+      );
+      const match = captures.find((c) => c.calledName === 'doStuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('doStuff');
+      expect(result!.callForm).toBe('free');
+    });
+  });
+
+  describe('PHP', () => {
+    const extractor = createCallExtractor(phpCallConfig);
+
+    it('extracts free function call', () => {
+      parser.setLanguage(PHP.php);
+      const captures = extractCallCaptures(parser, '<?php doStuff(); ?>', SupportedLanguages.PHP);
+      const match = captures.find((c) => c.calledName === 'doStuff');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('doStuff');
+    });
+  });
+
+  describe('Ruby', () => {
+    const extractor = createCallExtractor(rubyCallConfig);
+
+    it('extracts member call', () => {
+      parser.setLanguage(Ruby);
+      const captures = extractCallCaptures(parser, 'user.save()', SupportedLanguages.Ruby);
+      const match = captures.find((c) => c.calledName === 'save');
+      expect(match).toBeDefined();
+      const result = extractor.extract(match!.callNode, match!.nameNode!);
+      expect(result).not.toBeNull();
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('user');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Language-specific call site extraction (Java :: method references)
+// ---------------------------------------------------------------------------
+
+describe('Java method_reference extraction', () => {
+  const parser = new Parser();
+  parser.setLanguage(Java);
+  const extractor = createCallExtractor(javaCallConfig);
+
+  it('extracts Type::new as constructor', () => {
+    const captures = extractCallCaptures(
+      parser,
+      'class A { void m() { stream.map(User::new); } }',
+      SupportedLanguages.Java,
+    );
+    // The method_reference should be captured as @call
+    const match = captures.find((c) => c.callNode.type === 'method_reference');
+    if (match) {
+      const result = extractor.extract(match.callNode, undefined);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('User');
+      expect(result!.callForm).toBe('constructor');
+    }
+  });
+
+  it('extracts Type::method as member call', () => {
+    const captures = extractCallCaptures(
+      parser,
+      'class A { void m() { stream.map(User::getName); } }',
+      SupportedLanguages.Java,
+    );
+    const match = captures.find((c) => c.callNode.type === 'method_reference');
+    if (match) {
+      const result = extractor.extract(match.callNode, undefined);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('getName');
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('User');
+      expect(result!.typeAsReceiverHeuristic).toBe(true);
+    }
+  });
+
+  it('extracts this::method as member call', () => {
+    const captures = extractCallCaptures(
+      parser,
+      'class A { void m() { stream.map(this::process); } }',
+      SupportedLanguages.Java,
+    );
+    const match = captures.find((c) => c.callNode.type === 'method_reference');
+    if (match) {
+      const result = extractor.extract(match.callNode, undefined);
+      expect(result).not.toBeNull();
+      expect(result!.calledName).toBe('process');
+      expect(result!.callForm).toBe('member');
+      expect(result!.receiverName).toBe('this');
+    }
+  });
+
+  it('extractLanguageCallSite returns null for non-method_reference nodes', () => {
+    const captures = extractCallCaptures(
+      parser,
+      'class A { void m() { doStuff(); } }',
+      SupportedLanguages.Java,
+    );
+    const match = captures.find((c) => c.calledName === 'doStuff');
+    expect(match).toBeDefined();
+    // Language seed should be null for regular calls
+    const langSeed = extractor.extract(match!.callNode, undefined);
+    expect(langSeed).toBeNull();
+    // But full extraction with callNameNode should work
+    const full = extractor.extract(match!.callNode, match!.nameNode!);
+    expect(full).not.toBeNull();
+    expect(full!.calledName).toBe('doStuff');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// typeAsReceiverHeuristic config flag
+// ---------------------------------------------------------------------------
+
+describe('typeAsReceiverHeuristic config', () => {
+  it('JVM configs set typeAsReceiverHeuristic', () => {
+    expect(javaCallConfig.typeAsReceiverHeuristic).toBe(true);
+    expect(kotlinCallConfig.typeAsReceiverHeuristic).toBe(true);
+  });
+
+  it('C# config sets typeAsReceiverHeuristic', () => {
+    expect(csharpCallConfig.typeAsReceiverHeuristic).toBe(true);
+  });
+
+  it('other configs do not set typeAsReceiverHeuristic', () => {
+    expect(typescriptCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(javascriptCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(pythonCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(rubyCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(goCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(rustCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(cCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(cppCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(phpCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(dartCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+    expect(swiftCallConfig.typeAsReceiverHeuristic).toBeFalsy();
+  });
+});
diff --git a/gitnexus/test/unit/call-routing/ruby.test.ts b/gitnexus/test/unit/call-routing/ruby.test.ts
index e5e6858b3..1c602f3aa 100644
--- a/gitnexus/test/unit/call-routing/ruby.test.ts
+++ b/gitnexus/test/unit/call-routing/ruby.test.ts
@@ -251,197 +251,29 @@ describe('routeRubyCall — require / require_relative', () => {
 });
 
 // ── include / extend / prepend ───────────────────────────────────────────────
+// Heritage routing (include/extend/prepend) is now handled by
+// heritageExtractor.extractFromCall before the call router runs.
+// routeRubyCall returns 'skip' so these calls don't fall through
+// to normal call processing.
 
-describe('routeRubyCall — include / extend / prepend', () => {
-  it('include with a single constant arg inside a class returns heritage', () => {
+describe('routeRubyCall — include / extend / prepend (now delegated to heritageExtractor)', () => {
+  it('include returns skip (heritage handled by heritageExtractor)', () => {
     const node = makeHeritageCallNode([makeConstantArg('Serializable')], 'class', 'User');
-    const result = routeRubyCall('include', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [{ enclosingClass: 'User', mixinName: 'Serializable', heritageKind: 'include' }],
-    });
+    expect(routeRubyCall('include', node)).toEqual({ kind: 'skip' });
   });
 
-  it('extend with a scope_resolution arg (Foo::Bar) returns heritage', () => {
+  it('extend returns skip (heritage handled by heritageExtractor)', () => {
     const node = makeHeritageCallNode(
       [makeScopeResolutionArg('ActiveSupport::Concern')],
       'class',
       'Post',
     );
-    const result = routeRubyCall('extend', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [
-        { enclosingClass: 'Post', mixinName: 'ActiveSupport::Concern', heritageKind: 'extend' },
-      ],
-    });
+    expect(routeRubyCall('extend', node)).toEqual({ kind: 'skip' });
   });
 
-  it('prepend records heritageKind as "prepend"', () => {
+  it('prepend returns skip (heritage handled by heritageExtractor)', () => {
     const node = makeHeritageCallNode([makeConstantArg('Instrumented')], 'class', 'Service');
-    const result = routeRubyCall('prepend', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [{ enclosingClass: 'Service', mixinName: 'Instrumented', heritageKind: 'prepend' }],
-    });
-  });
-
-  it('include inside a module (not a class) still resolves enclosing name', () => {
-    const node = makeHeritageCallNode([makeConstantArg('Helpers')], 'module', 'ApplicationHelper');
-    const result = routeRubyCall('include', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [
-        { enclosingClass: 'ApplicationHelper', mixinName: 'Helpers', heritageKind: 'include' },
-      ],
-    });
-  });
-
-  it('include with multiple constant args produces one item per arg', () => {
-    const args = [makeConstantArg('Mod1'), makeConstantArg('Mod2'), makeConstantArg('Mod3')];
-    const node = makeHeritageCallNode(args, 'class', 'MyClass');
-    const result = routeRubyCall('include', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [
-        { enclosingClass: 'MyClass', mixinName: 'Mod1', heritageKind: 'include' },
-        { enclosingClass: 'MyClass', mixinName: 'Mod2', heritageKind: 'include' },
-        { enclosingClass: 'MyClass', mixinName: 'Mod3', heritageKind: 'include' },
-      ],
-    });
-  });
-
-  it('returns skip when no enclosing class or module is found in parent chain', () => {
-    const node = makeHeritageCallNode([makeConstantArg('Mod')], null, null);
-    expect(routeRubyCall('include', node)).toEqual({ kind: 'skip' });
-  });
-
-  it('returns skip when enclosing class node has no name child', () => {
-    // nameNode is undefined — childForFieldName('name') returns undefined
-    const argList: MockNode = {
-      type: 'argument_list',
-      text: '',
-      children: [makeConstantArg('Mod')],
-    };
-    const classNode: MockNode = {
-      type: 'class',
-      text: '',
-      parent: null,
-      childForFieldName: (_name: string) => undefined,
-    };
-    const bodyNode: MockNode = { type: 'body', text: '', parent: classNode };
-    const callNode: MockNode = {
-      type: 'call',
-      text: '',
-      parent: bodyNode,
-      childForFieldName: (name: string) => (name === 'arguments' ? argList : undefined),
-    };
-    expect(routeRubyCall('include', callNode)).toEqual({ kind: 'skip' });
-  });
-
-  it('returns skip when arg list contains only non-constant/non-scope_resolution args', () => {
-    const node = makeHeritageCallNode([makeIdentifierArg('some_var')], 'class', 'Foo');
-    expect(routeRubyCall('include', node)).toEqual({ kind: 'skip' });
-  });
-
-  it('returns skip when arg list is empty', () => {
-    const node = makeHeritageCallNode([], 'class', 'Foo');
-    expect(routeRubyCall('include', node)).toEqual({ kind: 'skip' });
-  });
-
-  it('walks nested scopes to find the nearest enclosing class', () => {
-    // callNode is 5 levels deep inside a class body
-    const node = makeHeritageCallNode([makeConstantArg('DeepMixin')], 'class', 'DeepClass', 5);
-    const result = routeRubyCall('include', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [{ enclosingClass: 'DeepClass', mixinName: 'DeepMixin', heritageKind: 'include' }],
-    });
-  });
-
-  it('returns skip when parent depth exceeds MAX_PARENT_DEPTH (50)', () => {
-    // Build a chain of 51 intermediate nodes with no class/module in it
-    const argList: MockNode = {
-      type: 'argument_list',
-      text: '',
-      children: [makeConstantArg('Mod')],
-    };
-    const callNode: MockNode = {
-      type: 'call',
-      text: '',
-      parent: null,
-      childForFieldName: (name: string) => (name === 'arguments' ? argList : undefined),
-    };
-
-    let current: MockNode = callNode;
-    // Create 51 parents — all plain body nodes, never a class/module
-    for (let i = 0; i < 51; i++) {
-      const parent: MockNode = { type: 'body_statement', text: '', parent: null };
-      current.parent = parent;
-      current = parent;
-    }
-
-    expect(routeRubyCall('include', callNode)).toEqual({ kind: 'skip' });
-  });
-
-  it('finds class at exactly depth 50 (boundary — must succeed)', () => {
-    // 49 plain wrappers, then the class at depth 50
-    const argList: MockNode = {
-      type: 'argument_list',
-      text: '',
-      children: [makeConstantArg('BoundaryMixin')],
-    };
-    const callNode: MockNode = {
-      type: 'call',
-      text: '',
-      parent: null,
-      childForFieldName: (name: string) => (name === 'arguments' ? argList : undefined),
-    };
-
-    let leaf: MockNode = callNode;
-    for (let i = 0; i < 49; i++) {
-      const wrapper: MockNode = { type: 'body_statement', text: '', parent: null };
-      leaf.parent = wrapper;
-      leaf = wrapper;
-    }
-
-    const nameNode: MockNode = { type: 'constant', text: 'BoundaryClass' };
-    const classNode: MockNode = {
-      type: 'class',
-      text: '',
-      parent: null,
-      childForFieldName: (name: string) => (name === 'name' ? nameNode : undefined),
-    };
-    leaf.parent = classNode;
-
-    const result = routeRubyCall('include', callNode);
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [
-        { enclosingClass: 'BoundaryClass', mixinName: 'BoundaryMixin', heritageKind: 'include' },
-      ],
-    });
-  });
-
-  it('skips non-constant args mixed with constant args, collecting only constants', () => {
-    const args = [
-      makeIdentifierArg('local_var'),
-      makeConstantArg('ValidMixin'),
-      makeIdentifierArg('another_var'),
-    ];
-    const node = makeHeritageCallNode(args, 'class', 'Foo');
-    const result = routeRubyCall('include', node);
-
-    expect(result).toEqual({
-      kind: 'heritage',
-      items: [{ enclosingClass: 'Foo', mixinName: 'ValidMixin', heritageKind: 'include' }],
-    });
+    expect(routeRubyCall('prepend', node)).toEqual({ kind: 'skip' });
   });
 });
 
diff --git a/gitnexus/test/unit/calltool-dispatch.test.ts b/gitnexus/test/unit/calltool-dispatch.test.ts
index ebccb42a2..9a90b7030 100644
--- a/gitnexus/test/unit/calltool-dispatch.test.ts
+++ b/gitnexus/test/unit/calltool-dispatch.test.ts
@@ -248,6 +248,215 @@ describe('LocalBackend.callTool', () => {
     const result = await backend.callTool('context', { name: 'main' });
     expect(result.status).toBe('ambiguous');
     expect(result.candidates).toHaveLength(2);
+
+    // #470: every candidate carries a relevance score in [0, 1] and the list
+    // is sorted descending by score (with deterministic tiebreakers).
+    for (const c of result.candidates) {
+      expect(typeof c.score).toBe('number');
+      expect(c.score).toBeGreaterThanOrEqual(0);
+      expect(c.score).toBeLessThanOrEqual(1);
+    }
+    expect(result.candidates[0].score).toBeGreaterThanOrEqual(result.candidates[1].score);
+  });
+
+  it('context tool ranks file_path match higher than non-match (#470)', async () => {
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'func:handleConnect:1',
+        name: 'handleConnect',
+        type: 'Function',
+        filePath: 'src/lib/socket.ts',
+        startLine: 10,
+        endLine: 20,
+      },
+      {
+        id: 'func:handleConnect:2',
+        name: 'handleConnect',
+        type: 'Function',
+        filePath: 'src/App.tsx',
+        startLine: 42,
+        endLine: 60,
+      },
+    ]);
+    const result = await backend.callTool('context', {
+      name: 'handleConnect',
+      file_path: 'App.tsx',
+    });
+    // In production, `WHERE n.filePath CONTAINS $filePath` would pre-filter
+    // at the DB layer and only `src/App.tsx` would come back — resolving
+    // via the single-candidate early return rather than via scoring. The
+    // `executeParameterized` mock here returns both rows regardless of the
+    // WHERE clause parameters, so this asserts that the resolver ends up
+    // picking the App.tsx candidate in either case (via mock-relaxed DB
+    // pre-filter or via scoring promotion). The dedicated scoring-promotion
+    // path is covered by the next `it()` block below.
+    expect(result.status).toBe('found');
+    expect(result.symbol.filePath).toBe('src/App.tsx');
+  });
+
+  it('context tool promotes top candidate via scoring when multiple rows survive DB pre-filter (#470)', async () => {
+    // This test explicitly exercises the scored-promotion path (#470
+    // review): both candidates satisfy the file_path hint (so DB
+    // pre-filter would return both in production), and promotion is
+    // determined purely by the combined file_path + kind score.
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'fn:App:1',
+        name: 'render',
+        type: 'Function',
+        filePath: 'src/components/App.tsx',
+        startLine: 10,
+        endLine: 20,
+      },
+      {
+        id: 'method:App:1',
+        name: 'render',
+        type: 'Method',
+        filePath: 'src/pages/App.tsx',
+        startLine: 5,
+        endLine: 15,
+      },
+    ]);
+    const result = await backend.callTool('context', {
+      name: 'render',
+      file_path: 'App.tsx',
+      kind: 'Function',
+    });
+    // Expected scoring:
+    //   Function candidate: 0.50 base + 0.40 file_path + 0.20 kind = 1.10 → cap 1.00
+    //   Method candidate:   0.50 base + 0.40 file_path + 0.00 kind = 0.90
+    // Top score ≥ 0.95 and beats runner-up by 0.10 → confident promotion
+    // to `{ status: 'found' }` with the Function.
+    expect(result.status).toBe('found');
+    expect(result.symbol.filePath).toBe('src/components/App.tsx');
+    expect(result.symbol.kind).toBe('Function');
+  });
+
+  it('context tool returns ranked candidates when file_path only partially narrows (#470)', async () => {
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'func:foo:1',
+        name: 'foo',
+        type: 'Function',
+        filePath: 'src/a.ts',
+        startLine: 1,
+        endLine: 5,
+      },
+      {
+        id: 'func:foo:2',
+        name: 'foo',
+        type: 'Function',
+        filePath: 'src/b.ts',
+        startLine: 1,
+        endLine: 5,
+      },
+    ]);
+    // No hints → both candidates score 0.56 (0.50 base + 0.06 Function
+    // priority). Tied scores fall back to deterministic tiebreakers.
+    const result = await backend.callTool('context', { name: 'foo' });
+    expect(result.status).toBe('ambiguous');
+    expect(result.candidates).toHaveLength(2);
+    expect(result.candidates[0].score).toBeCloseTo(0.56, 2);
+    expect(result.candidates[1].score).toBeCloseTo(0.56, 2);
+  });
+
+  it('context tool boosts the candidate whose kind matches the hint (#470)', async () => {
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'method:save:1',
+        name: 'save',
+        type: 'Method',
+        filePath: 'src/service.ts',
+        startLine: 10,
+        endLine: 20,
+      },
+      {
+        id: 'func:save:1',
+        name: 'save',
+        type: 'Function',
+        filePath: 'src/util.ts',
+        startLine: 5,
+        endLine: 15,
+      },
+    ]);
+    const result = await backend.callTool('context', { name: 'save', kind: 'Function' });
+    // When kind hint is given, kind-priority bonus is suppressed and +0.20
+    // kind-match bonus applies instead. Function becomes the top candidate.
+    expect(result.status).toBe('ambiguous');
+    expect(result.candidates[0].kind).toBe('Function');
+    expect(result.candidates[0].score).toBeGreaterThan(result.candidates[1].score);
+  });
+
+  it('impact tool returns ambiguous shape with ranked candidates when target has multiple matches (#470)', async () => {
+    // resolveSymbolCandidates issues a single name query; mock it to return
+    // two Function rows in different files with no hints.
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'func:login:1',
+        name: 'login',
+        type: 'Function',
+        filePath: 'src/auth.ts',
+        startLine: 5,
+        endLine: 15,
+      },
+      {
+        id: 'func:login:2',
+        name: 'login',
+        type: 'Function',
+        filePath: 'src/admin/login.ts',
+        startLine: 8,
+        endLine: 20,
+      },
+    ]);
+
+    const result = await backend.callTool('impact', { target: 'login', direction: 'upstream' });
+
+    expect(result.status).toBe('ambiguous');
+    expect(result.candidates).toHaveLength(2);
+    expect(result.impactedCount).toBe(0);
+    expect(result.risk).toBe('UNKNOWN');
+    expect(result.target.name).toBe('login');
+    for (const c of result.candidates) {
+      expect(typeof c.score).toBe('number');
+      expect(c.uid).toBeDefined();
+      expect(c.kind).toBe('Function');
+    }
+  });
+
+  it('impact tool resolves via target_uid without running the name-based resolver (#470)', async () => {
+    // UID path: exactly one executeParameterized call for the lookup, then
+    // the BFS issues executeQuery calls (which we mock empty). Crucially,
+    // no `WHERE n.name =` query fires.
+    (executeParameterized as any).mockResolvedValue([
+      {
+        id: 'uid:1234',
+        name: 'pickedByUid',
+        type: 'Function',
+        filePath: 'src/pick.ts',
+        startLine: 1,
+        endLine: 10,
+      },
+    ]);
+    (executeQuery as any).mockResolvedValue([]);
+
+    const result = await backend.callTool('impact', {
+      target: 'ignoredName',
+      target_uid: 'uid:1234',
+      direction: 'upstream',
+    });
+
+    // No ambiguous shape and no name-lookup error — the uid short-circuit won.
+    expect(result.status).not.toBe('ambiguous');
+    expect(result.target).toBeDefined();
+
+    // All executeParameterized calls this test dispatched must have been
+    // uid-keyed, never name-keyed. That proves the name resolver was skipped.
+    const calls = (executeParameterized as any).mock.calls as Array<
+      [string, string, Record<string, unknown>]
+    >;
+    for (const [, cypher] of calls) {
+      expect(cypher).not.toMatch(/WHERE n\.name = \$symName/);
+    }
   });
 
   it('dispatches impact tool', async () => {
diff --git a/gitnexus/test/unit/chunker.test.ts b/gitnexus/test/unit/chunker.test.ts
new file mode 100644
index 000000000..77ac839ba
--- /dev/null
+++ b/gitnexus/test/unit/chunker.test.ts
@@ -0,0 +1,336 @@
+/**
+ * Unit tests for character chunking and AST-aware chunking logic.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { characterChunk } from '../../src/core/embeddings/character-chunk.js';
+
+const { createParserForLanguage } = vi.hoisted(() => ({
+  createParserForLanguage: vi.fn(),
+}));
+
+const { getLanguageFromFilename } = vi.hoisted(() => ({
+  getLanguageFromFilename: vi.fn((filePath: string) =>
+    filePath.endsWith('.rs') ? 'rust' : 'typescript',
+  ),
+}));
+
+vi.mock('../../src/core/tree-sitter/parser-loader.js', () => ({
+  createParserForLanguage,
+  isLanguageAvailable: vi.fn().mockReturnValue(true),
+  resolveLanguageKey: vi.fn((language: string, filePath?: string) =>
+    language === 'typescript' && filePath?.endsWith('.tsx') ? 'typescript:tsx' : language,
+  ),
+}));
+
+vi.mock('gitnexus-shared', () => ({
+  getLanguageFromFilename,
+}));
+
+import { chunkNode } from '../../src/core/embeddings/chunker.js';
+
+type FakeNode = {
+  type: string;
+  startIndex: number;
+  endIndex: number;
+  namedChildCount: number;
+  namedChild: (index: number) => FakeNode | null;
+  childForFieldName?: (name: string) => FakeNode | null;
+};
+
+const makeFakeNode = (
+  type: string,
+  startIndex: number,
+  endIndex: number,
+  children: FakeNode[] = [],
+  fields: Record<string, FakeNode> = {},
+): FakeNode => ({
+  type,
+  startIndex,
+  endIndex,
+  namedChildCount: children.length,
+  namedChild: (index: number) => children[index] ?? null,
+  childForFieldName: (name: string) => fields[name] ?? null,
+});
+
+const makeFunctionTree = (content: string, statementTexts: string[]) => {
+  const statementNodes = statementTexts.map((text) => {
+    const startIndex = content.indexOf(text);
+    return makeFakeNode('expression_statement', startIndex, startIndex + text.length);
+  });
+
+  const bodyStart = content.indexOf('{');
+  const bodyEnd = content.lastIndexOf('}') + 1;
+  const bodyNode = makeFakeNode('statement_block', bodyStart, bodyEnd, statementNodes);
+  const fnNode = makeFakeNode('function_declaration', 0, bodyEnd, [], { body: bodyNode });
+  const root = makeFakeNode('program', 0, content.length, [fnNode]);
+
+  return {
+    rootNode: root,
+  };
+};
+
+const makeTypedFunctionTree = (nodeType: string, content: string, statementTexts: string[]) => {
+  const statementNodes = statementTexts.map((text) => {
+    const startIndex = content.indexOf(text);
+    return makeFakeNode('expression_statement', startIndex, startIndex + text.length);
+  });
+
+  const bodyStart = content.indexOf('{');
+  const bodyEnd = content.lastIndexOf('}') + 1;
+  const bodyNode = makeFakeNode('statement_block', bodyStart, bodyEnd, statementNodes);
+  const fnNode = makeFakeNode(nodeType, 0, bodyEnd, [], { body: bodyNode });
+  const root = makeFakeNode('program', 0, content.length, [fnNode]);
+
+  return {
+    rootNode: root,
+  };
+};
+
+const makeDeclarationTree = (
+  nodeType: string,
+  bodyType: string,
+  content: string,
+  memberTexts: string[],
+) => {
+  let searchFrom = 0;
+  const memberNodes = memberTexts.map((text, index) => {
+    const startIndex = content.indexOf(text, searchFrom);
+    if (startIndex < 0) {
+      throw new Error(`Unable to locate member text: ${text}`);
+    }
+    searchFrom = startIndex + text.length;
+    const inferredType =
+      text.includes('()') || text.includes(': void') || text.includes(': boolean')
+        ? 'method_definition'
+        : 'field_definition';
+    return makeFakeNode(inferredType, startIndex, startIndex + text.length);
+  });
+
+  const bodyStart = content.indexOf('{');
+  const bodyEnd = content.lastIndexOf('}') + 1;
+  const bodyNode = makeFakeNode(bodyType, bodyStart, bodyEnd, memberNodes);
+  const declNode = makeFakeNode(nodeType, 0, bodyEnd, [bodyNode], { body: bodyNode });
+  const root = makeFakeNode('program', 0, content.length, [declNode]);
+
+  return {
+    rootNode: root,
+  };
+};
+
+describe('characterChunk', () => {
+  it('returns single chunk when content fits', () => {
+    const result = characterChunk('short content', 1, 5, 1200, 120);
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toBe('short content');
+    expect(result[0].chunkIndex).toBe(0);
+    expect(result[0].startOffset).toBe(0);
+    expect(result[0].endOffset).toBe('short content'.length);
+    expect(result[0].startLine).toBe(1);
+    expect(result[0].endLine).toBe(5);
+  });
+
+  it('splits long content into multiple chunks', () => {
+    const longContent = 'a'.repeat(3000);
+    const result = characterChunk(longContent, 1, 100, 1200, 120);
+    expect(result.length).toBeGreaterThan(1);
+    for (const chunk of result) {
+      expect(chunk.text.length).toBeLessThanOrEqual(1200);
+    }
+  });
+
+  it('maintains sequential chunkIndex and offsets', () => {
+    const longContent = 'x'.repeat(3000);
+    const result = characterChunk(longContent, 1, 100, 1200, 120);
+    for (let i = 0; i < result.length; i++) {
+      expect(result[i].chunkIndex).toBe(i);
+      expect(result[i].text).toBe(longContent.slice(result[i].startOffset, result[i].endOffset));
+    }
+  });
+
+  it('includes overlap between chunks', () => {
+    const content = 'abcdefghij'.repeat(200);
+    const result = characterChunk(content, 1, 50, 500, 50);
+    if (result.length > 1) {
+      const endOfFirst = result[0].text.slice(-50);
+      expect(result[1].text.startsWith(endOfFirst)).toBe(true);
+    }
+  });
+
+  it('keeps the first chunk on the real starting line', () => {
+    const content = 'alpha\nbeta\ngamma';
+    const result = characterChunk(content, 38, 40, 6, 0);
+    expect(result[0].startLine).toBe(38);
+  });
+
+  it('does not advance endLine when a chunk ends at a newline boundary', () => {
+    const content = 'aaa\nbbb\nccc';
+    const result = characterChunk(content, 10, 12, 4, 0);
+    expect(result[0].text).toBe('aaa\n');
+    expect(result[0].startLine).toBe(10);
+    expect(result[0].endLine).toBe(10);
+  });
+});
+
+describe('chunkNode', () => {
+  beforeEach(() => {
+    createParserForLanguage.mockReset();
+    getLanguageFromFilename.mockImplementation((filePath: string) =>
+      filePath.endsWith('.rs') ? 'rust' : 'typescript',
+    );
+  });
+
+  it('returns single chunk for short content', async () => {
+    const result = await chunkNode('Function', 'short', 'test.ts', 1, 5, 1200, 120);
+    expect(result).toHaveLength(1);
+    expect(result[0].chunkIndex).toBe(0);
+    expect(result[0].text).toBe('short');
+    expect(result[0].startOffset).toBe(0);
+  });
+
+  it('splits a class by members instead of raw character windows', async () => {
+    const content = [
+      'class Parser {',
+      '  options: ParserOptions;',
+      '  cache: Map<string, any>;',
+      '  parseJSON() { return JSON.parse("{}"); }',
+      '  validate() { return true; }',
+      '}',
+    ].join('\n');
+    const tree = makeDeclarationTree('class_declaration', 'class_body', content, [
+      'options: ParserOptions;',
+      'cache: Map<string, any>;',
+      'parseJSON() { return JSON.parse("{}"); }',
+      'validate() { return true; }',
+    ]);
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(tree),
+    });
+
+    const result = await chunkNode('Class', content, 'test.ts', 1, 6, 90, 0);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].text).toContain('options: ParserOptions;');
+    expect(result[0].text).toContain('cache: Map<string, any>;');
+    expect(result[1].text).toContain('parseJSON()');
+    expect(result[1].text).toContain('validate()');
+    expect(result[0].startLine).toBe(2);
+    expect(result[1].startLine).toBe(4);
+  });
+
+  it('preserves interface signatures via declaration-aware chunking', async () => {
+    const content = [
+      'interface Handler {',
+      '  handle(event: Event): void;',
+      '  validate(input: string): boolean;',
+      '  readonly name: string;',
+      '}',
+    ].join('\n');
+    const tree = makeDeclarationTree('interface_declaration', 'object_type', content, [
+      'handle(event: Event): void;',
+      'validate(input: string): boolean;',
+      'readonly name: string;',
+    ]);
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(tree),
+    });
+
+    const result = await chunkNode('Interface', content, 'test.ts', 10, 14, 500, 0);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].text).toContain('handle(event: Event): void;');
+    expect(result[0].text).toContain('validate(input: string): boolean;');
+    expect(result[0].text).toContain('readonly name: string;');
+  });
+
+  it('splits a function into multiple AST-aware chunks using snippet offsets', async () => {
+    const content = [
+      'function example() {',
+      '  const first = 1;',
+      '',
+      '  const second = 2;',
+      '  return first + second;',
+      '}',
+    ].join('\n');
+    const tree = makeFunctionTree(content, [
+      'const first = 1;',
+      'const second = 2;',
+      'return first + second;',
+    ]);
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(tree),
+    });
+
+    const result = await chunkNode('Function', content, 'test.ts', 38, 43, 68, 0);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].startOffset).toBe(0);
+    expect(result[0].endOffset).toBeGreaterThan(content.indexOf('const second = 2;'));
+    expect(result[0].startLine).toBe(38);
+    expect(result[0].endLine).toBe(42);
+    expect(result[0].text).toContain('function example() {');
+    expect(result[0].text).toContain('\n\n  const second = 2;');
+    expect(result[1].startOffset).toBeGreaterThan(content.indexOf('const second = 2;'));
+    expect(result[1].startLine).toBeGreaterThanOrEqual(42);
+    expect(result[1].endLine).toBe(43);
+    expect(result[1].text.length).toBeGreaterThan(0);
+  });
+
+  it('uses AST-aware chunking for Constructor labels too', async () => {
+    const content = [
+      'constructor() {',
+      '  this.ready = true;',
+      '  this.mode = "prod";',
+      '  this.start();',
+      '}',
+    ].join('\n');
+    const tree = makeFunctionTree(content, [
+      'this.ready = true;',
+      'this.mode = "prod";',
+      'this.start();',
+    ]);
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(tree),
+    });
+
+    const result = await chunkNode('Constructor', content, 'test.ts', 12, 16, 55, 0);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].text).toContain('constructor() {');
+    expect(result[0].startLine).toBe(12);
+    expect(result[1].startLine).toBe(14);
+  });
+
+  it('recognizes Rust function_item nodes for AST-aware chunking', async () => {
+    const content = [
+      'fn build_user() {',
+      '    let first = 1;',
+      '    let second = 2;',
+      '    return first + second;',
+      '}',
+    ].join('\n');
+    const tree = makeTypedFunctionTree('function_item', content, [
+      'let first = 1;',
+      'let second = 2;',
+      'return first + second;',
+    ]);
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(tree),
+    });
+
+    const result = await chunkNode('Function', content, 'test.rs', 20, 24, 52, 0);
+
+    expect(result).toHaveLength(2);
+    expect(result[0].text).toContain('fn build_user() {');
+    expect(result[0].startLine).toBe(20);
+    expect(result[1].text).toContain('return first + second;');
+  });
+
+  it('falls back to character chunks when AST parsing fails', async () => {
+    createParserForLanguage.mockRejectedValueOnce(new Error('no parser'));
+
+    const content = 'x'.repeat(3000);
+    const result = await chunkNode('Function', content, 'test.tsx', 1, 100, 1200, 120);
+    expect(result.length).toBeGreaterThan(1);
+    expect(result[0].startOffset).toBe(0);
+  });
+});
diff --git a/gitnexus/test/unit/dart-import-resolver.test.ts b/gitnexus/test/unit/dart-import-resolver.test.ts
index 0c9eff1ca..ff5dfdc3e 100644
--- a/gitnexus/test/unit/dart-import-resolver.test.ts
+++ b/gitnexus/test/unit/dart-import-resolver.test.ts
@@ -1,15 +1,35 @@
+/**
+ * Unit tests for the production Dart import resolution strategies.
+ *
+ * Tests dartPackageStrategy and dartRelativeStrategy from configs/dart.ts —
+ * the actual strategies composed by createImportResolver(dartImportConfig).
+ *
+ * Key behavioral note:
+ * - dartPackageStrategy returns { kind: 'files', files: [] } (absorbing sentinel)
+ *   for dart: SDK imports and unresolved external packages, which stops the
+ *   strategy chain. This differs from the old monolithic resolver that returned null.
+ *   Both produce zero import edges at runtime (applyImportResult treats them identically).
+ */
+
 import { describe, it, expect } from 'vitest';
-import { resolveDartImport } from '../../src/core/ingestion/import-resolvers/dart.js';
+import {
+  dartPackageStrategy,
+  dartRelativeStrategy,
+} from '../../src/core/ingestion/import-resolvers/configs/dart.js';
+import { createImportResolver } from '../../src/core/ingestion/import-resolvers/resolver-factory.js';
+import { dartImportConfig } from '../../src/core/ingestion/import-resolvers/configs/dart.js';
 import type { ResolveCtx } from '../../src/core/ingestion/import-resolvers/types.js';
+import { buildSuffixIndex } from '../../src/core/ingestion/import-resolvers/utils.js';
 
 function makeCtx(files: string[]): ResolveCtx {
   const allFileList = files;
-  const normalizedFileList = files.map((f) => f.toLowerCase());
+  const normalizedFileList = files.map((f) => f.replace(/\\/g, '/'));
+  const index = buildSuffixIndex(normalizedFileList, allFileList);
   return {
     allFilePaths: new Set(files),
     allFileList,
     normalizedFileList,
-    index: undefined as any,
+    index,
     resolveCache: new Map(),
     configs: {
       tsconfigPaths: null,
@@ -21,59 +41,109 @@ function makeCtx(files: string[]): ResolveCtx {
   };
 }
 
-describe('Dart import resolver', () => {
+// ---------------------------------------------------------------------------
+// dartPackageStrategy — absorbs SDK / external package imports
+// ---------------------------------------------------------------------------
+
+describe('dartPackageStrategy', () => {
   describe('dart: SDK imports', () => {
-    it('skips dart:async', () => {
-      const result = resolveDartImport("'dart:async'", 'lib/main.dart', makeCtx([]));
-      expect(result).toBeNull();
+    it('absorbs dart:async with empty-files sentinel', () => {
+      const result = dartPackageStrategy("'dart:async'", 'lib/main.dart', makeCtx([]));
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
 
-    it('skips dart:io', () => {
-      const result = resolveDartImport("'dart:io'", 'lib/main.dart', makeCtx([]));
-      expect(result).toBeNull();
+    it('absorbs dart:io with empty-files sentinel', () => {
+      const result = dartPackageStrategy("'dart:io'", 'lib/main.dart', makeCtx([]));
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
   });
 
   describe('package: imports', () => {
     it('resolves local package import to lib/', () => {
       const ctx = makeCtx(['lib/models/user.dart', 'lib/main.dart']);
-      const result = resolveDartImport("'package:my_app/models/user.dart'", 'lib/main.dart', ctx);
+      const result = dartPackageStrategy("'package:my_app/models/user.dart'", 'lib/main.dart', ctx);
       expect(result).toEqual({ kind: 'files', files: ['lib/models/user.dart'] });
     });
 
-    it('returns null for external package imports', () => {
+    it('absorbs external package imports with empty-files sentinel', () => {
       const ctx = makeCtx(['lib/main.dart']);
-      const result = resolveDartImport("'package:http/http.dart'", 'lib/main.dart', ctx);
-      expect(result).toBeNull();
+      const result = dartPackageStrategy("'package:http/http.dart'", 'lib/main.dart', ctx);
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
 
-    it('returns null for malformed package import (no slash)', () => {
-      const result = resolveDartImport("'package:http'", 'lib/main.dart', makeCtx([]));
-      expect(result).toBeNull();
+    it('absorbs malformed package import (no slash) with empty-files sentinel', () => {
+      const result = dartPackageStrategy("'package:http'", 'lib/main.dart', makeCtx([]));
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
   });
 
   describe('relative imports', () => {
-    it('resolves relative import via standard resolver', () => {
-      const ctx = makeCtx(['lib/models/user.dart', 'lib/main.dart']);
-      const result = resolveDartImport("'models/user.dart'", 'lib/main.dart', ctx);
-      // resolveStandard handles relative path resolution
-      // The exact result depends on the standard resolver — we just check it doesn't crash
-      expect(result === null || result?.kind === 'files').toBe(true);
+    it('returns null for relative imports (chains to dartRelativeStrategy)', () => {
+      const ctx = makeCtx([]);
+      const result = dartPackageStrategy("'models.dart'", 'lib/main.dart', ctx);
+      expect(result).toBeNull();
     });
   });
 
   describe('quote stripping', () => {
     it('strips single quotes', () => {
-      const ctx = makeCtx([]);
-      const result = resolveDartImport("'dart:core'", 'lib/main.dart', ctx);
-      expect(result).toBeNull(); // dart: is skipped, proving quotes were stripped
+      const result = dartPackageStrategy("'dart:core'", 'lib/main.dart', makeCtx([]));
+      // dart: is absorbed, proving quotes were stripped
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
 
     it('strips double quotes', () => {
-      const ctx = makeCtx([]);
-      const result = resolveDartImport('"dart:core"', 'lib/main.dart', ctx);
-      expect(result).toBeNull();
+      const result = dartPackageStrategy('"dart:core"', 'lib/main.dart', makeCtx([]));
+      expect(result).toEqual({ kind: 'files', files: [] });
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// dartRelativeStrategy — bare relative paths via standard resolution
+// ---------------------------------------------------------------------------
+
+describe('dartRelativeStrategy', () => {
+  it('resolves bare relative path by prepending ./', () => {
+    const ctx = makeCtx(['lib/models/user.dart', 'lib/main.dart']);
+    const result = dartRelativeStrategy("'./models/user.dart'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: ['lib/models/user.dart'] });
+  });
+
+  it('returns null for unresolvable relative import', () => {
+    const ctx = makeCtx([]);
+    const result = dartRelativeStrategy("'nonexistent.dart'", 'lib/main.dart', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full resolver — dartImportConfig composed via factory
+// ---------------------------------------------------------------------------
+
+describe('Dart import resolver (full config)', () => {
+  const resolve = createImportResolver(dartImportConfig);
+
+  it('absorbs dart: SDK imports', () => {
+    const result = resolve("'dart:async'", 'lib/main.dart', makeCtx([]));
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('resolves local package: import', () => {
+    const ctx = makeCtx(['lib/models/user.dart']);
+    const result = resolve("'package:my_app/models/user.dart'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: ['lib/models/user.dart'] });
+  });
+
+  it('absorbs external package: import', () => {
+    const ctx = makeCtx(['lib/main.dart']);
+    const result = resolve("'package:http/http.dart'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('resolves relative import via second strategy', () => {
+    const ctx = makeCtx(['lib/models/user.dart', 'lib/main.dart']);
+    const result = resolve("'./models/user.dart'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: ['lib/models/user.dart'] });
+  });
+});
diff --git a/gitnexus/test/unit/embedding-chunking.test.ts b/gitnexus/test/unit/embedding-chunking.test.ts
new file mode 100644
index 000000000..62fdd2b23
--- /dev/null
+++ b/gitnexus/test/unit/embedding-chunking.test.ts
@@ -0,0 +1,243 @@
+/**
+ * Integration test: Embedding chunking pipeline
+ *
+ * Tests the chunking + text generation pipeline together.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { characterChunk } from '../../src/core/embeddings/character-chunk.js';
+import { generateEmbeddingText } from '../../src/core/embeddings/text-generator.js';
+import type { EmbeddableNode } from '../../src/core/embeddings/types.js';
+
+const { createParserForLanguage } = vi.hoisted(() => ({
+  createParserForLanguage: vi.fn(),
+}));
+
+vi.mock('../../src/core/tree-sitter/parser-loader.js', () => ({
+  createParserForLanguage,
+  isLanguageAvailable: vi.fn().mockReturnValue(true),
+  resolveLanguageKey: vi.fn((language: string) => language),
+}));
+
+vi.mock('gitnexus-shared', () => ({
+  getLanguageFromFilename: vi.fn().mockReturnValue('typescript'),
+}));
+
+import { chunkNode } from '../../src/core/embeddings/chunker.js';
+
+type FakeNode = {
+  type: string;
+  startIndex: number;
+  endIndex: number;
+  namedChildCount: number;
+  namedChild: (index: number) => FakeNode | null;
+  childForFieldName?: (name: string) => FakeNode | null;
+};
+
+const makeFakeNode = (
+  type: string,
+  startIndex: number,
+  endIndex: number,
+  children: FakeNode[] = [],
+  fields: Record<string, FakeNode> = {},
+): FakeNode => ({
+  type,
+  startIndex,
+  endIndex,
+  namedChildCount: children.length,
+  namedChild: (index: number) => children[index] ?? null,
+  childForFieldName: (name: string) => fields[name] ?? null,
+});
+
+const makeDeclarationTree = (
+  nodeType: string,
+  bodyType: string,
+  content: string,
+  members: Array<{ text: string; type: string }>,
+) => {
+  let searchFrom = 0;
+  const memberNodes = members.map((member) => {
+    const startIndex = content.indexOf(member.text, searchFrom);
+    if (startIndex < 0) {
+      throw new Error(`Unable to locate declaration member text: ${member.text}`);
+    }
+    searchFrom = startIndex + member.text.length;
+    return makeFakeNode(member.type, startIndex, startIndex + member.text.length);
+  });
+
+  const bodyStart = content.indexOf('{');
+  const bodyEnd = content.lastIndexOf('}') + 1;
+  const bodyNode = makeFakeNode(bodyType, bodyStart, bodyEnd, memberNodes);
+  const declNode = makeFakeNode(nodeType, 0, bodyEnd, [bodyNode], { body: bodyNode });
+  return {
+    rootNode: makeFakeNode('program', 0, content.length, [declNode]),
+  };
+};
+
+describe('embedding-chunking integration', () => {
+  const makeNode = (overrides: Partial<EmbeddableNode>): EmbeddableNode => ({
+    id: 'Function:src/test.ts:test',
+    name: 'test',
+    label: 'Function',
+    filePath: 'src/test.ts',
+    content: '',
+    startLine: 1,
+    endLine: 10,
+    ...overrides,
+  });
+
+  it('short function produces single chunk with metadata', () => {
+    const node = makeNode({
+      content: 'function hello() { return "world"; }',
+      isExported: true,
+      repoName: 'my-project',
+      serverName: 'my-service',
+    });
+
+    const chunks = characterChunk(node.content, 1, 3, 1200, 120);
+    expect(chunks).toHaveLength(1);
+
+    const text = generateEmbeddingText(node, chunks[0].text);
+    expect(text).toContain('Function: test');
+    expect(text).toContain('Repo: my-project');
+    expect(text).toContain('Server: my-service');
+    expect(text).toContain('Export: true');
+    expect(text).toContain('function hello()');
+  });
+
+  it('long function produces multiple chunks', () => {
+    const longContent = Array.from({ length: 100 }, (_, i) => `  const line${i} = ${i};`).join(
+      '\n',
+    );
+    const node = makeNode({
+      content: `function longFn() {\n${longContent}\n}`,
+      startLine: 1,
+      endLine: 102,
+    });
+
+    const chunks = characterChunk(node.content, 1, 102, 1200, 120);
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks[0].chunkIndex).toBe(0);
+  });
+
+  it('short labels (TypeAlias) skip chunking and embed directly', () => {
+    const node = makeNode({
+      label: 'TypeAlias',
+      name: 'Result',
+      content: 'type Result<T> = Success<T> | Error;',
+    });
+
+    const chunks = characterChunk(node.content, 1, 1, 1200, 120);
+    expect(chunks).toHaveLength(1);
+
+    const text = generateEmbeddingText(node, chunks[0].text);
+    expect(text).toContain('TypeAlias: Result');
+    expect(text).toContain('type Result<T> = Success<T> | Error;');
+  });
+
+  it('long enum uses character fallback', () => {
+    const enumContent = Array.from(
+      { length: 200 },
+      (_, i) => `  Value${i} = "${'x'.repeat(20)}${i}",`,
+    ).join('\n');
+    const node = makeNode({
+      label: 'Enum',
+      name: 'LargeEnum',
+      content: `enum LargeEnum {\n${enumContent}\n}`,
+      startLine: 1,
+      endLine: 202,
+    });
+
+    const chunks = characterChunk(node.content, 1, 202, 1200, 120);
+    expect(chunks.length).toBeGreaterThan(1);
+  });
+
+  it('long class produces member-aware chunks with structural metadata', async () => {
+    const node = makeNode({
+      label: 'Class',
+      name: 'Parser',
+      methodNames: ['parseJSON', 'validate'],
+      fieldNames: ['options', 'cache'],
+      content: `class Parser {
+  options: ParserOptions;
+  cache: Map<string, any>;
+  parseJSON(text: string) { return JSON.parse(text); }
+  validate() { return true; }
+}`,
+      startLine: 20,
+      endLine: 25,
+    });
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(
+        makeDeclarationTree('class_declaration', 'class_body', node.content, [
+          { text: 'options: ParserOptions;', type: 'field_definition' },
+          { text: 'cache: Map<string, any>;', type: 'field_definition' },
+          {
+            text: 'parseJSON(text: string) { return JSON.parse(text); }',
+            type: 'method_definition',
+          },
+          { text: 'validate() { return true; }', type: 'method_definition' },
+        ]),
+      ),
+    });
+
+    const chunks = await chunkNode(node.label, node.content, node.filePath, 20, 25, 90, 0);
+    expect(chunks).toHaveLength(2);
+
+    const secondText = generateEmbeddingText(node, chunks[1].text);
+    expect(secondText).toContain('Class: Parser');
+    expect(secondText).toContain('Methods: parseJSON, validate');
+    expect(secondText).toContain('Properties: options, cache');
+    expect(secondText).toContain('parseJSON(text: string)');
+  });
+
+  it('interface chunks retain structural metadata and signatures', async () => {
+    const node = makeNode({
+      label: 'Interface',
+      name: 'Handler',
+      methodNames: ['handle', 'validate'],
+      fieldNames: ['name'],
+      content: `interface Handler {
+  handle(event: Event): void;
+  validate(input: string): boolean;
+  readonly name: string;
+}`,
+      startLine: 30,
+      endLine: 34,
+    });
+    createParserForLanguage.mockResolvedValue({
+      parse: vi.fn().mockReturnValue(
+        makeDeclarationTree('interface_declaration', 'object_type', node.content, [
+          { text: 'handle(event: Event): void;', type: 'method_definition' },
+          { text: 'validate(input: string): boolean;', type: 'method_definition' },
+          { text: 'readonly name: string;', type: 'property_signature' },
+        ]),
+      ),
+    });
+
+    const chunks = await chunkNode(node.label, node.content, node.filePath, 30, 34, 500, 0);
+    expect(chunks).toHaveLength(1);
+
+    const text = generateEmbeddingText(node, chunks[0].text);
+    expect(text).toContain('Interface: Handler');
+    expect(text).toContain('Methods: handle, validate');
+    expect(text).toContain('readonly name: string;');
+  });
+
+  it('metadata is present in every chunk', () => {
+    const longContent = 'x'.repeat(3000);
+    const node = makeNode({
+      content: longContent,
+      repoName: 'test-repo',
+    });
+
+    const chunks = characterChunk(node.content, 1, 100, 1200, 120);
+    expect(chunks.length).toBeGreaterThan(1);
+
+    for (const chunk of chunks) {
+      const text = generateEmbeddingText(node, chunk.text);
+      expect(text).toContain('Function: test');
+      expect(text).toContain('Repo: test-repo');
+      expect(text).toContain('Path: src/test.ts');
+    }
+  });
+});
diff --git a/gitnexus/test/unit/embedding-pipeline.test.ts b/gitnexus/test/unit/embedding-pipeline.test.ts
index 7597d48ce..5276fd3da 100644
--- a/gitnexus/test/unit/embedding-pipeline.test.ts
+++ b/gitnexus/test/unit/embedding-pipeline.test.ts
@@ -3,7 +3,7 @@ import { createHash } from 'crypto';
 import { contentHashForNode } from '../../src/core/embeddings/embedding-pipeline.js';
 import { generateEmbeddingText } from '../../src/core/embeddings/text-generator.js';
 import type { EmbeddableNode, EmbeddingProgress } from '../../src/core/embeddings/types.js';
-import { DEFAULT_EMBEDDING_CONFIG } from '../../src/core/embeddings/types.js';
+import { DEFAULT_EMBEDDING_CONFIG, EMBEDDABLE_LABELS } from '../../src/core/embeddings/types.js';
 import { STALE_HASH_SENTINEL } from '../../src/core/lbug/schema.js';
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -29,9 +29,11 @@ describe('contentHashForNode', () => {
     expect(contentHashForNode(node)).toBe(contentHashForNode(node));
   });
 
-  it('matches sha1(generateEmbeddingText(node))', () => {
+  it('matches sha1(generateEmbeddingText(node, node.content))', () => {
     const node = makeNode();
-    const expected = createHash('sha1').update(generateEmbeddingText(node)).digest('hex');
+    const expected = createHash('sha1')
+      .update(generateEmbeddingText(node, node.content))
+      .digest('hex');
     expect(contentHashForNode(node)).toBe(expected);
   });
 
@@ -161,8 +163,15 @@ describe('runEmbeddingPipeline incremental filter', () => {
     return vi.fn().mockImplementation(async (cypher: string) => {
       queryCalls.push(cypher);
       // Respond to node queries based on label
-      for (const label of ['Function', 'Class', 'Method', 'Interface', 'File']) {
-        if (cypher.includes(`MATCH (n:${label})`)) {
+      for (const label of [
+        'Function',
+        'Class',
+        'Method',
+        'Interface',
+        'File',
+        ...(EMBEDDABLE_LABELS as readonly string[]),
+      ]) {
+        if (cypher.includes(`MATCH (n:${label})`) || cypher.includes(`MATCH (n:\`${label}\``)) {
           return nodes
             .filter((n) => n.label === label)
             .map((n) => ({
@@ -210,12 +219,14 @@ describe('runEmbeddingPipeline incremental filter', () => {
       executeWithReusedStatement,
       onProgress,
       {},
+      undefined, // skipNodeIds
+      undefined, // context
       existingEmbeddings,
     );
 
-    // No MERGE calls — node was skipped because hash matched
-    const mergeCalls = stmtCalls.filter((c) => c.cypher.includes('MERGE'));
-    expect(mergeCalls).toHaveLength(0);
+    // No CREATE calls — node was skipped because hash matched
+    const createCalls = stmtCalls.filter((c) => c.cypher.includes('CREATE'));
+    expect(createCalls).toHaveLength(0);
 
     // Pipeline should reach 'ready' state
     const readyProgress = progressUpdates.find((p) => p.phase === 'ready');
@@ -244,19 +255,96 @@ describe('runEmbeddingPipeline incremental filter', () => {
       executeWithReusedStatement,
       onProgress,
       {},
+      undefined, // skipNodeIds
+      undefined, // context
       existingEmbeddings,
     );
 
-    // Should have a MERGE call to insert the embedding
-    const mergeCalls = stmtCalls.filter((c) => c.cypher.includes('MERGE'));
-    expect(mergeCalls.length).toBeGreaterThanOrEqual(1);
+    // Should have a CREATE call to insert the embedding
+    const createCalls = stmtCalls.filter((c) => c.cypher.includes('CREATE'));
+    expect(createCalls.length).toBeGreaterThanOrEqual(1);
 
     // The inserted row should contain the node id and a contentHash
-    const insertParams = mergeCalls[0].params;
+    const insertParams = createCalls[0].params;
     expect(insertParams.some((p: any) => p.nodeId === node.id)).toBe(true);
     expect(insertParams[0].contentHash).toMatch(/^[0-9a-f]{40}$/);
   });
 
+  it('maps positional query rows with description/isExported columns correctly', async () => {
+    const embedBatchSpy = vi
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => new Float32Array(384))),
+      );
+    vi.doMock('../../src/core/embeddings/embedder.js', () => ({
+      initEmbedder: vi.fn().mockResolvedValue(undefined),
+      embedBatch: embedBatchSpy,
+      embedText: vi.fn().mockResolvedValue(new Float32Array(384)),
+      embeddingToArray: vi.fn().mockImplementation((emb: Float32Array) => Array.from(emb)),
+      isEmbedderReady: vi.fn().mockReturnValue(true),
+    }));
+    vi.doMock('../../src/core/lbug/lbug-adapter.js', () => ({
+      loadVectorExtension: vi.fn().mockResolvedValue(undefined),
+    }));
+
+    const executeQuery = vi.fn().mockImplementation(async (cypher: string) => {
+      queryCalls.push(cypher);
+      if (cypher.includes('MATCH (n:`Class`)')) {
+        return [
+          [
+            'Class:src/parser.ts:Parser',
+            'Parser',
+            'Class',
+            'src/parser.ts',
+            'class Parser { value = 1; }',
+            10,
+            12,
+            true,
+            'Parses typed payloads.',
+          ],
+        ];
+      }
+      if (cypher.includes('MATCH (n:`Enum`)')) {
+        return [
+          [
+            'Enum:src/status.ts:Status',
+            'Status',
+            'Enum',
+            'src/status.ts',
+            'enum Status { Active, Pending }',
+            20,
+            22,
+            'Represents user status.',
+          ],
+        ];
+      }
+      return [];
+    });
+    const executeWithReusedStatement = mockExecuteWithReusedStatement();
+
+    const { runEmbeddingPipeline } =
+      await import('../../src/core/embeddings/embedding-pipeline.js');
+
+    await runEmbeddingPipeline(
+      executeQuery,
+      executeWithReusedStatement,
+      onProgress,
+      {},
+      undefined,
+      undefined,
+      new Map(),
+    );
+
+    const embeddedTexts = embedBatchSpy.mock.calls.flatMap((call) => call[0] as string[]);
+    const classText = embeddedTexts.find((text) => text.includes('Class: Parser'));
+    const enumText = embeddedTexts.find((text) => text.includes('Enum: Status'));
+
+    expect(classText).toContain('Export: true');
+    expect(classText).toContain('Parses typed payloads.');
+    expect(enumText).not.toContain('Export:');
+    expect(enumText).toContain('Represents user status.');
+  });
+
   it('deletes and re-embeds stale nodes (hash mismatch)', async () => {
     mockEmbedderSetup();
 
@@ -275,6 +363,8 @@ describe('runEmbeddingPipeline incremental filter', () => {
       executeWithReusedStatement,
       onProgress,
       {},
+      undefined, // skipNodeIds
+      undefined, // context
       existingEmbeddings,
     );
 
@@ -283,9 +373,9 @@ describe('runEmbeddingPipeline incremental filter', () => {
     expect(deleteCalls.length).toBeGreaterThanOrEqual(1);
     expect(deleteCalls[0].params.some((p: any) => p.nodeId === node.id)).toBe(true);
 
-    // Should also have a MERGE call to re-insert with new hash
-    const mergeCalls = stmtCalls.filter((c) => c.cypher.includes('MERGE'));
-    expect(mergeCalls.length).toBeGreaterThanOrEqual(1);
+    // Should also have a CREATE call to re-insert with new hash
+    const createCalls = stmtCalls.filter((c) => c.cypher.includes('CREATE'));
+    expect(createCalls.length).toBeGreaterThanOrEqual(1);
   });
 
   it('treats STALE_HASH_SENTINEL as stale — triggers re-embed', async () => {
@@ -306,6 +396,8 @@ describe('runEmbeddingPipeline incremental filter', () => {
       executeWithReusedStatement,
       onProgress,
       {},
+      undefined, // skipNodeIds
+      undefined, // context
       existingEmbeddings,
     );
 
@@ -313,9 +405,9 @@ describe('runEmbeddingPipeline incremental filter', () => {
     const deleteCalls = stmtCalls.filter((c) => c.cypher.includes('DELETE'));
     expect(deleteCalls.length).toBeGreaterThanOrEqual(1);
 
-    // Should also have a MERGE (re-embed)
-    const mergeCalls = stmtCalls.filter((c) => c.cypher.includes('MERGE'));
-    expect(mergeCalls.length).toBeGreaterThanOrEqual(1);
+    // Should also have a CREATE (re-embed)
+    const createCalls = stmtCalls.filter((c) => c.cypher.includes('CREATE'));
+    expect(createCalls.length).toBeGreaterThanOrEqual(1);
   });
 
   it('calls createVectorIndex even when zero nodes need embedding after filter', async () => {
@@ -337,6 +429,8 @@ describe('runEmbeddingPipeline incremental filter', () => {
       executeWithReusedStatement,
       onProgress,
       {},
+      undefined, // skipNodeIds
+      undefined, // context
       existingEmbeddings,
     );
 
@@ -364,6 +458,8 @@ describe('runEmbeddingPipeline incremental filter', () => {
         executeWithReusedStatement,
         onProgress,
         {},
+        undefined, // skipNodeIds
+        undefined, // context
         existingEmbeddings,
       ),
     ).rejects.toThrow('vector-index corruption');
diff --git a/gitnexus/test/unit/framework-detection.test.ts b/gitnexus/test/unit/framework-detection.test.ts
index b07580044..ce9d76f10 100644
--- a/gitnexus/test/unit/framework-detection.test.ts
+++ b/gitnexus/test/unit/framework-detection.test.ts
@@ -90,12 +90,11 @@ describe('detectFrameworkFromPath', () => {
 
   describe('React', () => {
     it('has React component detection rule for views/components folders', () => {
-      // Note: The current implementation lowercases the path before checking
-      // PascalCase, so PascalCase detection currently can't match.
-      // This test documents the current behavior.
       const result = detectFrameworkFromPath('views/Button.tsx');
-      // Returns null because path is lowercased before PascalCase regex check
-      expect(result).toBeNull();
+      expect(result).not.toBeNull();
+      expect(result!.framework).toBe('react');
+      expect(result!.entryPointMultiplier).toBe(1.5);
+      expect(result!.reason).toBe('react-component');
     });
   });
 
diff --git a/gitnexus/test/unit/group/http-route-extractor.test.ts b/gitnexus/test/unit/group/http-route-extractor.test.ts
index 653b4952c..8ff914fcc 100644
--- a/gitnexus/test/unit/group/http-route-extractor.test.ts
+++ b/gitnexus/test/unit/group/http-route-extractor.test.ts
@@ -290,6 +290,124 @@ export const deleteUser = (id: string) => axios.delete(\`/api/users/\${id}\`);
       ).toBeDefined();
     });
 
+    it('extracts jQuery $.get and $.post shorthand', async () => {
+      const dir = path.join(tmpDir, 'jquery-shorthand');
+      fs.mkdirSync(path.join(dir, 'public/js'), { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'public/js/users.js'),
+        `
+function loadUsers() {
+  $.get('/api/users', function (data) { console.log(data); });
+}
+
+function createUser(payload) {
+  $.post('/api/users', payload);
+}
+`,
+      );
+
+      const contracts = await extractor.extract(null, dir, makeRepo(dir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      const getRoute = consumers.find((c) => c.contractId === 'http::GET::/api/users');
+      expect(getRoute).toBeDefined();
+      expect(getRoute?.meta.framework).toBe('jquery');
+
+      const postRoute = consumers.find((c) => c.contractId === 'http::POST::/api/users');
+      expect(postRoute).toBeDefined();
+      expect(postRoute?.meta.framework).toBe('jquery');
+    });
+
+    it('extracts jQuery $.ajax with method: and type: keys and default GET', async () => {
+      const dir = path.join(tmpDir, 'jquery-ajax');
+      fs.mkdirSync(path.join(dir, 'public/js'), { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'public/js/orders.js'),
+        `
+$.ajax({ url: '/api/orders', method: 'PUT', data: {} });
+$.ajax({ url: '/api/items',  type:   'DELETE' });
+$.ajax({ url: '/api/default' });
+
+function reloadOrder(id) {
+  return $.ajax({ url: \`/api/orders/\${id}\`, method: 'GET' });
+}
+`,
+      );
+
+      const contracts = await extractor.extract(null, dir, makeRepo(dir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers.find((c) => c.contractId === 'http::PUT::/api/orders')).toBeDefined();
+      expect(consumers.find((c) => c.contractId === 'http::DELETE::/api/items')).toBeDefined();
+      expect(consumers.find((c) => c.contractId === 'http::GET::/api/default')).toBeDefined();
+      // Template-literal URL inside $.ajax is normalized to {param} the same
+      // way the fetch/axios paths do — confirms readStringProp accepts
+      // template_string values for jQuery ajax, not just for axios object form.
+      expect(
+        consumers.find((c) => c.contractId === 'http::GET::/api/orders/{param}'),
+      ).toBeDefined();
+    });
+
+    it('extracts axios({ method, url }) object form regardless of key order', async () => {
+      const dir = path.join(tmpDir, 'axios-object');
+      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'src/orders.ts'),
+        `
+import axios from 'axios';
+
+export function createOrder(data: unknown) {
+  return axios({ method: 'POST', url: '/api/orders', data });
+}
+
+export function updateUser(id: string, data: unknown) {
+  return axios({ url: \`/api/users/\${id}\`, method: 'PUT', data });
+}
+
+export function listDefaults() {
+  return axios({ url: '/api/defaults' });
+}
+`,
+      );
+
+      const contracts = await extractor.extract(null, dir, makeRepo(dir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      expect(consumers.find((c) => c.contractId === 'http::POST::/api/orders')).toBeDefined();
+      expect(consumers.find((c) => c.contractId === 'http::PUT::/api/users/{param}')).toBeDefined();
+      expect(consumers.find((c) => c.contractId === 'http::GET::/api/defaults')).toBeDefined();
+    });
+
+    it('does not emit consumers for unrelated object-literal calls (negative control)', async () => {
+      const dir = path.join(tmpDir, 'jquery-axios-negative');
+      fs.mkdirSync(path.join(dir, 'public/js'), { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'public/js/misc.js'),
+        `
+// jQuery but not an ajax/get/post call
+$.fn.extend({ url: '/nope', method: 'POST' });
+$.each([1, 2, 3], function (i, v) { return v; });
+
+// Not axios and not $ — unrelated helper that happens to take { url, method }
+function myHelper(opts) { return opts; }
+myHelper({ url: '/nope', method: 'POST' });
+
+// Bare object literal, not a call argument at all
+const cfg = { url: '/nope', method: 'POST' };
+console.log(cfg);
+`,
+      );
+
+      const contracts = await extractor.extract(null, dir, makeRepo(dir));
+      const consumers = contracts.filter((c) => c.role === 'consumer');
+
+      // None of the above should have produced any HTTP consumer contracts.
+      const nopeConsumers = consumers.filter(
+        (c) => typeof c.meta.path === 'string' && c.meta.path.includes('/nope'),
+      );
+      expect(nopeConsumers).toHaveLength(0);
+    });
+
     it('extracts Python requests calls', async () => {
       const dir = path.join(tmpDir, 'python-consumer');
       fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
diff --git a/gitnexus/test/unit/heritage-extraction.test.ts b/gitnexus/test/unit/heritage-extraction.test.ts
new file mode 100644
index 000000000..93010fa78
--- /dev/null
+++ b/gitnexus/test/unit/heritage-extraction.test.ts
@@ -0,0 +1,428 @@
+import { describe, it, expect } from 'vitest';
+import { createHeritageExtractor } from '../../src/core/ingestion/heritage-extractors/generic.js';
+import { rubyHeritageConfig } from '../../src/core/ingestion/heritage-extractors/configs/ruby.js';
+import { goHeritageConfig } from '../../src/core/ingestion/heritage-extractors/configs/go.js';
+import type {
+  HeritageExtractionConfig,
+  HeritageExtractorContext,
+} from '../../src/core/ingestion/heritage-types.js';
+import type { CaptureMap } from '../../src/core/ingestion/language-provider.js';
+import { SupportedLanguages } from 'gitnexus-shared';
+import { getProvider } from '../../src/core/ingestion/languages/index.js';
+
+// ---------------------------------------------------------------------------
+// Mock AST node helpers
+// ---------------------------------------------------------------------------
+
+interface MockNode {
+  type: string;
+  text: string;
+  parent?: MockNode | null;
+  children?: MockNode[];
+  childForFieldName?: (name: string) => MockNode | undefined;
+}
+
+/** Create a minimal mock SyntaxNode for capture map entries. */
+function makeNode(text: string, type = 'identifier', parent?: MockNode): MockNode {
+  return { type, text, parent: parent ?? null };
+}
+
+/** Create a mock field_declaration node (Go struct fields). */
+function makeGoFieldDecl(opts: { hasName: boolean; typeName: string }): MockNode {
+  const nameNode = opts.hasName ? makeNode('MyField', 'field_identifier') : undefined;
+  const fieldDecl: MockNode = {
+    type: 'field_declaration',
+    text: '',
+    childForFieldName: (name: string) => (name === 'name' ? nameNode : undefined),
+  };
+  const typeNode = makeNode(opts.typeName, 'type_identifier', fieldDecl);
+  return typeNode;
+}
+
+/** Build a CaptureMap from partial entries. */
+function buildCaptureMap(entries: Record<string, MockNode | undefined>): CaptureMap {
+  return entries as unknown as CaptureMap;
+}
+
+/** Default context for testing. */
+function ctx(filePath = 'Test.java', language = SupportedLanguages.Java): HeritageExtractorContext {
+  return { filePath, language };
+}
+
+// ---------------------------------------------------------------------------
+// Factory construction
+// ---------------------------------------------------------------------------
+
+describe('createHeritageExtractor', () => {
+  it('creates an extractor from a minimal config', () => {
+    const extractor = createHeritageExtractor(SupportedLanguages.Java);
+    expect(extractor).toBeDefined();
+    expect(extractor.language).toBe(SupportedLanguages.Java);
+    expect(typeof extractor.extract).toBe('function');
+  });
+
+  it('creates an extractor from a language enum (default config)', () => {
+    const languages: SupportedLanguages[] = [
+      SupportedLanguages.Java,
+      SupportedLanguages.Kotlin,
+      SupportedLanguages.CSharp,
+      SupportedLanguages.TypeScript,
+      SupportedLanguages.JavaScript,
+      SupportedLanguages.CPlusPlus,
+      SupportedLanguages.C,
+      SupportedLanguages.Python,
+      SupportedLanguages.Rust,
+      SupportedLanguages.Dart,
+      SupportedLanguages.PHP,
+      SupportedLanguages.Swift,
+    ];
+    for (const lang of languages) {
+      const extractor = createHeritageExtractor(lang);
+      expect(extractor.language, `${lang} extractor should have correct language`).toBe(lang);
+      expect(typeof extractor.extract).toBe('function');
+      expect(extractor.extractFromCall).toBeUndefined();
+    }
+  });
+
+  it('creates an extractor from full config with custom hooks', () => {
+    const configs: HeritageExtractionConfig[] = [goHeritageConfig, rubyHeritageConfig];
+    for (const cfg of configs) {
+      expect(
+        () => createHeritageExtractor(cfg),
+        `config for ${cfg.language} must construct cleanly`,
+      ).not.toThrow();
+    }
+  });
+
+  it('sets extractFromCall when callBasedHeritage is configured', () => {
+    const extractor = createHeritageExtractor(rubyHeritageConfig);
+    expect(extractor.extractFromCall).toBeDefined();
+    expect(typeof extractor.extractFromCall).toBe('function');
+  });
+
+  it('does not set extractFromCall for default language extractors', () => {
+    const extractor = createHeritageExtractor(SupportedLanguages.Java);
+    expect(extractor.extractFromCall).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Generic extraction from captures
+// ---------------------------------------------------------------------------
+
+describe('HeritageExtractor.extract', () => {
+  const extractor = createHeritageExtractor(SupportedLanguages.Java);
+
+  it('returns empty array when heritage.class is not present', () => {
+    const captures = buildCaptureMap({});
+    expect(extractor.extract(captures, ctx())).toEqual([]);
+  });
+
+  it('returns empty array when heritage.class is present but no extends/implements/trait', () => {
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('MyClass'),
+    });
+    expect(extractor.extract(captures, ctx())).toEqual([]);
+  });
+
+  it('extracts extends heritage', () => {
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('Child'),
+      'heritage.extends': makeNode('Parent'),
+    });
+    const result = extractor.extract(captures, ctx());
+    expect(result).toEqual([{ className: 'Child', parentName: 'Parent', kind: 'extends' }]);
+  });
+
+  it('extracts implements heritage', () => {
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('MyClass'),
+      'heritage.implements': makeNode('MyInterface'),
+    });
+    const result = extractor.extract(captures, ctx());
+    expect(result).toEqual([
+      { className: 'MyClass', parentName: 'MyInterface', kind: 'implements' },
+    ]);
+  });
+
+  it('extracts trait-impl heritage', () => {
+    const rustExtractor = createHeritageExtractor(SupportedLanguages.Rust);
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('MyStruct'),
+      'heritage.trait': makeNode('Display'),
+    });
+    const result = rustExtractor.extract(captures, ctx('main.rs', SupportedLanguages.Rust));
+    expect(result).toEqual([{ className: 'MyStruct', parentName: 'Display', kind: 'trait-impl' }]);
+  });
+
+  it('extracts both extends and implements from same match', () => {
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('MyClass'),
+      'heritage.extends': makeNode('BaseClass'),
+      'heritage.implements': makeNode('ISerializable'),
+    });
+    const result = extractor.extract(captures, ctx());
+    expect(result).toEqual([
+      { className: 'MyClass', parentName: 'BaseClass', kind: 'extends' },
+      { className: 'MyClass', parentName: 'ISerializable', kind: 'implements' },
+    ]);
+  });
+
+  it('extracts all three heritage kinds from same match', () => {
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('MyStruct'),
+      'heritage.extends': makeNode('Base'),
+      'heritage.implements': makeNode('IFace'),
+      'heritage.trait': makeNode('Trait'),
+    });
+    const result = extractor.extract(captures, ctx());
+    expect(result).toEqual([
+      { className: 'MyStruct', parentName: 'Base', kind: 'extends' },
+      { className: 'MyStruct', parentName: 'IFace', kind: 'implements' },
+      { className: 'MyStruct', parentName: 'Trait', kind: 'trait-impl' },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Go: shouldSkipExtends (named field detection)
+// ---------------------------------------------------------------------------
+
+describe('Go HeritageExtractor — shouldSkipExtends', () => {
+  const extractor = createHeritageExtractor(goHeritageConfig);
+
+  it('extracts anonymous struct embedding (no field name)', () => {
+    const typeNode = makeGoFieldDecl({ hasName: false, typeName: 'Animal' });
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('Dog'),
+      'heritage.extends': typeNode as unknown as CaptureMap[string],
+    });
+    const result = extractor.extract(captures, ctx('main.go', SupportedLanguages.Go));
+    expect(result).toEqual([{ className: 'Dog', parentName: 'Animal', kind: 'extends' }]);
+  });
+
+  it('skips named struct fields (Breed string)', () => {
+    const typeNode = makeGoFieldDecl({ hasName: true, typeName: 'string' });
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('Dog'),
+      'heritage.extends': typeNode as unknown as CaptureMap[string],
+    });
+    const result = extractor.extract(captures, ctx('main.go', SupportedLanguages.Go));
+    expect(result).toEqual([]);
+  });
+
+  it('extracts heritage when extends node has no parent', () => {
+    const orphanNode = makeNode('Embedded', 'type_identifier');
+    orphanNode.parent = null;
+    const captures = buildCaptureMap({
+      'heritage.class': makeNode('Foo'),
+      'heritage.extends': orphanNode as unknown as CaptureMap[string],
+    });
+    const result = extractor.extract(captures, ctx('main.go', SupportedLanguages.Go));
+    expect(result).toEqual([{ className: 'Foo', parentName: 'Embedded', kind: 'extends' }]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Ruby: call-based heritage (include/extend/prepend)
+// ---------------------------------------------------------------------------
+
+describe('Ruby HeritageExtractor — call-based heritage', () => {
+  const extractor = createHeritageExtractor(rubyHeritageConfig);
+
+  /** Build a mock call node for include/extend/prepend. */
+  function makeCallNode(
+    argNodes: MockNode[],
+    enclosingType: 'class' | 'module' | null,
+    enclosingName: string | null,
+  ): MockNode {
+    const argList: MockNode = {
+      type: 'argument_list',
+      text: '',
+      children: argNodes,
+    };
+    const classNameNode = enclosingName ? makeNode(enclosingName, 'constant') : undefined;
+    const enclosingNode: MockNode | null =
+      enclosingType && enclosingName
+        ? {
+            type: enclosingType,
+            text: '',
+            parent: null,
+            childForFieldName: (name: string) => (name === 'name' ? classNameNode : undefined),
+          }
+        : null;
+
+    const bodyNode: MockNode = {
+      type: 'body_statement',
+      text: '',
+      parent: enclosingNode,
+    };
+    if (enclosingNode) enclosingNode.children = [bodyNode];
+
+    const callNode: MockNode = {
+      type: 'call',
+      text: '',
+      parent: bodyNode,
+      childForFieldName: (name: string) => (name === 'arguments' ? argList : undefined),
+    };
+    return callNode;
+  }
+
+  function makeConstantArg(name: string): MockNode {
+    return makeNode(name, 'constant');
+  }
+
+  function makeScopeResolutionArg(name: string): MockNode {
+    return makeNode(name, 'scope_resolution');
+  }
+
+  const rubyCtx = ctx('app.rb', SupportedLanguages.Ruby);
+
+  it('returns null for non-heritage call names', () => {
+    const callNode = makeCallNode([makeConstantArg('Foo')], 'class', 'Bar');
+    expect(extractor.extractFromCall!('puts', callNode as any, rubyCtx)).toBeNull();
+  });
+
+  it('extracts include heritage with single constant arg', () => {
+    const callNode = makeCallNode([makeConstantArg('Serializable')], 'class', 'User');
+    const result = extractor.extractFromCall!('include', callNode as any, rubyCtx);
+    expect(result).toEqual([{ className: 'User', parentName: 'Serializable', kind: 'include' }]);
+  });
+
+  it('extracts extend heritage with scope_resolution arg', () => {
+    const callNode = makeCallNode(
+      [makeScopeResolutionArg('ActiveSupport::Concern')],
+      'class',
+      'Post',
+    );
+    const result = extractor.extractFromCall!('extend', callNode as any, rubyCtx);
+    expect(result).toEqual([
+      { className: 'Post', parentName: 'ActiveSupport::Concern', kind: 'extend' },
+    ]);
+  });
+
+  it('extracts prepend heritage', () => {
+    const callNode = makeCallNode([makeConstantArg('Instrumented')], 'class', 'Service');
+    const result = extractor.extractFromCall!('prepend', callNode as any, rubyCtx);
+    expect(result).toEqual([{ className: 'Service', parentName: 'Instrumented', kind: 'prepend' }]);
+  });
+
+  it('extracts include inside a module', () => {
+    const callNode = makeCallNode([makeConstantArg('Helpers')], 'module', 'AppHelper');
+    const result = extractor.extractFromCall!('include', callNode as any, rubyCtx);
+    expect(result).toEqual([{ className: 'AppHelper', parentName: 'Helpers', kind: 'include' }]);
+  });
+
+  it('extracts multiple constant args as separate heritage items', () => {
+    const args = [makeConstantArg('Mod1'), makeConstantArg('Mod2'), makeConstantArg('Mod3')];
+    const callNode = makeCallNode(args, 'class', 'MyClass');
+    const result = extractor.extractFromCall!('include', callNode as any, rubyCtx);
+    expect(result).toEqual([
+      { className: 'MyClass', parentName: 'Mod1', kind: 'include' },
+      { className: 'MyClass', parentName: 'Mod2', kind: 'include' },
+      { className: 'MyClass', parentName: 'Mod3', kind: 'include' },
+    ]);
+  });
+
+  it('returns empty array when no enclosing class/module', () => {
+    const argList: MockNode = {
+      type: 'argument_list',
+      text: '',
+      children: [makeConstantArg('Foo')],
+    };
+    const callNode: MockNode = {
+      type: 'call',
+      text: '',
+      parent: null,
+      childForFieldName: (name: string) => (name === 'arguments' ? argList : undefined),
+    };
+    const result = extractor.extractFromCall!('include', callNode as any, rubyCtx);
+    expect(result).toEqual([]);
+  });
+
+  it('skips non-constant/non-scope_resolution args', () => {
+    const args = [
+      makeConstantArg('Mod1'),
+      makeNode('some_var', 'identifier'), // not constant or scope_resolution
+      makeConstantArg('Mod2'),
+    ];
+    const callNode = makeCallNode(args, 'class', 'MyClass');
+    const result = extractor.extractFromCall!('include', callNode as any, rubyCtx);
+    expect(result).toEqual([
+      { className: 'MyClass', parentName: 'Mod1', kind: 'include' },
+      { className: 'MyClass', parentName: 'Mod2', kind: 'include' },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Language-specific config validation
+// ---------------------------------------------------------------------------
+
+describe('HeritageExtraction language configs', () => {
+  it('Go config has shouldSkipExtends hook', () => {
+    expect(goHeritageConfig.language).toBe(SupportedLanguages.Go);
+    expect(goHeritageConfig.shouldSkipExtends).toBeDefined();
+    expect(typeof goHeritageConfig.shouldSkipExtends).toBe('function');
+  });
+
+  it('Ruby config has callBasedHeritage', () => {
+    expect(rubyHeritageConfig.language).toBe(SupportedLanguages.Ruby);
+    expect(rubyHeritageConfig.callBasedHeritage).toBeDefined();
+    expect(rubyHeritageConfig.callBasedHeritage!.callNames).toEqual(
+      new Set(['include', 'extend', 'prepend']),
+    );
+  });
+
+  it('default language extractors have no custom hooks', () => {
+    const defaultLanguages: SupportedLanguages[] = [
+      SupportedLanguages.Java,
+      SupportedLanguages.Kotlin,
+      SupportedLanguages.CSharp,
+      SupportedLanguages.TypeScript,
+      SupportedLanguages.JavaScript,
+      SupportedLanguages.CPlusPlus,
+      SupportedLanguages.C,
+      SupportedLanguages.Python,
+      SupportedLanguages.Rust,
+      SupportedLanguages.Dart,
+      SupportedLanguages.PHP,
+      SupportedLanguages.Swift,
+    ];
+    for (const lang of defaultLanguages) {
+      const extractor = createHeritageExtractor(lang);
+      expect(extractor.language).toBe(lang);
+      expect(extractor.extractFromCall, `${lang} should not have extractFromCall`).toBeUndefined();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Provider wiring — every tree-sitter provider MUST have heritageExtractor
+// ---------------------------------------------------------------------------
+
+describe('heritageExtractor on LanguageProvider', () => {
+  it('all tree-sitter providers have heritageExtractor defined', () => {
+    const languages: SupportedLanguages[] = [
+      SupportedLanguages.TypeScript,
+      SupportedLanguages.JavaScript,
+      SupportedLanguages.Python,
+      SupportedLanguages.Java,
+      SupportedLanguages.Kotlin,
+      SupportedLanguages.Go,
+      SupportedLanguages.Rust,
+      SupportedLanguages.CSharp,
+      SupportedLanguages.C,
+      SupportedLanguages.CPlusPlus,
+      SupportedLanguages.PHP,
+      SupportedLanguages.Ruby,
+      SupportedLanguages.Swift,
+      SupportedLanguages.Dart,
+      SupportedLanguages.Vue,
+    ];
+    for (const lang of languages) {
+      const provider = getProvider(lang);
+      expect(provider.heritageExtractor, `${lang} should have a heritageExtractor`).toBeDefined();
+    }
+  });
+});
diff --git a/gitnexus/test/unit/import-resolver-factory.test.ts b/gitnexus/test/unit/import-resolver-factory.test.ts
new file mode 100644
index 000000000..1150f371e
--- /dev/null
+++ b/gitnexus/test/unit/import-resolver-factory.test.ts
@@ -0,0 +1,571 @@
+/**
+ * Unit tests for the import resolver factory and per-strategy composition.
+ *
+ * Validates that:
+ * - createImportResolver chains strategies in order
+ * - First non-null result wins
+ * - Empty files array stops the chain (absorbing sentinel)
+ * - All per-language configs produce valid resolvers
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createImportResolver } from '../../src/core/ingestion/import-resolvers/resolver-factory.js';
+import { createStandardStrategy } from '../../src/core/ingestion/import-resolvers/standard.js';
+import type {
+  ImportResolutionConfig,
+  ImportResolverStrategy,
+  ResolveCtx,
+} from '../../src/core/ingestion/import-resolvers/types.js';
+import { SupportedLanguages } from 'gitnexus-shared';
+import { buildSuffixIndex } from '../../src/core/ingestion/import-resolvers/utils.js';
+
+// ── Per-language strategy imports (from config files) ──────────────────
+import { goPackageStrategy } from '../../src/core/ingestion/import-resolvers/configs/go.js';
+import {
+  javaJvmStrategy,
+  kotlinJvmStrategy,
+} from '../../src/core/ingestion/import-resolvers/configs/jvm.js';
+import { pythonImportStrategy } from '../../src/core/ingestion/import-resolvers/configs/python.js';
+import { csharpNamespaceStrategy } from '../../src/core/ingestion/import-resolvers/configs/csharp.js';
+import { dartPackageStrategy } from '../../src/core/ingestion/import-resolvers/configs/dart.js';
+import { rustModuleStrategy } from '../../src/core/ingestion/import-resolvers/configs/rust.js';
+import { phpPsr4Strategy } from '../../src/core/ingestion/import-resolvers/configs/php.js';
+import { swiftPackageStrategy } from '../../src/core/ingestion/import-resolvers/configs/swift.js';
+import { rubyRequireStrategy } from '../../src/core/ingestion/import-resolvers/configs/ruby.js';
+
+// ── Per-language config imports ────────────────────────────────────────
+import {
+  typescriptImportConfig,
+  javascriptImportConfig,
+  vueImportConfig,
+} from '../../src/core/ingestion/import-resolvers/configs/typescript-javascript.js';
+import {
+  cImportConfig,
+  cppImportConfig,
+} from '../../src/core/ingestion/import-resolvers/configs/c-cpp.js';
+import { goImportConfig } from '../../src/core/ingestion/import-resolvers/configs/go.js';
+import {
+  javaImportConfig,
+  kotlinImportConfig,
+} from '../../src/core/ingestion/import-resolvers/configs/jvm.js';
+import { pythonImportConfig } from '../../src/core/ingestion/import-resolvers/configs/python.js';
+import { rustImportConfig } from '../../src/core/ingestion/import-resolvers/configs/rust.js';
+import { csharpImportConfig } from '../../src/core/ingestion/import-resolvers/configs/csharp.js';
+import { phpImportConfig } from '../../src/core/ingestion/import-resolvers/configs/php.js';
+import { swiftImportConfig } from '../../src/core/ingestion/import-resolvers/configs/swift.js';
+import { dartImportConfig } from '../../src/core/ingestion/import-resolvers/configs/dart.js';
+import { rubyImportConfig } from '../../src/core/ingestion/import-resolvers/configs/ruby.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCtx(files: string[], overrides: Partial<ResolveCtx['configs']> = {}): ResolveCtx {
+  const allFileList = files;
+  const normalizedFileList = files.map((p) => p.replace(/\\/g, '/'));
+  const allFilePaths = new Set(allFileList);
+  const index = buildSuffixIndex(normalizedFileList, allFileList);
+  return {
+    allFilePaths,
+    allFileList,
+    normalizedFileList,
+    index,
+    resolveCache: new Map(),
+    configs: {
+      tsconfigPaths: null,
+      goModule: null,
+      composerConfig: null,
+      swiftPackageConfig: null,
+      csharpConfigs: [],
+      ...overrides,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// createImportResolver — factory behavior
+// ---------------------------------------------------------------------------
+
+describe('createImportResolver', () => {
+  it('returns null when no strategies match', () => {
+    const config: ImportResolutionConfig = {
+      language: SupportedLanguages.TypeScript,
+      strategies: [],
+    };
+    const resolver = createImportResolver(config);
+    expect(resolver('./foo', 'src/index.ts', makeCtx([]))).toBeNull();
+  });
+
+  it('returns first non-null result from strategy chain', () => {
+    const strategyA: ImportResolverStrategy = () => null;
+    const strategyB: ImportResolverStrategy = () => ({ kind: 'files', files: ['b.ts'] });
+    const strategyC: ImportResolverStrategy = () => ({ kind: 'files', files: ['c.ts'] });
+
+    const resolver = createImportResolver({
+      language: SupportedLanguages.TypeScript,
+      strategies: [strategyA, strategyB, strategyC],
+    });
+
+    const result = resolver('./foo', 'src/index.ts', makeCtx(['b.ts', 'c.ts']));
+    expect(result).toEqual({ kind: 'files', files: ['b.ts'] });
+  });
+
+  it('stops chain when strategy returns result with empty files (absorbing sentinel)', () => {
+    const absorber: ImportResolverStrategy = () => ({ kind: 'files', files: [] });
+    const shouldNotRun: ImportResolverStrategy = () => ({
+      kind: 'files',
+      files: ['should-not.ts'],
+    });
+
+    const resolver = createImportResolver({
+      language: SupportedLanguages.TypeScript,
+      strategies: [absorber, shouldNotRun],
+    });
+
+    const result = resolver('./foo', 'src/index.ts', makeCtx([]));
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('passes correct arguments to strategies', () => {
+    const ctx = makeCtx(['src/utils.ts']);
+    const captured: { raw: string; fp: string }[] = [];
+
+    const spy: ImportResolverStrategy = (raw, fp) => {
+      captured.push({ raw, fp });
+      return null;
+    };
+
+    const resolver = createImportResolver({
+      language: SupportedLanguages.TypeScript,
+      strategies: [spy],
+    });
+
+    resolver('./utils', 'src/index.ts', ctx);
+    expect(captured).toEqual([{ raw: './utils', fp: 'src/index.ts' }]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-language strategies — behavioral coverage
+//
+// The previous `typeof strategy === 'function'` assertions were tautological:
+// TypeScript's `ImportResolverStrategy` type enforces the function shape at
+// compile time, so those tests could never fail. Each strategy now has at
+// least one behavioral assertion below; the Go and C# full-chain tests also
+// double as strategy-order guards because their `kind: 'package'` output is
+// unreachable through `createStandardStrategy`.
+// ---------------------------------------------------------------------------
+
+describe('goPackageStrategy', () => {
+  it('resolves go.mod package imports to a package result with dirSuffix', () => {
+    const files = ['cmd/server/main.go', 'cmd/server/handler.go'];
+    const ctx = makeCtx(files, { goModule: { modulePath: 'example.com/app' } });
+
+    const result = goPackageStrategy('example.com/app/cmd/server', 'main.go', ctx);
+    // `kind: 'package'` + `dirSuffix` is unique to goPackageStrategy — the
+    // standard strategy always returns `kind: 'files'`. Asserting the exact
+    // shape makes format regressions observable (e.g. prefix/suffix slash
+    // normalization) and makes strategy ordering observable via the
+    // full-chain test in `goImportConfig` below.
+    expect(result).toEqual({
+      kind: 'package',
+      files: expect.arrayContaining(files),
+      dirSuffix: '/cmd/server/',
+    });
+  });
+
+  it('returns null for imports outside the go module (allows chain to continue)', () => {
+    const ctx = makeCtx(['vendor/other/pkg/foo.go'], {
+      goModule: { modulePath: 'example.com/app' },
+    });
+    const result = goPackageStrategy('github.com/other/pkg', 'main.go', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('returns null when goModule is not configured', () => {
+    const ctx = makeCtx(['cmd/server/main.go']);
+    expect(ctx.configs.goModule).toBeNull();
+    const result = goPackageStrategy('example.com/app/cmd/server', 'main.go', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('returns null when module prefix matches but package directory has no .go files', () => {
+    // Documented fall-through in configs/go.ts:27 — when resolveGoPackageDir
+    // returns non-null but resolveGoPackage returns an empty files list
+    // (external module coincidentally sharing the prefix, or a subpackage with
+    // no .go sources), the strategy returns null so the chain can continue.
+    const ctx = makeCtx(['README.md', 'cmd/server/config.yaml'], {
+      goModule: { modulePath: 'example.com/app' },
+    });
+    const result = goPackageStrategy('example.com/app/cmd/server', 'main.go', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('goImportConfig full chain produces the package-kind result (strategy-order guard)', () => {
+    const files = ['cmd/server/main.go', 'cmd/server/handler.go'];
+    const ctx = makeCtx(files, { goModule: { modulePath: 'example.com/app' } });
+
+    const resolver = createImportResolver(goImportConfig);
+    const result = resolver('example.com/app/cmd/server', 'main.go', ctx);
+    // If goPackageStrategy were moved after createStandardStrategy, the
+    // standard strategy's suffix resolution would return a single file with
+    // `kind: 'files'` (or null), not `kind: 'package'` with a dirSuffix.
+    // Asserting the full shape (not just kind) guards against a future
+    // regression that emits `kind: 'package'` with mismatched files.
+    expect(result).toEqual({
+      kind: 'package',
+      files: expect.arrayContaining(files),
+      dirSuffix: '/cmd/server/',
+    });
+  });
+});
+
+describe('javaJvmStrategy', () => {
+  it('resolves wildcard imports to .java files in the package directory', () => {
+    const files = [
+      'src/main/java/com/example/foo/Bar.java',
+      'src/main/java/com/example/foo/Baz.java',
+      'src/main/java/com/example/other/Unrelated.java',
+    ];
+    const ctx = makeCtx(files);
+    const result = javaJvmStrategy('com.example.foo.*', 'App.java', ctx);
+    expect(result?.kind).toBe('files');
+    expect(result?.files).toEqual(
+      expect.arrayContaining([
+        'src/main/java/com/example/foo/Bar.java',
+        'src/main/java/com/example/foo/Baz.java',
+      ]),
+    );
+    expect(result?.files).not.toContain('src/main/java/com/example/other/Unrelated.java');
+  });
+
+  it('resolves member imports to the owning class file', () => {
+    const files = ['src/main/java/com/example/Constants.java'];
+    const ctx = makeCtx(files);
+    // JVM member import: last segment is an ALL_CAPS constant / lowercase
+    // member; resolver walks back to the class path `com/example/Constants`.
+    const result = javaJvmStrategy('com.example.Constants.VALUE', 'App.java', ctx);
+    expect(result).toEqual({ kind: 'files', files });
+  });
+
+  it('returns null when no matching .java files exist', () => {
+    const ctx = makeCtx(['src/main/java/other/Foo.java']);
+    const result = javaJvmStrategy('com.example.missing.*', 'App.java', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+describe('kotlinJvmStrategy', () => {
+  it('resolves wildcard imports to files in the package directory', () => {
+    const files = [
+      'src/main/kotlin/com/example/foo/Bar.kt',
+      'src/main/kotlin/com/example/foo/Baz.kt',
+      'src/main/kotlin/com/example/other/Unrelated.kt',
+    ];
+    const ctx = makeCtx(files);
+
+    const result = kotlinJvmStrategy('com.example.foo.*', 'App.kt', ctx);
+    expect(result?.kind).toBe('files');
+    expect(result?.files).toEqual(
+      expect.arrayContaining([
+        'src/main/kotlin/com/example/foo/Bar.kt',
+        'src/main/kotlin/com/example/foo/Baz.kt',
+      ]),
+    );
+    expect(result?.files).not.toContain('src/main/kotlin/com/example/other/Unrelated.kt');
+  });
+
+  it('resolves member imports to the owning class file', () => {
+    const files = ['src/main/kotlin/com/example/Constants.kt'];
+    const ctx = makeCtx(files);
+    const result = kotlinJvmStrategy('com.example.Constants.VALUE', 'App.kt', ctx);
+    expect(result).toEqual({ kind: 'files', files });
+  });
+
+  it('returns null for wildcard with no matching files (allows chain to continue)', () => {
+    const ctx = makeCtx(['src/main/kotlin/com/example/other/Foo.kt']);
+    const result = kotlinJvmStrategy('com.example.missing.*', 'App.kt', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('kotlinImportConfig full chain resolves wildcard via the JVM strategy', () => {
+    // Note: this is a behavioral smoke test, NOT a strategy-order guard.
+    // `createStandardStrategy(Kotlin)` explicitly returns null for any import
+    // ending in `.*` (see standard.ts:137), so reordering `kotlinImportConfig`
+    // strategies would still produce the same result — the standard strategy
+    // would return null and the chain would fall through to kotlinJvmStrategy
+    // regardless of position. A genuine ordering guard for Kotlin would need
+    // a non-wildcard fixture where both strategies resolve to different files.
+    const files = ['src/main/kotlin/com/example/foo/Bar.kt'];
+    const ctx = makeCtx(files);
+    const resolver = createImportResolver(kotlinImportConfig);
+    const result = resolver('com.example.foo.*', 'App.kt', ctx);
+    expect(result).toEqual({ kind: 'files', files });
+  });
+});
+
+describe('rustModuleStrategy', () => {
+  it('resolves scoped grouped imports to per-item files', () => {
+    const files = ['src/models/User.rs', 'src/models/Repo.rs'];
+    const ctx = makeCtx(files);
+    // `use crate::models::{User, Repo}` — the strategy resolves each item
+    // individually against the allFilePaths set via resolveRustImportInternal.
+    const result = rustModuleStrategy('crate::models::{User, Repo}', 'src/lib.rs', ctx);
+    // Exact file discovery depends on resolveRustImportInternal's search
+    // heuristics; we assert the shape + that at least one item resolved.
+    expect(result?.kind).toBe('files');
+    expect(result?.files.length).toBeGreaterThan(0);
+  });
+
+  it('returns null for non-grouped imports (delegates to standard fallback)', () => {
+    const ctx = makeCtx(['src/models.rs']);
+    // Plain `use crate::models` — rustModuleStrategy only handles grouped
+    // forms; standard strategy handles the crate:: -> path translation.
+    const result = rustModuleStrategy('crate::models', 'src/lib.rs', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+describe('csharpNamespaceStrategy', () => {
+  it('resolves namespace imports via .csproj root-namespace mapping', () => {
+    const files = ['src/Services/Auth/AuthService.cs', 'src/Services/Auth/TokenService.cs'];
+    const ctx = makeCtx(files, {
+      csharpConfigs: [{ rootNamespace: 'MyCo', projectDir: 'src' }],
+    });
+
+    const result = csharpNamespaceStrategy('MyCo.Services.Auth', 'App.cs', ctx);
+    // Multi-file namespace resolution produces `kind: 'package'` with
+    // dirSuffix — unique to csharpNamespaceStrategy; the standard strategy
+    // always emits `kind: 'files'`. Asserting the full shape (including the
+    // exact dirSuffix format) guards against format regressions.
+    expect(result).toEqual({
+      kind: 'package',
+      files: expect.arrayContaining(files),
+      dirSuffix: '/src/Services/Auth/',
+    });
+  });
+
+  it('returns null when no csharpConfigs are configured', () => {
+    const ctx = makeCtx(['src/Services/Auth/AuthService.cs']);
+    expect(ctx.configs.csharpConfigs).toEqual([]);
+    const result = csharpNamespaceStrategy('MyCo.Services.Auth', 'App.cs', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('csharpImportConfig full chain produces package-kind (strategy-order guard)', () => {
+    const files = ['src/Services/Auth/AuthService.cs', 'src/Services/Auth/TokenService.cs'];
+    const ctx = makeCtx(files, {
+      csharpConfigs: [{ rootNamespace: 'MyCo', projectDir: 'src' }],
+    });
+
+    const resolver = createImportResolver(csharpImportConfig);
+    const result = resolver('MyCo.Services.Auth', 'App.cs', ctx);
+    // If csharpNamespaceStrategy were reordered after createStandardStrategy,
+    // the result would be `kind: 'files'` (suffix match) or null, never
+    // `kind: 'package'` with a dirSuffix. Asserting the full shape (not just
+    // kind) guards against a regression that emits `kind: 'package'` with
+    // mismatched files.
+    expect(result).toEqual({
+      kind: 'package',
+      files: expect.arrayContaining(files),
+      dirSuffix: '/src/Services/Auth/',
+    });
+  });
+});
+
+describe('phpPsr4Strategy', () => {
+  it('resolves PSR-4 namespace imports via composer.json autoload map', () => {
+    const files = ['app/Services/UserService.php'];
+    const ctx = makeCtx(files, {
+      composerConfig: {
+        psr4: new Map([['App\\', 'app/']]),
+      },
+    });
+    const result = phpPsr4Strategy('App\\Services\\UserService', 'index.php', ctx);
+    expect(result).toEqual({ kind: 'files', files });
+  });
+
+  it('returns null when no file matches the namespace via PSR-4 or suffix fallback', () => {
+    const ctx = makeCtx(['app/Services/OtherService.php'], {
+      composerConfig: { psr4: new Map([['App\\', 'app/']]) },
+    });
+    const result = phpPsr4Strategy('App\\Services\\UserService', 'index.php', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+describe('swiftPackageStrategy', () => {
+  it('resolves SwiftPM target imports to files in the target directory', () => {
+    const files = [
+      'Package/Sources/SiuperModel/Foo.swift',
+      'Package/Sources/SiuperModel/Bar.swift',
+      'Package/Sources/Other/Unrelated.swift',
+    ];
+    const ctx = makeCtx(files, {
+      swiftPackageConfig: {
+        targets: new Map([['SiuperModel', 'Package/Sources/SiuperModel']]),
+      },
+    });
+    const result = swiftPackageStrategy('SiuperModel', 'App.swift', ctx);
+    expect(result?.kind).toBe('files');
+    expect(result?.files).toEqual(
+      expect.arrayContaining([
+        'Package/Sources/SiuperModel/Foo.swift',
+        'Package/Sources/SiuperModel/Bar.swift',
+      ]),
+    );
+    expect(result?.files).not.toContain('Package/Sources/Other/Unrelated.swift');
+  });
+
+  it('returns null for unknown targets (external frameworks like Foundation)', () => {
+    const ctx = makeCtx(['Package/Sources/SiuperModel/Foo.swift'], {
+      swiftPackageConfig: {
+        targets: new Map([['SiuperModel', 'Package/Sources/SiuperModel']]),
+      },
+    });
+    const result = swiftPackageStrategy('Foundation', 'App.swift', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+describe('rubyRequireStrategy', () => {
+  it('resolves require_relative paths via suffix matching', () => {
+    const files = ['lib/models/user.rb'];
+    const ctx = makeCtx(files);
+    const result = rubyRequireStrategy('./models/user', 'lib/app.rb', ctx);
+    expect(result).toEqual({ kind: 'files', files });
+  });
+
+  it('returns null when no file matches the require path', () => {
+    const ctx = makeCtx(['lib/models/user.rb']);
+    const result = rubyRequireStrategy('./missing/file', 'lib/app.rb', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Per-language configs — all construct cleanly
+// ---------------------------------------------------------------------------
+
+describe('per-language import configs', () => {
+  const configs: { name: string; config: ImportResolutionConfig }[] = [
+    { name: 'TypeScript', config: typescriptImportConfig },
+    { name: 'JavaScript', config: javascriptImportConfig },
+    { name: 'Vue', config: vueImportConfig },
+    { name: 'C', config: cImportConfig },
+    { name: 'C++', config: cppImportConfig },
+    { name: 'Go', config: goImportConfig },
+    { name: 'Java', config: javaImportConfig },
+    { name: 'Kotlin', config: kotlinImportConfig },
+    { name: 'Python', config: pythonImportConfig },
+    { name: 'Rust', config: rustImportConfig },
+    { name: 'C#', config: csharpImportConfig },
+    { name: 'PHP', config: phpImportConfig },
+    { name: 'Swift', config: swiftImportConfig },
+    { name: 'Dart', config: dartImportConfig },
+    { name: 'Ruby', config: rubyImportConfig },
+  ];
+
+  for (const { name, config } of configs) {
+    it(`${name} config has strategies and constructs a resolver`, () => {
+      expect(config.strategies.length).toBeGreaterThan(0);
+      expect(() => createImportResolver(config)).not.toThrow();
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// createStandardStrategy — reusable across languages
+// ---------------------------------------------------------------------------
+
+describe('createStandardStrategy', () => {
+  it('creates a reusable strategy from a language', () => {
+    const strategy = createStandardStrategy(SupportedLanguages.TypeScript);
+    expect(typeof strategy).toBe('function');
+  });
+
+  it('resolves relative imports', () => {
+    const strategy = createStandardStrategy(SupportedLanguages.TypeScript);
+    const ctx = makeCtx(['src/utils.ts']);
+    const result = strategy('./utils', 'src/index.ts', ctx);
+    expect(result).toEqual({ kind: 'files', files: ['src/utils.ts'] });
+  });
+
+  it('returns null for unresolvable imports', () => {
+    const strategy = createStandardStrategy(SupportedLanguages.TypeScript);
+    const ctx = makeCtx([]);
+    const result = strategy('./nonexistent', 'src/index.ts', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Python strategy — absorbs unresolved relative imports
+// ---------------------------------------------------------------------------
+
+describe('pythonImportStrategy', () => {
+  it('absorbs unresolved relative imports with empty-files sentinel', () => {
+    const ctx = makeCtx([]);
+    const result = pythonImportStrategy('.nonexistent', 'src/app.py', ctx);
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('returns null for non-relative imports (allows chain to continue)', () => {
+    const ctx = makeCtx([]);
+    const result = pythonImportStrategy('os', 'src/app.py', ctx);
+    expect(result).toBeNull();
+  });
+
+  it('absorbs unresolved external dotted imports instead of suffix-matching local basename files', () => {
+    const ctx = makeCtx(['accounts/apps.py', 'billing/apps.py']);
+    const result = pythonImportStrategy('django.apps', 'accounts/apps.py', ctx);
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('absorbs unresolved nested external dotted imports like django.urls and django.core.*', () => {
+    const ctx = makeCtx(['config/asgi.py', 'config/urls.py', 'config/wsgi.py']);
+
+    expect(pythonImportStrategy('django.urls', 'config/urls.py', ctx)).toEqual({
+      kind: 'files',
+      files: [],
+    });
+    expect(pythonImportStrategy('django.core.asgi', 'config/asgi.py', ctx)).toEqual({
+      kind: 'files',
+      files: [],
+    });
+    expect(pythonImportStrategy('django.core.wsgi', 'config/wsgi.py', ctx)).toEqual({
+      kind: 'files',
+      files: [],
+    });
+  });
+
+  it('keeps dotted internal imports unresolved here when the leading package exists in-repo', () => {
+    const ctx = makeCtx(['accounts/models.py', 'billing/models.py']);
+    const result = pythonImportStrategy('accounts.models', 'billing/models.py', ctx);
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Dart strategies — absorbs SDK / external package imports
+// ---------------------------------------------------------------------------
+
+describe('dartPackageStrategy', () => {
+  it('absorbs dart: SDK imports', () => {
+    const ctx = makeCtx([]);
+    const result = dartPackageStrategy("'dart:async'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('absorbs external package: imports', () => {
+    const ctx = makeCtx([]);
+    const result = dartPackageStrategy("'package:http/http.dart'", 'lib/main.dart', ctx);
+    expect(result).toEqual({ kind: 'files', files: [] });
+  });
+
+  it('returns null for relative imports (chains to dartRelativeStrategy)', () => {
+    const ctx = makeCtx([]);
+    const result = dartPackageStrategy("'models.dart'", 'lib/main.dart', ctx);
+    expect(result).toBeNull();
+  });
+});
diff --git a/gitnexus/test/unit/lbug-embedding-hashes.test.ts b/gitnexus/test/unit/lbug-embedding-hashes.test.ts
new file mode 100644
index 000000000..7ad3e086e
--- /dev/null
+++ b/gitnexus/test/unit/lbug-embedding-hashes.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vitest';
+import { STALE_HASH_SENTINEL } from '../../src/core/lbug/schema.js';
+import { fetchExistingEmbeddingHashes } from '../../src/core/lbug/lbug-adapter.js';
+
+describe('fetchExistingEmbeddingHashes', () => {
+  it('treats rows without chunk-aware metadata as stale even when contentHash exists', async () => {
+    const execQuery = vi.fn().mockResolvedValue([
+      {
+        nodeId: 'Function:src/main.ts:foo',
+        chunkIndex: null,
+        startLine: null,
+        endLine: null,
+        contentHash: 'abcdef1234567890abcdef1234567890abcdef12',
+      },
+    ]);
+
+    const result = await fetchExistingEmbeddingHashes(execQuery);
+
+    expect(result?.get('Function:src/main.ts:foo')).toBe(STALE_HASH_SENTINEL);
+  });
+
+  it('preserves contentHash for chunk-aware rows', async () => {
+    const hash = 'abcdef1234567890abcdef1234567890abcdef12';
+    const execQuery = vi.fn().mockResolvedValue([
+      {
+        nodeId: 'Function:src/main.ts:foo',
+        chunkIndex: 0,
+        startLine: 10,
+        endLine: 12,
+        contentHash: hash,
+      },
+    ]);
+
+    const result = await fetchExistingEmbeddingHashes(execQuery);
+
+    expect(result?.get('Function:src/main.ts:foo')).toBe(hash);
+  });
+
+  it('falls back to stale hashes when chunk-aware columns are missing from the schema', async () => {
+    const execQuery = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('Binder exception: column chunkIndex does not exist'))
+      .mockResolvedValueOnce([{ nodeId: 'Function:src/main.ts:foo' }]);
+
+    const result = await fetchExistingEmbeddingHashes(execQuery);
+
+    expect(result?.get('Function:src/main.ts:foo')).toBe(STALE_HASH_SENTINEL);
+    expect(execQuery).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/gitnexus/test/unit/local-backend-maxbuffer.test.ts b/gitnexus/test/unit/local-backend-maxbuffer.test.ts
new file mode 100644
index 000000000..f67675021
--- /dev/null
+++ b/gitnexus/test/unit/local-backend-maxbuffer.test.ts
@@ -0,0 +1,48 @@
+/**
+ * Source-code regression: ENOBUFS on large git/rg output.
+ *
+ * Node's default maxBuffer for execFileSync is 1 MB, which is easily exceeded
+ * by `git diff` on repos with large unstaged changes (e.g. unignored build
+ * folders) — see the original bug report:
+ *
+ *   "spawnSync git ENOBUFS in gitnexus_detect_changes(scope=\"unstaged\")
+ *    due to missing maxBuffer".
+ *
+ * Every `execFileSync` call in `local-backend.ts` that captures stdout
+ * (i.e. sets `encoding`) MUST pass an explicit `maxBuffer`. This test is a
+ * lightweight static guard so the regression cannot silently come back.
+ *
+ * Kept as a standalone file (no LocalBackend import) so it does not depend
+ * on the LadybugDB native binding being available in the test environment.
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+const SOURCE_PATH = path.join(__dirname, '../../src/mcp/local/local-backend.ts');
+
+describe('local-backend: execFileSync maxBuffer regression', () => {
+  const source = fs.readFileSync(SOURCE_PATH, 'utf-8');
+
+  it('every stdout-capturing execFileSync call passes maxBuffer', () => {
+    // Match each `execFileSync(...)` call. The local-backend.ts call sites use
+    // a single trailing options object literal, so a non-greedy match up to the
+    // closing `)` of the statement is sufficient.
+    const callRe = /execFileSync\s*\(([\s\S]*?)\)\s*;/g;
+    const offenders: string[] = [];
+    let match: RegExpExecArray | null;
+    while ((match = callRe.exec(source)) !== null) {
+      const args = match[1];
+      // Only stdout-capturing calls (encoding set) are at risk of ENOBUFS.
+      if (!/encoding\s*:/.test(args)) continue;
+      if (!/maxBuffer\s*:/.test(args)) {
+        const lineNo = source.slice(0, match.index).split('\n').length;
+        offenders.push(`line ${lineNo}: ${args.replace(/\s+/g, ' ').slice(0, 160)}`);
+      }
+    }
+    expect(
+      offenders,
+      `execFileSync calls missing explicit maxBuffer (ENOBUFS risk):\n${offenders.join('\n')}`,
+    ).toEqual([]);
+  });
+});
diff --git a/gitnexus/test/unit/model/field-registry.test.ts b/gitnexus/test/unit/model/field-registry.test.ts
index 4c6e093d7..ff1f749b1 100644
--- a/gitnexus/test/unit/model/field-registry.test.ts
+++ b/gitnexus/test/unit/model/field-registry.test.ts
@@ -8,7 +8,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { createFieldRegistry } from '../../../src/core/ingestion/model/field-registry.js';
-import type { SymbolDefinition } from '../../../src/core/ingestion/model/symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 import { makeDef as makeBaseDef } from './helpers.js';
 
 const makeDef = (overrides: Partial<SymbolDefinition> = {}): SymbolDefinition =>
diff --git a/gitnexus/test/unit/model/helpers.ts b/gitnexus/test/unit/model/helpers.ts
index 04856f8d3..00c5fef06 100644
--- a/gitnexus/test/unit/model/helpers.ts
+++ b/gitnexus/test/unit/model/helpers.ts
@@ -6,7 +6,7 @@
  * test file that uses it.
  */
 
-import type { SymbolDefinition } from '../../../src/core/ingestion/model/symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 
 /**
  * Build a {@link SymbolDefinition} with sensible defaults. Every field
diff --git a/gitnexus/test/unit/model/registration-table.test.ts b/gitnexus/test/unit/model/registration-table.test.ts
index 067b7fc20..fe37d0bbb 100644
--- a/gitnexus/test/unit/model/registration-table.test.ts
+++ b/gitnexus/test/unit/model/registration-table.test.ts
@@ -9,7 +9,7 @@ import { createTypeRegistry } from '../../../src/core/ingestion/model/type-regis
 import { createMethodRegistry } from '../../../src/core/ingestion/model/method-registry.js';
 import { createFieldRegistry } from '../../../src/core/ingestion/model/field-registry.js';
 import { ALL_NODE_LABELS } from '../../../src/core/ingestion/model/index.js';
-import type { SymbolDefinition } from '../../../src/core/ingestion/model/symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 import { makeDef as makeBaseDef } from './helpers.js';
 
 // ---------------------------------------------------------------------------
diff --git a/gitnexus/test/unit/model/type-registry.test.ts b/gitnexus/test/unit/model/type-registry.test.ts
index 8f0eee838..9eaf61c4e 100644
--- a/gitnexus/test/unit/model/type-registry.test.ts
+++ b/gitnexus/test/unit/model/type-registry.test.ts
@@ -10,7 +10,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { createTypeRegistry } from '../../../src/core/ingestion/model/type-registry.js';
-import type { SymbolDefinition } from '../../../src/core/ingestion/model/symbol-table.js';
+import type { SymbolDefinition } from 'gitnexus-shared';
 import { makeDef as makeBaseDef } from './helpers.js';
 
 const makeDef = (overrides: Partial<SymbolDefinition> = {}): SymbolDefinition =>
diff --git a/gitnexus/test/unit/phase-timer.test.ts b/gitnexus/test/unit/phase-timer.test.ts
new file mode 100644
index 000000000..f606ffa7d
--- /dev/null
+++ b/gitnexus/test/unit/phase-timer.test.ts
@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { PhaseTimer } from '../../src/core/search/phase-timer.js';
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+describe('PhaseTimer', () => {
+  it('start/stop records a single phase', async () => {
+    const t = new PhaseTimer();
+    t.start('bm25');
+    await sleep(20);
+    t.stop();
+
+    const phases = t.summary();
+    expect(phases.bm25).toBeGreaterThanOrEqual(15); // allow a bit of scheduler slack
+    expect(Object.keys(phases)).toEqual(['bm25']);
+  });
+
+  it('start implicitly stops the previous phase', async () => {
+    const t = new PhaseTimer();
+    t.start('a');
+    await sleep(10);
+    t.start('b'); // auto-stops 'a'
+    await sleep(10);
+    t.stop();
+
+    const phases = t.summary();
+    expect(phases.a).toBeGreaterThanOrEqual(5);
+    expect(phases.b).toBeGreaterThanOrEqual(5);
+  });
+
+  it('mark accumulates additive durations for the same phase', () => {
+    const t = new PhaseTimer();
+    t.mark('x', 5);
+    t.mark('x', 3);
+    t.mark('y', 7);
+
+    const phases = t.summary();
+    expect(phases.x).toBe(8);
+    expect(phases.y).toBe(7);
+  });
+
+  it('time() records concurrent promises independently (Promise.all safe)', async () => {
+    const t = new PhaseTimer();
+    await Promise.all([t.time('a', sleep(30)), t.time('b', sleep(80))]);
+
+    const phases = t.summary();
+    // Both phases recorded independently despite overlapping in time.
+    expect(phases.a).toBeGreaterThanOrEqual(25);
+    expect(phases.a).toBeLessThan(80);
+    expect(phases.b).toBeGreaterThanOrEqual(75);
+  });
+
+  it('mark rejects negative or non-finite durations', () => {
+    const t = new PhaseTimer();
+    t.mark('x', -1);
+    t.mark('x', Number.NaN);
+    t.mark('x', Number.POSITIVE_INFINITY);
+
+    const phases = t.summary();
+    expect(phases.x).toBeUndefined();
+  });
+
+  it('totalMs sums all phases and implicitly stops the active one', async () => {
+    const t = new PhaseTimer();
+    t.mark('a', 10);
+    t.mark('b', 15);
+    t.start('c');
+    await sleep(20);
+    // Call totalMs without stopping — it should stop 'c' implicitly.
+    const total = t.totalMs();
+
+    expect(total).toBeGreaterThanOrEqual(40); // 10 + 15 + ~20
+    const phases = t.summary();
+    expect(phases.c).toBeGreaterThanOrEqual(15);
+  });
+});
diff --git a/gitnexus/test/unit/registry-primary-flag.test.ts b/gitnexus/test/unit/registry-primary-flag.test.ts
new file mode 100644
index 000000000..20a547e24
--- /dev/null
+++ b/gitnexus/test/unit/registry-primary-flag.test.ts
@@ -0,0 +1,152 @@
+/**
+ * Unit tests for `registry-primary-flag` (RFC #909 Ring 2 PKG #924).
+ *
+ * Flag is `REGISTRY_PRIMARY_<UPPER(lang)>`. Each test manipulates
+ * `process.env` directly and restores it in `afterEach` — there is no
+ * per-process cache to invalidate, so isolation is lexical.
+ */
+
+import { describe, it, expect, afterEach, beforeEach } from 'vitest';
+import { SupportedLanguages } from 'gitnexus-shared';
+import {
+  envVarNameFor,
+  isRegistryPrimary,
+  primaryLanguages,
+} from '../../src/core/ingestion/registry-primary-flag.js';
+
+// ─── Test isolation ─────────────────────────────────────────────────────────
+//
+// Scrub every `REGISTRY_PRIMARY_*` env var before + after each test so
+// parallel vitest runs on the same process don't bleed state.
+
+function clearAllRegistryPrimaryVars(): void {
+  for (const key of Object.keys(process.env)) {
+    if (key.startsWith('REGISTRY_PRIMARY_')) delete process.env[key];
+  }
+}
+
+beforeEach(clearAllRegistryPrimaryVars);
+afterEach(clearAllRegistryPrimaryVars);
+
+// ─── envVarNameFor ─────────────────────────────────────────────────────────
+
+describe('envVarNameFor', () => {
+  it('produces upper-cased env-var names from the enum value', () => {
+    expect(envVarNameFor(SupportedLanguages.Python)).toBe('REGISTRY_PRIMARY_PYTHON');
+    expect(envVarNameFor(SupportedLanguages.TypeScript)).toBe('REGISTRY_PRIMARY_TYPESCRIPT');
+    expect(envVarNameFor(SupportedLanguages.JavaScript)).toBe('REGISTRY_PRIMARY_JAVASCRIPT');
+  });
+
+  it('uses the enum VALUE, not the key, for languages whose key differs from the value', () => {
+    // Key 'CPlusPlus' → value 'cpp' → env var 'REGISTRY_PRIMARY_CPP'.
+    // Users see the language by its canonical name, not its TS symbol.
+    expect(envVarNameFor(SupportedLanguages.CPlusPlus)).toBe('REGISTRY_PRIMARY_CPP');
+    expect(envVarNameFor(SupportedLanguages.CSharp)).toBe('REGISTRY_PRIMARY_CSHARP');
+  });
+
+  it('covers every member of SupportedLanguages', () => {
+    // Build env-var names for every language and assert no duplicates —
+    // catches a future enum-value collision or accidental renaming.
+    const names = new Set<string>();
+    for (const lang of Object.values(SupportedLanguages)) {
+      names.add(envVarNameFor(lang));
+    }
+    expect(names.size).toBe(Object.values(SupportedLanguages).length);
+  });
+});
+
+// ─── isRegistryPrimary ─────────────────────────────────────────────────────
+
+describe('isRegistryPrimary', () => {
+  it('returns false by default (no env var set)', () => {
+    for (const lang of Object.values(SupportedLanguages)) {
+      expect(isRegistryPrimary(lang)).toBe(false);
+    }
+  });
+
+  it("returns true when the env var is 'true' (lowercase)", () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'true';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+  });
+
+  it("returns true when the env var is '1'", () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = '1';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+  });
+
+  it("returns true when the env var is 'yes'", () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'yes';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+  });
+
+  it('accepts mixed-case and whitespace-padded truthy values', () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = '  TRUE  ';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'Yes';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+  });
+
+  it("returns false for falsy-looking values ('false', '0', empty, 'off')", () => {
+    for (const value of ['false', '0', '', 'off', 'no', 'disabled']) {
+      process.env['REGISTRY_PRIMARY_PYTHON'] = value;
+      expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(false);
+    }
+  });
+
+  it('returns false for unrecognized tokens (fail-safe on typos)', () => {
+    // User meant to type 'true' but fat-fingered — conservative: treat as off.
+    for (const value of ['ture', 'tru', 'yeah', 'enable', 'y']) {
+      process.env['REGISTRY_PRIMARY_PYTHON'] = value;
+      expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(false);
+    }
+  });
+
+  it('isolates flags per-language (one on does not affect others)', () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'true';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+    expect(isRegistryPrimary(SupportedLanguages.Java)).toBe(false);
+    expect(isRegistryPrimary(SupportedLanguages.Go)).toBe(false);
+  });
+
+  it('respects a mid-process env-var mutation (no stale cache)', () => {
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(false);
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'true';
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(true);
+    delete process.env['REGISTRY_PRIMARY_PYTHON'];
+    expect(isRegistryPrimary(SupportedLanguages.Python)).toBe(false);
+  });
+
+  it('handles the CPlusPlus → REGISTRY_PRIMARY_CPP mapping correctly', () => {
+    process.env['REGISTRY_PRIMARY_CPP'] = 'true';
+    expect(isRegistryPrimary(SupportedLanguages.CPlusPlus)).toBe(true);
+    // Negative: the TS-key-style name is NOT read.
+    delete process.env['REGISTRY_PRIMARY_CPP'];
+    process.env['REGISTRY_PRIMARY_CPLUSPLUS'] = 'true';
+    expect(isRegistryPrimary(SupportedLanguages.CPlusPlus)).toBe(false);
+  });
+});
+
+// ─── primaryLanguages ──────────────────────────────────────────────────────
+
+describe('primaryLanguages', () => {
+  it('returns an empty set when no flags are set', () => {
+    expect(primaryLanguages().size).toBe(0);
+  });
+
+  it('returns exactly the flipped languages', () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'true';
+    process.env['REGISTRY_PRIMARY_GO'] = '1';
+    process.env['REGISTRY_PRIMARY_JAVA'] = 'false'; // explicitly off
+    const enabled = primaryLanguages();
+    expect(enabled.has(SupportedLanguages.Python)).toBe(true);
+    expect(enabled.has(SupportedLanguages.Go)).toBe(true);
+    expect(enabled.has(SupportedLanguages.Java)).toBe(false);
+    expect(enabled.size).toBe(2);
+  });
+
+  it('returns a plain Set (not a frozen proxy) — consistent shape', () => {
+    process.env['REGISTRY_PRIMARY_PYTHON'] = 'true';
+    const enabled = primaryLanguages();
+    expect(enabled).toBeInstanceOf(Set);
+  });
+});
diff --git a/gitnexus/test/unit/repo-manager.test.ts b/gitnexus/test/unit/repo-manager.test.ts
index 08afceaff..83827fc15 100644
--- a/gitnexus/test/unit/repo-manager.test.ts
+++ b/gitnexus/test/unit/repo-manager.test.ts
@@ -13,7 +13,13 @@ import {
   getStoragePaths,
   readRegistry,
   loadCLIConfig,
+  registerRepo,
+  listRegisteredRepos,
+  RegistryNameCollisionError,
+  type RepoMeta,
 } from '../../src/storage/repo-manager.js';
+import { parseRepoNameFromUrl, getInferredRepoName } from '../../src/storage/git.js';
+import { execSync } from 'child_process';
 import { createTempDir } from '../helpers/test-db.js';
 
 // ─── getStoragePath ──────────────────────────────────────────────────
@@ -133,3 +139,317 @@ describe('API key file permissions', () => {
     expect(source).toContain("process.platform !== 'win32'");
   });
 });
+
+// ─── analyze --name <alias> + duplicate-name guard (#829) ────────────
+//
+// Each test isolates the global registry by pointing GITNEXUS_HOME at a
+// per-test tmpdir. `getGlobalDir()` honors that env var, so registerRepo
+// writes/reads a sandboxed registry.json without touching the user's
+// real ~/.gitnexus.
+
+describe('registerRepo name override + collision guard (#829)', () => {
+  let tmpHome: Awaited<ReturnType<typeof createTempDir>>;
+  let tmpRepoA: Awaited<ReturnType<typeof createTempDir>>;
+  let tmpRepoB: Awaited<ReturnType<typeof createTempDir>>;
+  let savedGitnexusHome: string | undefined;
+
+  const meta: RepoMeta = {
+    repoPath: '',
+    lastCommit: 'abc1234',
+    indexedAt: '2026-04-18T12:00:00.000Z',
+    stats: { files: 1, nodes: 1 },
+  };
+
+  beforeEach(async () => {
+    tmpHome = await createTempDir('gitnexus-registry-home-');
+    tmpRepoA = await createTempDir('gitnexus-repo-a-');
+    tmpRepoB = await createTempDir('gitnexus-repo-b-');
+    savedGitnexusHome = process.env.GITNEXUS_HOME;
+    process.env.GITNEXUS_HOME = tmpHome.dbPath;
+  });
+
+  afterEach(async () => {
+    if (savedGitnexusHome === undefined) delete process.env.GITNEXUS_HOME;
+    else process.env.GITNEXUS_HOME = savedGitnexusHome;
+    await tmpHome.cleanup();
+    await tmpRepoA.cleanup();
+    await tmpRepoB.cleanup();
+  });
+
+  it('registerRepo({ name: "alias" }) stores the alias instead of basename', async () => {
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'custom-alias' });
+
+    const entries = await listRegisteredRepos();
+    expect(entries).toHaveLength(1);
+    expect(entries[0].name).toBe('custom-alias');
+    expect(entries[0].name).not.toBe(path.basename(tmpRepoA.dbPath));
+  });
+
+  it('re-registerRepo on same path without name preserves an existing alias', async () => {
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'custom-alias' });
+    // Second call with no opts should keep the alias, not revert to basename.
+    await registerRepo(tmpRepoA.dbPath, meta);
+
+    const entries = await listRegisteredRepos();
+    expect(entries).toHaveLength(1);
+    expect(entries[0].name).toBe('custom-alias');
+  });
+
+  it('re-registerRepo with a different name overrides the previous alias', async () => {
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'old-alias' });
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'new-alias' });
+
+    const entries = await listRegisteredRepos();
+    expect(entries).toHaveLength(1);
+    expect(entries[0].name).toBe('new-alias');
+  });
+
+  it('registerRepo throws RegistryNameCollisionError when another path uses the name', async () => {
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'shared' });
+
+    await expect(registerRepo(tmpRepoB.dbPath, meta, { name: 'shared' })).rejects.toBeInstanceOf(
+      RegistryNameCollisionError,
+    );
+
+    // And the colliding entry in the error carries enough info for the
+    // CLI layer to surface an actionable message without string-matching.
+    try {
+      await registerRepo(tmpRepoB.dbPath, meta, { name: 'shared' });
+    } catch (e) {
+      expect(e).toBeInstanceOf(RegistryNameCollisionError);
+      const err = e as RegistryNameCollisionError;
+      // err.registryName carries the colliding alias (exposed as its own
+      // field so err.name retains the inherited Error.prototype.name
+      // semantics for downstream `err.name === '…Error'` checks).
+      expect(err.registryName).toBe('shared');
+      expect(err.name).toBe('RegistryNameCollisionError');
+      expect(path.resolve(err.existingPath)).toBe(path.resolve(tmpRepoA.dbPath));
+      expect(path.resolve(err.requestedPath)).toBe(path.resolve(tmpRepoB.dbPath));
+    }
+
+    // Registry still only has the first entry — the failed call didn't
+    // corrupt state.
+    const entries = await listRegisteredRepos();
+    expect(entries).toHaveLength(1);
+    expect(entries[0].name).toBe('shared');
+  });
+
+  it('registerRepo({ name, allowDuplicateName: true }) allows the duplicate to coexist', async () => {
+    await registerRepo(tmpRepoA.dbPath, meta, { name: 'shared' });
+    await registerRepo(tmpRepoB.dbPath, meta, { name: 'shared', allowDuplicateName: true });
+
+    const entries = await listRegisteredRepos();
+    expect(entries).toHaveLength(2);
+    expect(entries.every((e) => e.name === 'shared')).toBe(true);
+    // Both paths are stored distinctly — the collision is surfaced to the
+    // user via resolveRepo / list output, not hidden at the storage layer.
+    const paths = entries.map((e) => path.resolve(e.path)).sort();
+    expect(paths).toEqual([path.resolve(tmpRepoA.dbPath), path.resolve(tmpRepoB.dbPath)].sort());
+  });
+
+  it('basename collisions without an explicit --name still register silently (backward-compat)', async () => {
+    // Create two sibling dirs whose basenames collide. Neither caller
+    // passes { name }, so the guard must NOT fire — this preserves the
+    // pre-#829 behaviour for users who don't know about --name yet.
+    const parentA = await createTempDir('gitnexus-collide-parent-a-');
+    const parentB = await createTempDir('gitnexus-collide-parent-b-');
+    const sharedBasename = 'app';
+    const pathA = path.join(parentA.dbPath, sharedBasename);
+    const pathB = path.join(parentB.dbPath, sharedBasename);
+    await fs.mkdir(pathA, { recursive: true });
+    await fs.mkdir(pathB, { recursive: true });
+
+    try {
+      await registerRepo(pathA, meta);
+      await registerRepo(pathB, meta); // must NOT throw
+
+      const entries = await listRegisteredRepos();
+      expect(entries).toHaveLength(2);
+      expect(entries[0].name).toBe(sharedBasename);
+      expect(entries[1].name).toBe(sharedBasename);
+    } finally {
+      await parentA.cleanup();
+      await parentB.cleanup();
+    }
+  });
+});
+
+// ─── parseRepoNameFromUrl + getInferredRepoName (#979) ───────────────
+
+describe('parseRepoNameFromUrl', () => {
+  it('parses HTTPS URLs and strips .git', () => {
+    expect(parseRepoNameFromUrl('https://github.com/owner/lume_spark.git')).toBe('lume_spark');
+    expect(parseRepoNameFromUrl('https://github.com/owner/lume_spark')).toBe('lume_spark');
+  });
+
+  it('parses SSH URLs (git@host:owner/repo.git)', () => {
+    expect(parseRepoNameFromUrl('git@github.com:owner/lume_spark.git')).toBe('lume_spark');
+    expect(parseRepoNameFromUrl('git@gitlab.com:group/sub/lume_spark.git')).toBe('lume_spark');
+  });
+
+  it('parses ssh:// and git:// URLs', () => {
+    expect(parseRepoNameFromUrl('ssh://git@host.example/owner/lume_spark.git')).toBe('lume_spark');
+    expect(parseRepoNameFromUrl('git://host.example/owner/lume_spark.git')).toBe('lume_spark');
+  });
+
+  it('parses local file:// URLs', () => {
+    expect(parseRepoNameFromUrl('file:///srv/git/lume_spark.git')).toBe('lume_spark');
+  });
+
+  it('handles trailing slashes and mixed-case .git', () => {
+    expect(parseRepoNameFromUrl('https://github.com/owner/lume_spark.GIT/')).toBe('lume_spark');
+    expect(parseRepoNameFromUrl('https://github.com/owner/lume_spark/')).toBe('lume_spark');
+  });
+
+  it('returns null for empty / null / undefined / unparseable input', () => {
+    expect(parseRepoNameFromUrl('')).toBeNull();
+    expect(parseRepoNameFromUrl('   ')).toBeNull();
+    expect(parseRepoNameFromUrl(null)).toBeNull();
+    expect(parseRepoNameFromUrl(undefined)).toBeNull();
+  });
+});
+
+describe('getInferredRepoName + registerRepo (#979 — git remote inference)', () => {
+  let tmpHome: Awaited<ReturnType<typeof createTempDir>>;
+  let savedGitnexusHome: string | undefined;
+
+  const meta: RepoMeta = {
+    repoPath: '',
+    lastCommit: 'abc1234',
+    indexedAt: '2026-04-19T00:00:00.000Z',
+    stats: { files: 1, nodes: 1 },
+  };
+
+  /** Initialise a real git repo at `dir` with the given remote URL. */
+  const initGitRepo = (dir: string, remoteUrl: string | null) => {
+    execSync('git init -q', { cwd: dir });
+    execSync('git config user.email "test@example.com"', { cwd: dir });
+    execSync('git config user.name "Test"', { cwd: dir });
+    if (remoteUrl) {
+      execSync(`git remote add origin ${remoteUrl}`, { cwd: dir });
+    }
+  };
+
+  beforeEach(async () => {
+    tmpHome = await createTempDir('gitnexus-registry-home-979-');
+    savedGitnexusHome = process.env.GITNEXUS_HOME;
+    process.env.GITNEXUS_HOME = tmpHome.dbPath;
+  });
+
+  afterEach(async () => {
+    if (savedGitnexusHome === undefined) delete process.env.GITNEXUS_HOME;
+    else process.env.GITNEXUS_HOME = savedGitnexusHome;
+    await tmpHome.cleanup();
+  });
+
+  it('getInferredRepoName returns null when there is no .git directory', async () => {
+    const tmp = await createTempDir('gitnexus-no-git-');
+    try {
+      expect(getInferredRepoName(tmp.dbPath)).toBeNull();
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('getInferredRepoName returns null when origin is unset', async () => {
+    const tmp = await createTempDir('gitnexus-no-origin-');
+    try {
+      initGitRepo(tmp.dbPath, null);
+      expect(getInferredRepoName(tmp.dbPath)).toBeNull();
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('getInferredRepoName returns the remote repo name when origin is set', async () => {
+    const tmp = await createTempDir('gitnexus-with-origin-');
+    try {
+      initGitRepo(tmp.dbPath, 'https://github.com/owner/lume_spark.git');
+      expect(getInferredRepoName(tmp.dbPath)).toBe('lume_spark');
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('registerRepo derives name from git remote when basename is generic (Gas-Town repro)', async () => {
+    // Reproduce <rig>/refinery/rig/.git layout: leaf basename is "rig",
+    // but origin URL says "lume_spark". The new precedence MUST pick up
+    // the remote-derived name instead of the basename.
+    const root = await createTempDir('gitnexus-gastown-');
+    try {
+      const rigPath = path.join(root.dbPath, 'lume_spark', 'refinery', 'rig');
+      await fs.mkdir(rigPath, { recursive: true });
+      initGitRepo(rigPath, 'git@github.com:gastown/lume_spark.git');
+
+      const name = await registerRepo(rigPath, meta);
+      expect(name).toBe('lume_spark');
+      expect(name).not.toBe('rig');
+
+      const entries = await listRegisteredRepos();
+      expect(entries).toHaveLength(1);
+      expect(entries[0].name).toBe('lume_spark');
+    } finally {
+      await root.cleanup();
+    }
+  });
+
+  it('two analyze calls of differently-remoted "rig" leaves no longer collide', async () => {
+    // Without the remote inference both would register as "rig"; with
+    // inference they pick up their distinct remotes — the original issue.
+    const root = await createTempDir('gitnexus-gastown-2-');
+    try {
+      const rigA = path.join(root.dbPath, 'lume_spark', 'refinery', 'rig');
+      const rigB = path.join(root.dbPath, 'gemba', 'refinery', 'rig');
+      await fs.mkdir(rigA, { recursive: true });
+      await fs.mkdir(rigB, { recursive: true });
+      initGitRepo(rigA, 'git@github.com:gastown/lume_spark.git');
+      initGitRepo(rigB, 'git@github.com:gastown/gemba.git');
+
+      const nameA = await registerRepo(rigA, meta);
+      const nameB = await registerRepo(rigB, meta);
+      expect(nameA).toBe('lume_spark');
+      expect(nameB).toBe('gemba');
+
+      const entries = await listRegisteredRepos();
+      expect(entries.map((e) => e.name).sort()).toEqual(['gemba', 'lume_spark']);
+    } finally {
+      await root.cleanup();
+    }
+  });
+
+  it('explicit --name still wins over remote inference', async () => {
+    const tmp = await createTempDir('gitnexus-name-wins-');
+    try {
+      initGitRepo(tmp.dbPath, 'https://github.com/owner/from-remote.git');
+      const name = await registerRepo(tmp.dbPath, meta, { name: 'user-alias' });
+      expect(name).toBe('user-alias');
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('preserved alias still wins over remote inference on re-analyze', async () => {
+    const tmp = await createTempDir('gitnexus-preserve-alias-');
+    try {
+      initGitRepo(tmp.dbPath, 'https://github.com/owner/from-remote.git');
+      // First analyze sets the alias…
+      await registerRepo(tmp.dbPath, meta, { name: 'sticky-alias' });
+      // …second analyze with no opts must keep it (not silently switch
+      // to the remote-derived name).
+      const name = await registerRepo(tmp.dbPath, meta);
+      expect(name).toBe('sticky-alias');
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+
+  it('falls back to basename when no .git / no remote is available', async () => {
+    const tmp = await createTempDir('gitnexus-fallback-basename-');
+    try {
+      const name = await registerRepo(tmp.dbPath, meta);
+      expect(name).toBe(path.basename(tmp.dbPath));
+    } finally {
+      await tmp.cleanup();
+    }
+  });
+});
diff --git a/gitnexus/test/unit/resolve-enclosing-owner.test.ts b/gitnexus/test/unit/resolve-enclosing-owner.test.ts
index b00da7d8c..6139d69af 100644
--- a/gitnexus/test/unit/resolve-enclosing-owner.test.ts
+++ b/gitnexus/test/unit/resolve-enclosing-owner.test.ts
@@ -87,7 +87,10 @@ end
 
     expect(info).not.toBeNull();
     expect(info!.className).toBe('Helpers');
-    expect(info!.classId).toContain('Module');
+    // Ruby modules are labeled `Trait` so mixin heritage resolves through
+    // the class-like type registry; the enclosing class id switches labels
+    // in lockstep with the structure-phase label.
+    expect(info!.classId).toContain('Trait');
   });
 
   it('returns null for file-level singleton_class without enclosing class', () => {
diff --git a/gitnexus/test/unit/ruby-self-call.test.ts b/gitnexus/test/unit/ruby-self-call.test.ts
new file mode 100644
index 000000000..1ac439a3b
--- /dev/null
+++ b/gitnexus/test/unit/ruby-self-call.test.ts
@@ -0,0 +1,316 @@
+/**
+ * Unit tests for `maybeRewriteRubyBareCallToSelf` — the self-inference helper
+ * that rewrites Ruby bare-identifier calls inside class/module bodies into
+ * `self`-receiver member calls (plan 005 DAG / Ruby `inferImplicitReceiver`).
+ *
+ * The helper is pure: given the call name, callForm, AST node, enclosing
+ * class, and a minimal provider shape, it returns a rewrite suggestion or
+ * null. These tests pin each gate + branch so regressions surface at unit
+ * level rather than through the Ruby integration fixtures.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import Parser from 'tree-sitter';
+import Ruby from 'tree-sitter-ruby';
+import { maybeRewriteRubyBareCallToSelf } from '../../src/core/ingestion/utils/ruby-self-call.js';
+import type { LanguageProvider } from '../../src/core/ingestion/language-provider.js';
+import type { SyntaxNode } from '../../src/core/ingestion/utils/ast-helpers.js';
+
+const parser = new Parser();
+
+beforeAll(() => {
+  parser.setLanguage(Ruby as unknown as Parser.Language);
+});
+
+function parseRuby(src: string): SyntaxNode {
+  return parser.parse(src).rootNode;
+}
+
+/** Find the first identifier node whose `text` matches `name` (DFS, pre-order). */
+function findIdentifier(root: SyntaxNode, name: string): SyntaxNode | null {
+  const stack: SyntaxNode[] = [root];
+  while (stack.length) {
+    const node = stack.pop()!;
+    if (node.type === 'identifier' && node.text === name) return node;
+    for (let i = node.childCount - 1; i >= 0; i--) {
+      const child = node.child(i);
+      if (child) stack.push(child);
+    }
+  }
+  return null;
+}
+
+/** Minimal provider stub matching the helper's structural expectations. */
+const rubyProviderStub: Pick<LanguageProvider, 'isBuiltInName' | 'mroStrategy'> = {
+  isBuiltInName: (name: string) =>
+    new Set(['puts', 'p', 'raise', 'require', 'include', 'extend', 'prepend', 'attr_accessor']).has(
+      name,
+    ),
+  mroStrategy: 'ruby-mixin',
+};
+
+const nonRubyProviderStub: Pick<LanguageProvider, 'isBuiltInName' | 'mroStrategy'> = {
+  isBuiltInName: () => false,
+  mroStrategy: 'first-wins',
+};
+
+describe('maybeRewriteRubyBareCallToSelf', () => {
+  it('rewrites bare call inside instance method → self-receiver member call', () => {
+    const root = parseRuby(`
+class Account
+  def call_greet
+    greet
+  end
+end
+`);
+    const call = findIdentifier(root, 'greet')!;
+    expect(call).not.toBeNull();
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'greet',
+      'free',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite).toEqual({
+      callForm: 'member',
+      receiverName: 'self',
+      receiverTypeName: 'Account',
+      dispatchKind: 'instance',
+    });
+  });
+
+  it('accepts `callForm === undefined` (body_statement bare identifier captures)', () => {
+    // Ruby body-statement captures produce callForm === undefined because the
+    // @call node IS the @call.name node. The helper must accept both undefined
+    // and 'free'.
+    const root = parseRuby(`
+class Account
+  def work
+    helper
+  end
+end
+`);
+    const call = findIdentifier(root, 'helper')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'helper',
+      undefined,
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite?.callForm).toBe('member');
+    expect(rewrite?.receiverTypeName).toBe('Account');
+  });
+
+  it('flags singleton dispatch for calls inside `def self.foo` bodies', () => {
+    const root = parseRuby(`
+class Account
+  def self.factory
+    log("building")
+  end
+end
+`);
+    const call = findIdentifier(root, 'log')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'log',
+      'free',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite?.dispatchKind).toBe('singleton');
+    expect(rewrite?.receiverTypeName).toBe('Account');
+  });
+
+  it('flags singleton dispatch for calls inside `class << self` body', () => {
+    const root = parseRuby(`
+class Account
+  class << self
+    def factory
+      log("msg")
+    end
+  end
+end
+`);
+    const call = findIdentifier(root, 'log')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'log',
+      'free',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite?.dispatchKind).toBe('singleton');
+  });
+
+  it('returns null for Kernel built-in methods (puts)', () => {
+    const root = parseRuby(`
+class Account
+  def greet
+    puts "hi"
+  end
+end
+`);
+    const call = findIdentifier(root, 'puts')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'puts',
+      'free',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('returns null for `super` keyword', () => {
+    const root = parseRuby(`
+class Account
+  def save
+    super
+  end
+end
+`);
+    const call = findIdentifier(root, 'super') ?? root;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'super',
+      'free',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('returns null at file-level (no enclosing class)', () => {
+    const root = parseRuby(`
+some_top_level_call
+`);
+    const call = findIdentifier(root, 'some_top_level_call')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'some_top_level_call',
+      'free',
+      call,
+      null,
+      rubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('returns null when callForm is already member (explicit receiver present)', () => {
+    const root = parseRuby(`
+class Account
+  def greet
+    self.say_hello
+  end
+end
+`);
+    const call = findIdentifier(root, 'say_hello')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'say_hello',
+      'member',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('returns null when callForm is constructor', () => {
+    const root = parseRuby(`
+class Account
+  def build
+    Account.new
+  end
+end
+`);
+    const call = findIdentifier(root, 'new')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'new',
+      'constructor',
+      call,
+      'Account',
+      rubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('returns null for non-Ruby providers (mroStrategy !== ruby-mixin)', () => {
+    const root = parseRuby(`
+class Account
+  def greet
+    some_call
+  end
+end
+`);
+    const call = findIdentifier(root, 'some_call')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'some_call',
+      'free',
+      call,
+      'Account',
+      nonRubyProviderStub,
+    );
+    expect(rewrite).toBeNull();
+  });
+
+  it('uses module name as receiverTypeName for calls inside module body', () => {
+    const root = parseRuby(`
+module Helpers
+  def format
+    capitalize
+  end
+end
+`);
+    const call = findIdentifier(root, 'capitalize')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'capitalize',
+      'free',
+      call,
+      'Helpers',
+      rubyProviderStub,
+    );
+    expect(rewrite).toEqual({
+      callForm: 'member',
+      receiverName: 'self',
+      receiverTypeName: 'Helpers',
+      dispatchKind: 'instance',
+    });
+  });
+
+  it('terminates walk at enclosing class/module (does not walk past into outer scopes)', () => {
+    // `outer_call` is inside `Inner#work`; Inner is nested inside Outer.
+    // Enclosing class is Inner — the helper should return dispatchKind='instance'
+    // without escaping to Outer's singleton methods (if any existed).
+    const root = parseRuby(`
+module Outer
+  class Inner
+    def work
+      outer_call
+    end
+  end
+end
+`);
+    const call = findIdentifier(root, 'outer_call')!;
+
+    const rewrite = maybeRewriteRubyBareCallToSelf(
+      'outer_call',
+      'free',
+      call,
+      'Inner',
+      rubyProviderStub,
+    );
+    expect(rewrite?.dispatchKind).toBe('instance');
+    expect(rewrite?.receiverTypeName).toBe('Inner');
+  });
+});
diff --git a/gitnexus/test/unit/schema.test.ts b/gitnexus/test/unit/schema.test.ts
index 78f0b6ccb..cab80984a 100644
--- a/gitnexus/test/unit/schema.test.ts
+++ b/gitnexus/test/unit/schema.test.ts
@@ -53,6 +53,7 @@ describe('LadybugDB Schema', () => {
         'TypeAlias',
         'Const',
         'Static',
+        'Variable',
         'Property',
         'Record',
         'Delegate',
@@ -67,8 +68,8 @@ describe('LadybugDB Schema', () => {
     });
 
     it('has expected total count', () => {
-      // 9 core + 18 multi-language + Route + Tool = 30
-      expect(NODE_TABLES).toHaveLength(30);
+      // 9 core + 19 multi-language + Route + Tool = 31
+      expect(NODE_TABLES).toHaveLength(31);
     });
   });
 
@@ -201,7 +202,7 @@ describe('LadybugDB Schema', () => {
 
   describe('schema query ordering', () => {
     it('NODE_SCHEMA_QUERIES has correct count', () => {
-      expect(NODE_SCHEMA_QUERIES).toHaveLength(30);
+      expect(NODE_SCHEMA_QUERIES).toHaveLength(31);
     });
 
     it('REL_SCHEMA_QUERIES has one relation table', () => {
@@ -209,8 +210,8 @@ describe('LadybugDB Schema', () => {
     });
 
     it('SCHEMA_QUERIES includes all node + rel + embedding schemas', () => {
-      // 30 node + 1 rel + 1 embedding = 32
-      expect(SCHEMA_QUERIES).toHaveLength(32);
+      // 31 node + 1 rel + 1 embedding = 33
+      expect(SCHEMA_QUERIES).toHaveLength(33);
     });
 
     it('node schemas come before relation schemas in SCHEMA_QUERIES', () => {
diff --git a/gitnexus/test/unit/scope-resolution/def-index.test.ts b/gitnexus/test/unit/scope-resolution/def-index.test.ts
new file mode 100644
index 000000000..3b13d4c2d
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/def-index.test.ts
@@ -0,0 +1,69 @@
+/**
+ * Unit tests for `buildDefIndex` / `DefIndex` (RFC #909 Ring 2 SHARED #913).
+ *
+ * Covers: build-from-list, O(1) lookup contract, first-write-wins on
+ * duplicate `nodeId`, readonly surface.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildDefIndex, type SymbolDefinition } from 'gitnexus-shared';
+
+const makeDef = (overrides: Partial<SymbolDefinition> = {}): SymbolDefinition => ({
+  nodeId: 'def:test',
+  filePath: 'src/test.ts',
+  type: 'Method',
+  ...overrides,
+});
+
+describe('buildDefIndex', () => {
+  it('builds an empty index from an empty input', () => {
+    const idx = buildDefIndex([]);
+    expect(idx.size).toBe(0);
+    expect(idx.get('anything')).toBeUndefined();
+    expect(idx.has('anything')).toBe(false);
+  });
+
+  it('stores a single def and round-trips by nodeId', () => {
+    const def = makeDef({ nodeId: 'def:User.save' });
+    const idx = buildDefIndex([def]);
+    expect(idx.size).toBe(1);
+    expect(idx.has('def:User.save')).toBe(true);
+    expect(idx.get('def:User.save')).toBe(def); // reference identity
+  });
+
+  it('stores multiple defs under their distinct ids', () => {
+    const a = makeDef({ nodeId: 'def:A' });
+    const b = makeDef({ nodeId: 'def:B' });
+    const c = makeDef({ nodeId: 'def:C' });
+    const idx = buildDefIndex([a, b, c]);
+    expect(idx.size).toBe(3);
+    expect(idx.get('def:A')).toBe(a);
+    expect(idx.get('def:B')).toBe(b);
+    expect(idx.get('def:C')).toBe(c);
+  });
+
+  it('first-write-wins on duplicate nodeId', () => {
+    const first = makeDef({ nodeId: 'def:dup', returnType: 'Original' });
+    const second = makeDef({ nodeId: 'def:dup', returnType: 'Shadow' });
+    const idx = buildDefIndex([first, second]);
+    expect(idx.size).toBe(1);
+    expect(idx.get('def:dup')).toBe(first);
+    expect(idx.get('def:dup')?.returnType).toBe('Original');
+  });
+
+  it("returns undefined for a missing id (doesn't throw)", () => {
+    const idx = buildDefIndex([makeDef({ nodeId: 'def:A' })]);
+    expect(idx.get('def:missing')).toBeUndefined();
+    expect(idx.has('def:missing')).toBe(false);
+  });
+
+  it('exposes byId as the underlying read-only Map for direct iteration', () => {
+    const a = makeDef({ nodeId: 'def:A' });
+    const b = makeDef({ nodeId: 'def:B' });
+    const idx = buildDefIndex([a, b]);
+    const entries = Array.from(idx.byId.entries())
+      .map(([id]) => id)
+      .sort();
+    expect(entries).toEqual(['def:A', 'def:B']);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/emit-references.test.ts b/gitnexus/test/unit/scope-resolution/emit-references.test.ts
new file mode 100644
index 000000000..c88dc998e
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/emit-references.test.ts
@@ -0,0 +1,495 @@
+/**
+ * Unit tests for `emit-references` (RFC #909 Ring 2 PKG #925).
+ *
+ * Covers kind → RelationshipType mapping, enclosing-def resolution
+ * through the scope tree, evidence serialization onto emitted edges,
+ * skip counts, and the optional `INGESTION_EMIT_SCOPES` scope-node
+ * flush.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  buildDefIndex,
+  buildMethodDispatchIndex,
+  buildModuleScopeIndex,
+  buildQualifiedNameIndex,
+  buildScopeTree,
+  type BindingRef,
+  type DefId,
+  type Range,
+  type Reference,
+  type ReferenceIndex,
+  type Scope,
+  type ScopeId,
+  type SymbolDefinition,
+} from 'gitnexus-shared';
+import { createKnowledgeGraph } from '../../../src/core/graph/graph.js';
+import {
+  emitReferencesToGraph,
+  emitScopeGraph,
+} from '../../../src/core/ingestion/emit-references.js';
+import type { ScopeResolutionIndexes } from '../../../src/core/ingestion/model/scope-resolution-indexes.js';
+
+// ─── Env isolation ────────────────────────────────────────────────────────
+
+let savedEnv: string | undefined;
+beforeEach(() => {
+  savedEnv = process.env['INGESTION_EMIT_SCOPES'];
+  delete process.env['INGESTION_EMIT_SCOPES'];
+});
+afterEach(() => {
+  if (savedEnv === undefined) delete process.env['INGESTION_EMIT_SCOPES'];
+  else process.env['INGESTION_EMIT_SCOPES'] = savedEnv;
+});
+
+// ─── Fixture builders ─────────────────────────────────────────────────────
+
+const range = (sl = 1, sc = 0, el = 100, ec = 0): Range => ({
+  startLine: sl,
+  startCol: sc,
+  endLine: el,
+  endCol: ec,
+});
+
+const def = (
+  nodeId: string,
+  type: SymbolDefinition['type'] = 'Method',
+  qname?: string,
+): SymbolDefinition => ({
+  nodeId,
+  filePath: 'x.ts',
+  type,
+  ...(qname !== undefined ? { qualifiedName: qname } : {}),
+});
+
+const scope = (
+  id: ScopeId,
+  parent: ScopeId | null,
+  kind: Scope['kind'],
+  ownedDefs: readonly SymbolDefinition[] = [],
+  r: Range = range(),
+  filePath = 'x.ts',
+  bindings: Record<string, readonly BindingRef[]> = {},
+): Scope => ({
+  id,
+  parent,
+  kind,
+  range: r,
+  filePath,
+  bindings: new Map(Object.entries(bindings)),
+  ownedDefs,
+  imports: [],
+  typeBindings: new Map(),
+});
+
+function makeIndexes(scopes: Scope[], allDefs: SymbolDefinition[]): ScopeResolutionIndexes {
+  return {
+    scopeTree: buildScopeTree(scopes),
+    defs: buildDefIndex(allDefs),
+    qualifiedNames: buildQualifiedNameIndex(allDefs),
+    moduleScopes: buildModuleScopeIndex(
+      scopes
+        .filter((s) => s.kind === 'Module')
+        .map((s) => ({ filePath: s.filePath, moduleScopeId: s.id })),
+    ),
+    methodDispatch: buildMethodDispatchIndex({
+      owners: [],
+      computeMro: () => [],
+      implementsOf: () => [],
+    }),
+    imports: new Map(),
+    bindings: new Map(),
+    referenceSites: [],
+    sccs: [],
+    stats: {
+      totalFiles: 0,
+      totalEdges: 0,
+      linkedEdges: 0,
+      unresolvedEdges: 0,
+      sccCount: 0,
+      largestSccSize: 0,
+    },
+  };
+}
+
+function buildRefIndex(sourceScope: ScopeId, refs: readonly Reference[]): ReferenceIndex {
+  const bySource = new Map<ScopeId, readonly Reference[]>();
+  bySource.set(sourceScope, refs);
+  const byTarget = new Map<DefId, Reference[]>();
+  for (const ref of refs) {
+    const bucket = byTarget.get(ref.toDef) ?? [];
+    bucket.push(ref);
+    byTarget.set(ref.toDef, bucket);
+  }
+  return {
+    bySourceScope: bySource,
+    byTargetDef: new Map(
+      Array.from(byTarget.entries()).map(([k, v]) => [k, Object.freeze([...v])]),
+    ),
+  };
+}
+
+// ─── Kind mapping + basic emission ────────────────────────────────────────
+
+describe('emitReferencesToGraph: kind mapping', () => {
+  it('maps call → CALLS and carries confidence + evidence onto the edge', () => {
+    const callerFn = def('def:saveUser', 'Function', 'saveUser');
+    const targetFn = def('def:User.save', 'Method', 'User.save');
+    const mod = scope('scope:m', null, 'Module', [callerFn, targetFn]);
+    const indexes = makeIndexes([mod], [callerFn, targetFn]);
+
+    const ref: Reference = {
+      fromScope: 'scope:m',
+      toDef: 'def:User.save',
+      atRange: range(10, 4, 10, 8),
+      kind: 'call',
+      confidence: 0.75,
+      evidence: [
+        { kind: 'local', weight: 0.55 },
+        { kind: 'arity-match', weight: 0.1, note: 'compatible' },
+      ],
+    };
+
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:m', [ref]),
+    });
+
+    expect(stats.edgesEmitted).toBe(1);
+    expect(graph.relationships).toHaveLength(1);
+    const edge = graph.relationships[0]!;
+    expect(edge.type).toBe('CALLS');
+    expect(edge.sourceId).toBe('def:saveUser');
+    expect(edge.targetId).toBe('def:User.save');
+    expect(edge.confidence).toBe(0.75);
+    expect(edge.evidence).toEqual([
+      { kind: 'local', weight: 0.55 },
+      { kind: 'arity-match', weight: 0.1, note: 'compatible' },
+    ]);
+    expect(edge.reason).toContain('call');
+    expect(edge.reason).toContain('0.750');
+  });
+
+  it('maps read / write → ACCESSES and stamps step=1 / step=2 for discrimination', () => {
+    const fn = def('def:render', 'Function');
+    const field = def('def:User.name', 'Property');
+    const mod = scope('scope:m', null, 'Module', [fn, field]);
+    const indexes = makeIndexes([mod], [fn, field]);
+
+    const readRef: Reference = {
+      fromScope: 'scope:m',
+      toDef: 'def:User.name',
+      atRange: range(5, 0, 5, 4),
+      kind: 'read',
+      confidence: 0.55,
+      evidence: [{ kind: 'local', weight: 0.55 }],
+    };
+    const writeRef: Reference = {
+      fromScope: 'scope:m',
+      toDef: 'def:User.name',
+      atRange: range(6, 0, 6, 4),
+      kind: 'write',
+      confidence: 0.55,
+      evidence: [{ kind: 'local', weight: 0.55 }],
+    };
+
+    const graph = createKnowledgeGraph();
+    emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:m', [readRef, writeRef]),
+    });
+
+    const edges = graph.relationships;
+    expect(edges).toHaveLength(2);
+    expect(edges.every((e) => e.type === 'ACCESSES')).toBe(true);
+    const readEdge = edges.find((e) => e.step === 1)!;
+    const writeEdge = edges.find((e) => e.step === 2)!;
+    expect(readEdge).toBeDefined();
+    expect(writeEdge).toBeDefined();
+  });
+
+  it('maps inherits → INHERITS and type-reference/import-use → USES', () => {
+    const hostFn = def('def:host', 'Function');
+    const base = def('def:Base', 'Class');
+    const mixin = def('def:Mixin', 'Class');
+    const module = def('def:SomeModule', 'Namespace');
+    const mod = scope('scope:m', null, 'Module', [hostFn, base, mixin, module]);
+    const indexes = makeIndexes([mod], [hostFn, base, mixin, module]);
+
+    const refs: Reference[] = [
+      {
+        fromScope: 'scope:m',
+        toDef: 'def:Base',
+        atRange: range(1, 0, 1, 4),
+        kind: 'inherits',
+        confidence: 0.9,
+        evidence: [],
+      },
+      {
+        fromScope: 'scope:m',
+        toDef: 'def:Mixin',
+        atRange: range(2, 0, 2, 4),
+        kind: 'type-reference',
+        confidence: 0.7,
+        evidence: [],
+      },
+      {
+        fromScope: 'scope:m',
+        toDef: 'def:SomeModule',
+        atRange: range(3, 0, 3, 4),
+        kind: 'import-use',
+        confidence: 0.5,
+        evidence: [],
+      },
+    ];
+
+    const graph = createKnowledgeGraph();
+    emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:m', refs),
+    });
+
+    const types = graph.relationships.map((r) => r.type).sort();
+    expect(types).toEqual(['INHERITS', 'USES', 'USES']);
+  });
+});
+
+// ─── Enclosing-def resolution ─────────────────────────────────────────────
+
+describe('enclosing-def resolution', () => {
+  it('uses the innermost Function/Method ancestor as the caller', () => {
+    const method = def('def:User.save', 'Method');
+    const classScope = scope('scope:c', 'scope:m', 'Class', [], range(5, 0, 40, 0));
+    const methodScope = scope('scope:f', 'scope:c', 'Function', [method], range(10, 0, 30, 0));
+    const mod = scope('scope:m', null, 'Module', [], range(1, 0, 100, 0));
+    const target = def('def:Logger.log', 'Method');
+    const indexes = makeIndexes([mod, classScope, methodScope], [method, target]);
+
+    // Reference fires from a block inside the method scope.
+    const ref: Reference = {
+      fromScope: 'scope:f',
+      toDef: 'def:Logger.log',
+      atRange: range(20, 4, 20, 8),
+      kind: 'call',
+      confidence: 0.75,
+      evidence: [],
+    };
+
+    const graph = createKnowledgeGraph();
+    emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:f', [ref]),
+    });
+
+    expect(graph.relationships[0]!.sourceId).toBe('def:User.save');
+  });
+
+  it('walks up to the parent Class if the immediate scope has no Function def', () => {
+    const classDef = def('def:User', 'Class');
+    const targetFn = def('def:Logger.log', 'Method');
+    const mod = scope('scope:m', null, 'Module', [], range(1, 0, 100, 0));
+    // Class scope owns the Class def but no Function/Method; fallback
+    // walks into the Class's owned defs.
+    const classScope = scope('scope:c', 'scope:m', 'Class', [classDef], range(5, 0, 50, 0));
+    const indexes = makeIndexes([mod, classScope], [classDef, targetFn]);
+
+    const ref: Reference = {
+      fromScope: 'scope:c',
+      toDef: 'def:Logger.log',
+      atRange: range(7, 0, 7, 4),
+      kind: 'call',
+      confidence: 0.55,
+      evidence: [],
+    };
+
+    const graph = createKnowledgeGraph();
+    emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:c', [ref]),
+    });
+
+    // No Function ancestor — falls back to the first owned def: the class itself.
+    expect(graph.relationships[0]!.sourceId).toBe('def:User');
+  });
+
+  it('increments skippedNoCaller when no ancestor has any owned defs', () => {
+    // Module scope is empty; the lone child scope references something
+    // but neither it nor its ancestors own anything.
+    const target = def('def:someClass', 'Class');
+    const mod = scope('scope:m', null, 'Module', [], range(1, 0, 100, 0));
+    const child = scope('scope:c', 'scope:m', 'Function', [], range(5, 0, 10, 0));
+    const indexes = makeIndexes([mod, child], [target]);
+
+    const ref: Reference = {
+      fromScope: 'scope:c',
+      toDef: 'def:someClass',
+      atRange: range(7, 0, 7, 4),
+      kind: 'type-reference',
+      confidence: 0.3,
+      evidence: [],
+    };
+
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:c', [ref]),
+    });
+
+    expect(stats.edgesEmitted).toBe(0);
+    expect(stats.skippedNoCaller).toBe(1);
+    expect(graph.relationships).toHaveLength(0);
+  });
+});
+
+// ─── Missing target ──────────────────────────────────────────────────────
+
+describe('missing target', () => {
+  it('skips references whose toDef is not in the DefIndex', () => {
+    const callerFn = def('def:caller', 'Function');
+    const mod = scope('scope:m', null, 'Module', [callerFn]);
+    const indexes = makeIndexes([mod], [callerFn]); // target def missing
+
+    const ref: Reference = {
+      fromScope: 'scope:m',
+      toDef: 'def:ghost',
+      atRange: range(5, 0, 5, 4),
+      kind: 'call',
+      confidence: 0.3,
+      evidence: [],
+    };
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:m', [ref]),
+    });
+    expect(stats.edgesEmitted).toBe(0);
+    expect(stats.skippedMissingTarget).toBe(1);
+    expect(graph.relationships).toHaveLength(0);
+  });
+});
+
+// ─── Scope-graph emission (INGESTION_EMIT_SCOPES) ─────────────────────────
+
+describe('scope-graph emission', () => {
+  it('stays off by default — no scope nodes emitted', () => {
+    const callerFn = def('def:caller', 'Function');
+    const targetFn = def('def:target', 'Method');
+    const mod = scope('scope:m', null, 'Module', [callerFn, targetFn]);
+    const indexes = makeIndexes([mod], [callerFn, targetFn]);
+
+    const ref: Reference = {
+      fromScope: 'scope:m',
+      toDef: 'def:target',
+      atRange: range(5, 0, 5, 4),
+      kind: 'call',
+      confidence: 0.5,
+      evidence: [],
+    };
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:m', [ref]),
+    });
+    expect(stats.scopeNodesEmitted).toBe(0);
+    expect(stats.scopeEdgesEmitted).toBe(0);
+    // No scope nodes in the graph either.
+    expect(graph.nodes.filter((n) => n.id.startsWith('scope:')).length).toBe(0);
+  });
+
+  it('emits Scope nodes + CONTAINS + DEFINES when INGESTION_EMIT_SCOPES=1', () => {
+    process.env['INGESTION_EMIT_SCOPES'] = '1';
+    const fn = def('def:fn', 'Function');
+    const childScope = scope('scope:f', 'scope:m', 'Function', [fn], range(5, 0, 10, 0));
+    const mod = scope('scope:m', null, 'Module', [], range(1, 0, 100, 0));
+    const indexes = makeIndexes([mod, childScope], [fn]);
+
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: buildRefIndex('scope:f', []),
+    });
+
+    expect(stats.scopeNodesEmitted).toBe(2); // module + function scope
+    // 1 CONTAINS (module→function) + 1 DEFINES (function→fn def) = 2
+    expect(stats.scopeEdgesEmitted).toBe(2);
+    const containsEdge = graph.relationships.find((e) => e.type === 'CONTAINS');
+    const definesEdge = graph.relationships.find((e) => e.type === 'DEFINES');
+    expect(containsEdge).toBeDefined();
+    expect(containsEdge!.sourceId).toBe('scope:m');
+    expect(containsEdge!.targetId).toBe('scope:f');
+    expect(definesEdge).toBeDefined();
+    expect(definesEdge!.targetId).toBe('def:fn');
+  });
+
+  it("treats 'true', 'yes' (case-insensitive) as enabled; anything else as disabled", () => {
+    const fn = def('def:fn', 'Function');
+    const mod = scope('scope:m', null, 'Module', [fn]);
+    const indexes = makeIndexes([mod], [fn]);
+
+    for (const value of ['true', 'TRUE', 'yes', '1']) {
+      process.env['INGESTION_EMIT_SCOPES'] = value;
+      const g = createKnowledgeGraph();
+      const stats = emitReferencesToGraph({
+        graph: g,
+        scopes: indexes,
+        referenceIndex: buildRefIndex('scope:m', []),
+      });
+      expect(stats.scopeNodesEmitted).toBeGreaterThan(0);
+    }
+    for (const value of ['false', '0', '', 'off', 'tru']) {
+      process.env['INGESTION_EMIT_SCOPES'] = value;
+      const g = createKnowledgeGraph();
+      const stats = emitReferencesToGraph({
+        graph: g,
+        scopes: indexes,
+        referenceIndex: buildRefIndex('scope:m', []),
+      });
+      expect(stats.scopeNodesEmitted).toBe(0);
+    }
+  });
+
+  it('emitScopeGraph can be called directly (bypasses env flag)', () => {
+    const fn = def('def:fn', 'Function');
+    const mod = scope('scope:m', null, 'Module', [fn]);
+    const indexes = makeIndexes([mod], [fn]);
+
+    const graph = createKnowledgeGraph();
+    const stats = emitScopeGraph({ graph, scopes: indexes });
+    expect(stats.scopeNodesEmitted).toBe(1);
+    expect(stats.scopeEdgesEmitted).toBe(1); // only the DEFINES edge; no parent scope
+  });
+});
+
+// ─── Empty input ──────────────────────────────────────────────────────────
+
+describe('empty input', () => {
+  it('returns zeroed stats and mutates nothing when ReferenceIndex is empty', () => {
+    const mod = scope('scope:m', null, 'Module', []);
+    const indexes = makeIndexes([mod], []);
+    const graph = createKnowledgeGraph();
+    const stats = emitReferencesToGraph({
+      graph,
+      scopes: indexes,
+      referenceIndex: { bySourceScope: new Map(), byTargetDef: new Map() },
+    });
+    expect(stats).toEqual({
+      edgesEmitted: 0,
+      skippedNoCaller: 0,
+      skippedMissingTarget: 0,
+      scopeNodesEmitted: 0,
+      scopeEdgesEmitted: 0,
+    });
+    expect(graph.nodes).toHaveLength(0);
+    expect(graph.relationships).toHaveLength(0);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/finalize-algorithm.test.ts b/gitnexus/test/unit/scope-resolution/finalize-algorithm.test.ts
new file mode 100644
index 000000000..501d0cba9
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/finalize-algorithm.test.ts
@@ -0,0 +1,443 @@
+/**
+ * Unit tests for `finalize` (RFC #909 Ring 2 SHARED #915).
+ *
+ * Covers: acyclic chain · single-SCC cycle · multi-SCC · wildcard
+ * expansion · re-export flattening · dynamic-unresolved passthrough ·
+ * bounded fixpoint cap · module-scope binding materialization · unresolved
+ * target · external target · provider `mergeBindings` precedence.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  finalize,
+  type FinalizeFile,
+  type FinalizeHooks,
+  type ParsedImport,
+  type BindingRef,
+  type SymbolDefinition,
+  type ScopeId,
+} from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const def = (
+  nodeId: string,
+  type: SymbolDefinition['type'] = 'Class',
+  qualifiedName?: string,
+): SymbolDefinition => ({
+  nodeId,
+  filePath: 'x',
+  type,
+  ...(qualifiedName !== undefined ? { qualifiedName } : {}),
+});
+
+const file = (
+  filePath: string,
+  localDefs: SymbolDefinition[] = [],
+  parsedImports: ParsedImport[] = [],
+): FinalizeFile => ({
+  filePath,
+  moduleScope: `scope:${filePath}#1:0-9999:0:Module`,
+  localDefs: localDefs.map((d) => ({ ...d, filePath })),
+  parsedImports,
+});
+
+/** Simple hook set: `resolveImportTarget` does a direct path lookup; wildcard
+ *  expansion returns the concrete names from the target's own local defs;
+ *  `mergeBindings` appends (no precedence logic). */
+const defaultHooks = (files: readonly FinalizeFile[]): FinalizeHooks => ({
+  resolveImportTarget(targetRaw) {
+    if (targetRaw === null || targetRaw.length === 0) return null;
+    return files.some((f) => f.filePath === targetRaw) ? targetRaw : null;
+  },
+  expandsWildcardTo(targetModuleScope) {
+    const target = files.find((f) => f.moduleScope === targetModuleScope);
+    if (target === undefined) return [];
+    return target.localDefs.map((d) => deriveSimple(d)).filter((n): n is string => n !== null);
+  },
+  mergeBindings(existing, incoming) {
+    return [...existing, ...incoming];
+  },
+});
+
+function deriveSimple(d: SymbolDefinition): string | null {
+  const q = d.qualifiedName;
+  if (q === undefined || q.length === 0) return null;
+  const dot = q.lastIndexOf('.');
+  return dot === -1 ? q : q.slice(dot + 1);
+}
+
+const named = (localName: string, importedName: string, targetRaw: string): ParsedImport => ({
+  kind: 'named',
+  localName,
+  importedName,
+  targetRaw,
+});
+
+const aliased = (
+  localName: string,
+  importedName: string,
+  alias: string,
+  targetRaw: string,
+): ParsedImport => ({ kind: 'alias', localName, importedName, alias, targetRaw });
+
+const namespace = (localName: string, importedName: string, targetRaw: string): ParsedImport => ({
+  kind: 'namespace',
+  localName,
+  importedName,
+  targetRaw,
+});
+
+const reexport = (localName: string, importedName: string, targetRaw: string): ParsedImport => ({
+  kind: 'reexport',
+  localName,
+  importedName,
+  targetRaw,
+});
+
+const wildcard = (targetRaw: string): ParsedImport => ({ kind: 'wildcard', targetRaw });
+
+const dynamic = (localName: string, targetRaw: string | null): ParsedImport => ({
+  kind: 'dynamic-unresolved',
+  localName,
+  targetRaw,
+});
+
+const firstImport = (out: ReturnType<typeof finalize>, scope: ScopeId) => {
+  const imports = out.imports.get(scope);
+  return imports?.[0];
+};
+
+const bindingsFor = (
+  out: ReturnType<typeof finalize>,
+  scope: ScopeId,
+  name: string,
+): readonly BindingRef[] => {
+  const scopeBindings = out.bindings.get(scope);
+  return scopeBindings?.get(name) ?? [];
+};
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('finalize', () => {
+  describe('trivial / acyclic', () => {
+    it('handles an empty workspace', () => {
+      const out = finalize({ files: [], workspaceIndex: undefined }, defaultHooks([]));
+      expect(out.stats.totalFiles).toBe(0);
+      expect(out.stats.totalEdges).toBe(0);
+      expect(out.sccs).toEqual([]);
+    });
+
+    it('resolves a single named import across two files', () => {
+      const b = file('b', [def('def:b.User', 'Class', 'b.User')]);
+      const a = file('a', [], [named('User', 'User', 'b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+
+      const edge = firstImport(out, a.moduleScope)!;
+      expect(edge.kind).toBe('named');
+      expect(edge.targetFile).toBe('b');
+      expect(edge.targetModuleScope).toBe(b.moduleScope);
+      expect(edge.targetDefId).toBe('def:b.User');
+      expect(edge.linkStatus).toBeUndefined();
+      expect(out.stats.linkedEdges).toBe(1);
+      expect(out.stats.unresolvedEdges).toBe(0);
+    });
+
+    it('marks an edge unresolved when target file cannot be resolved', () => {
+      const a = file('a', [], [named('User', 'User', 'external-pkg')]);
+      const out = finalize({ files: [a], workspaceIndex: undefined }, defaultHooks([a]));
+      const edge = firstImport(out, a.moduleScope)!;
+      expect(edge.linkStatus).toBe('unresolved');
+      expect(edge.targetFile).toBeNull();
+    });
+
+    it('marks an edge unresolved when target file exists but name is not exported', () => {
+      const b = file('b', [def('def:b.Other', 'Class', 'b.Other')]);
+      const a = file('a', [], [named('User', 'User', 'b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const edge = firstImport(out, a.moduleScope)!;
+      expect(edge.linkStatus).toBe('unresolved');
+      // targetFile still known — unresolvability is at the name level.
+      expect(edge.targetFile).toBe('b');
+    });
+
+    it('passes dynamic-unresolved edges through without linking', () => {
+      const a = file('a', [], [dynamic('', 'runtime.computed')]);
+      const out = finalize({ files: [a], workspaceIndex: undefined }, defaultHooks([a]));
+      const edge = firstImport(out, a.moduleScope)!;
+      expect(edge.kind).toBe('dynamic-unresolved');
+      expect(edge.targetFile).toBeNull();
+      expect(edge.linkStatus).toBeUndefined();
+    });
+  });
+
+  describe('cycles + bounded fixpoint', () => {
+    it('finalizes a two-file cycle (A → B → A) without hanging', () => {
+      const a = file('a', [def('def:a.X', 'Class', 'a.X')], [named('Y', 'Y', 'b')]);
+      const b = file('b', [def('def:b.Y', 'Class', 'b.Y')], [named('X', 'X', 'a')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+
+      const aEdge = firstImport(out, a.moduleScope)!;
+      const bEdge = firstImport(out, b.moduleScope)!;
+      expect(aEdge.targetDefId).toBe('def:b.Y');
+      expect(bEdge.targetDefId).toBe('def:a.X');
+      expect(out.stats.sccCount).toBeGreaterThanOrEqual(1);
+    });
+
+    it('packs cyclic files into a single SCC with isCycle=true', () => {
+      const a = file('a', [def('def:a.X', 'Class', 'a.X')], [named('Y', 'Y', 'b')]);
+      const b = file('b', [def('def:b.Y', 'Class', 'b.Y')], [named('X', 'X', 'a')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const cycles = out.sccs.filter((scc) => scc.isCycle);
+      expect(cycles.length).toBe(1);
+      expect(cycles[0]!.files.length).toBe(2);
+      expect(new Set(cycles[0]!.files)).toEqual(new Set(['a', 'b']));
+    });
+
+    it('separates disjoint SCCs', () => {
+      // a↔b cycle, c↔d cycle — disjoint.
+      const a = file('a', [def('def:a.X', 'Class', 'a.X')], [named('Y', 'Y', 'b')]);
+      const b = file('b', [def('def:b.Y', 'Class', 'b.Y')], [named('X', 'X', 'a')]);
+      const c = file('c', [def('def:c.P', 'Class', 'c.P')], [named('Q', 'Q', 'd')]);
+      const d = file('d', [def('def:d.Q', 'Class', 'd.Q')], [named('P', 'P', 'c')]);
+      const files = [a, b, c, d];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const cycleSCCs = out.sccs.filter((scc) => scc.isCycle);
+      expect(cycleSCCs.length).toBe(2);
+    });
+
+    it('reports stats distinguishing linked from unresolved edges in a cycle', () => {
+      const a = file(
+        'a',
+        [def('def:a.X', 'Class', 'a.X')],
+        [named('Y', 'Y', 'b'), named('Ghost', 'Ghost', 'b')],
+      );
+      const b = file('b', [def('def:b.Y', 'Class', 'b.Y')], [named('X', 'X', 'a')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      expect(out.stats.linkedEdges).toBe(2); // a→b.Y and b→a.X resolve
+      expect(out.stats.unresolvedEdges).toBe(1); // a→b.Ghost doesn't
+    });
+
+    it('transitions an intra-SCC edge to linkStatus=unresolved when the cap is reached', () => {
+      // A↔B cycle; A imports a name that B never exports. The file-level
+      // target resolves (b exists), but the name-level lookup never
+      // succeeds, so the fixpoint exhausts its cap and we fall through to
+      // `linkStatus: 'unresolved'` (distinct from `targetFile: null`).
+      const a = file(
+        'a',
+        [def('def:a.X', 'Class', 'a.X')],
+        [named('Ghost', 'Ghost', 'b'), named('Y', 'Y', 'b')],
+      );
+      const b = file('b', [def('def:b.Y', 'Class', 'b.Y')], [named('X', 'X', 'a')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+
+      const aEdges = out.imports.get(a.moduleScope) ?? [];
+      const ghost = aEdges.find((e) => e.localName === 'Ghost');
+      expect(ghost).toBeDefined();
+      // Cap-hit distinction: file target is known, but name never resolved.
+      expect(ghost!.targetFile).toBe('b');
+      expect(ghost!.linkStatus).toBe('unresolved');
+      expect(ghost!.targetDefId).toBeUndefined();
+    });
+  });
+
+  describe('wildcard expansion', () => {
+    it('expands `wildcard` into one ImportEdge per exported name', () => {
+      const b = file('b', [
+        def('def:b.X', 'Class', 'b.X'),
+        def('def:b.Y', 'Class', 'b.Y'),
+        def('def:b.Z', 'Class', 'b.Z'),
+      ]);
+      const a = file('a', [], [wildcard('b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const edges = out.imports.get(a.moduleScope) ?? [];
+      expect(edges.length).toBe(3);
+      expect(edges.every((e) => e.kind === 'wildcard-expanded')).toBe(true);
+      expect(new Set(edges.map((e) => e.localName))).toEqual(new Set(['X', 'Y', 'Z']));
+      expect(new Set(edges.map((e) => e.targetDefId))).toEqual(
+        new Set(['def:b.X', 'def:b.Y', 'def:b.Z']),
+      );
+    });
+
+    it('leaves a wildcard unresolved when the target file cannot be resolved', () => {
+      const a = file('a', [], [wildcard('external-pkg')]);
+      const out = finalize({ files: [a], workspaceIndex: undefined }, defaultHooks([a]));
+      const edges = out.imports.get(a.moduleScope) ?? [];
+      expect(edges.length).toBe(1);
+      expect(edges[0]!.linkStatus).toBe('unresolved');
+    });
+
+    it('expanded bindings land at `origin: wildcard`', () => {
+      const b = file('b', [def('def:b.X', 'Class', 'b.X')]);
+      const a = file('a', [], [wildcard('b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const bindings = bindingsFor(out, a.moduleScope, 'X');
+      expect(bindings.length).toBeGreaterThanOrEqual(1);
+      const imported = bindings.find((br) => br.origin === 'wildcard');
+      expect(imported).toBeDefined();
+      expect(imported!.def.nodeId).toBe('def:b.X');
+    });
+  });
+
+  describe('re-export flattening', () => {
+    it('sets transitiveVia on reexport edges', () => {
+      const c = file('c', [def('def:c.X', 'Class', 'c.X')]);
+      const b = file('b', [], [reexport('X', 'X', 'c')]);
+      const a = file('a', [], [named('X', 'X', 'b')]);
+      const files = [a, b, c];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const reexportEdge = firstImport(out, b.moduleScope)!;
+      expect(reexportEdge.kind).toBe('reexport');
+      expect(reexportEdge.transitiveVia).toEqual(['c']);
+    });
+
+    it('multi-hop re-export chains only resolve when intermediate files include the name in localDefs', () => {
+      // Contract (see FinalizeFile.localDefs doc): `finalize` looks up
+      // `importedName` in `B.localDefs`. If B re-exports X from C but does
+      // NOT include X in its own localDefs, A's import of X from B cannot
+      // resolve — the fixpoint doesn't mutate localDefs across iterations.
+      //
+      // This test documents the current behavior: parsers that want
+      // multi-hop chains to settle end-to-end must surface re-exported
+      // names in the intermediate file's localDefs (with the original
+      // source DefId).
+      const c = file('c', [def('def:c.X', 'Class', 'c.X')]);
+      // Variant 1: B does NOT include X in its own localDefs → A's import
+      // fails.
+      const bThin = file('b', [], [reexport('X', 'X', 'c')]);
+      const aThin = file('a', [], [named('X', 'X', 'b')]);
+      const thinFiles = [aThin, bThin, c];
+      const thinOut = finalize(
+        { files: thinFiles, workspaceIndex: undefined },
+        defaultHooks(thinFiles),
+      );
+      expect(firstImport(thinOut, aThin.moduleScope)!.linkStatus).toBe('unresolved');
+
+      // Variant 2: B includes X in its localDefs (re-exports surfaced) → A resolves.
+      const bThick = file(
+        'b',
+        [def('def:c.X', 'Class', 'b.X')], // B surfaces X with its own qname
+        [reexport('X', 'X', 'c')],
+      );
+      const aThick = file('a', [], [named('X', 'X', 'b')]);
+      const thickFiles = [aThick, bThick, c];
+      const thickOut = finalize(
+        { files: thickFiles, workspaceIndex: undefined },
+        defaultHooks(thickFiles),
+      );
+      expect(firstImport(thickOut, aThick.moduleScope)!.linkStatus).toBeUndefined();
+      expect(firstImport(thickOut, aThick.moduleScope)!.targetDefId).toBe('def:c.X');
+    });
+  });
+
+  describe('aliased + namespace imports', () => {
+    it('resolves an alias under its local name while preserving targetExportedName', () => {
+      const b = file('b', [def('def:b.User', 'Class', 'b.User')]);
+      const a = file('a', [], [aliased('Account', 'User', 'Account', 'b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const edge = firstImport(out, a.moduleScope)!;
+      expect(edge.kind).toBe('alias');
+      expect(edge.localName).toBe('Account');
+      expect(edge.targetExportedName).toBe('User');
+      expect(edge.targetDefId).toBe('def:b.User');
+    });
+
+    it('records namespace imports with origin=namespace in bindings', () => {
+      // Provider emits a synthetic module-representing def so the namespace
+      // binding can anchor to a real SymbolDefinition.
+      const numpyFile = file('numpy.py', [
+        def('def:numpy', 'Namespace', 'numpy'),
+        def('def:numpy.array', 'Function', 'numpy.array'),
+      ]);
+      const a = file('a', [], [namespace('np', 'numpy', 'numpy.py')]);
+      const files = [a, numpyFile];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const npEdge = firstImport(out, a.moduleScope)!;
+      expect(npEdge.kind).toBe('namespace');
+      expect(npEdge.targetModuleScope).toBe(numpyFile.moduleScope);
+
+      const bindings = bindingsFor(out, a.moduleScope, 'np');
+      expect(bindings.some((b) => b.origin === 'namespace')).toBe(true);
+      expect(bindings.find((b) => b.origin === 'namespace')!.def.nodeId).toBe('def:numpy');
+    });
+
+    it('links a namespace import to the module scope even when no module-def exists', () => {
+      // No synthetic def in target — the edge still resolves to the module
+      // scope, just without a `targetDefId`. Bindings materialization skips
+      // the binding (no def to anchor to), but the edge itself is linked.
+      const numpyFile = file('numpy.py', [def('def:numpy.array', 'Function', 'numpy.array')]);
+      const a = file('a', [], [namespace('np', 'numpy', 'numpy.py')]);
+      const files = [a, numpyFile];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const npEdge = firstImport(out, a.moduleScope)!;
+      expect(npEdge.kind).toBe('namespace');
+      expect(npEdge.linkStatus).toBeUndefined();
+      expect(npEdge.targetModuleScope).toBe(numpyFile.moduleScope);
+      expect(npEdge.targetDefId).toBeUndefined();
+    });
+  });
+
+  describe('module-scope binding materialization', () => {
+    it('lays down local defs with origin=local', () => {
+      const a = file('a', [def('def:a.X', 'Class', 'a.X')]);
+      const out = finalize({ files: [a], workspaceIndex: undefined }, defaultHooks([a]));
+      const bindings = bindingsFor(out, a.moduleScope, 'X');
+      expect(bindings.length).toBe(1);
+      expect(bindings[0]!.origin).toBe('local');
+      expect(bindings[0]!.def.nodeId).toBe('def:a.X');
+    });
+
+    it('layers imports on top of local defs via mergeBindings', () => {
+      const b = file('b', [def('def:b.User', 'Class', 'b.User')]);
+      const a = file('a', [def('def:a.User', 'Class', 'a.User')], [named('User', 'User', 'b')]);
+      const files = [a, b];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      const bindings = bindingsFor(out, a.moduleScope, 'User');
+      expect(bindings.length).toBe(2);
+      expect(bindings.some((br) => br.origin === 'local')).toBe(true);
+      expect(bindings.some((br) => br.origin === 'import')).toBe(true);
+    });
+
+    it('honors provider precedence: mergeBindings can drop existing bindings', () => {
+      // Provider decides imports win over locals (Python-ish precedence).
+      const b = file('b', [def('def:b.User', 'Class', 'b.User')]);
+      const a = file('a', [def('def:a.User', 'Class', 'a.User')], [named('User', 'User', 'b')]);
+      const files = [a, b];
+      const hooks: FinalizeHooks = {
+        ...defaultHooks(files),
+        mergeBindings(_existing, incoming) {
+          // Replace existing with incoming — last-write-wins across tiers.
+          return incoming;
+        },
+      };
+      const out = finalize({ files, workspaceIndex: undefined }, hooks);
+      const bindings = bindingsFor(out, a.moduleScope, 'User');
+      // Only the last merged layer (the import) remains.
+      expect(bindings.length).toBe(1);
+      expect(bindings[0]!.origin).toBe('import');
+    });
+  });
+
+  describe('SCC-DAG exposure for parallelism', () => {
+    it('returns SCCs in reverse-topological order (leaves first)', () => {
+      // c ← b ← a (a imports b, b imports c, c has no imports)
+      const c = file('c', [def('def:c.C', 'Class', 'c.C')]);
+      const b = file('b', [def('def:b.B', 'Class', 'b.B')], [named('C', 'C', 'c')]);
+      const a = file('a', [def('def:a.A', 'Class', 'a.A')], [named('B', 'B', 'b')]);
+      const files = [a, b, c];
+      const out = finalize({ files, workspaceIndex: undefined }, defaultHooks(files));
+      // First SCC processed must be `c` (leaf), last must be `a`.
+      expect(out.sccs[0]!.files[0]).toBe('c');
+      expect(out.sccs[out.sccs.length - 1]!.files[0]).toBe('a');
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/finalize-orchestrator.test.ts b/gitnexus/test/unit/scope-resolution/finalize-orchestrator.test.ts
new file mode 100644
index 000000000..f3d92f0f0
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/finalize-orchestrator.test.ts
@@ -0,0 +1,219 @@
+/**
+ * Unit tests for `finalize-orchestrator` (RFC #909 Ring 2 PKG #921).
+ *
+ * Covers empty-input, single-file, multi-file-with-imports, and the
+ * `MutableSemanticModel.attachScopeIndexes` one-shot contract.
+ *
+ * Builds synthetic `ParsedFile` inputs directly — the orchestrator is
+ * below the extraction layer and independent of tree-sitter, so the
+ * tests don't need a real parser.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+  BindingRef,
+  ParsedFile,
+  ParsedImport,
+  Scope,
+  ScopeId,
+  SymbolDefinition,
+} from 'gitnexus-shared';
+import { finalizeScopeModel } from '../../../src/core/ingestion/finalize-orchestrator.js';
+import { createSemanticModel } from '../../../src/core/ingestion/model/semantic-model.js';
+import type { ScopeResolutionIndexes } from '../../../src/core/ingestion/model/scope-resolution-indexes.js';
+
+// ─── Fixture helpers ────────────────────────────────────────────────────────
+
+const mkScope = (
+  id: ScopeId,
+  parent: ScopeId | null,
+  filePath: string,
+  bindings: Record<string, readonly BindingRef[]> = {},
+): Scope => ({
+  id,
+  parent,
+  kind: parent === null ? 'Module' : 'Class',
+  range: { startLine: 1, startCol: 0, endLine: 100, endCol: 0 },
+  filePath,
+  bindings: new Map(Object.entries(bindings)),
+  ownedDefs: [],
+  imports: [],
+  typeBindings: new Map(),
+});
+
+const mkFile = (filePath: string, overrides: Partial<ParsedFile> = {}): ParsedFile => ({
+  filePath,
+  moduleScope: `scope:${filePath}#module`,
+  scopes: overrides.scopes ?? [mkScope(`scope:${filePath}#module`, null, filePath)],
+  parsedImports: overrides.parsedImports ?? [],
+  localDefs: overrides.localDefs ?? [],
+  referenceSites: overrides.referenceSites ?? [],
+});
+
+const mkDef = (nodeId: string, filePath: string, qname: string): SymbolDefinition => ({
+  nodeId,
+  filePath,
+  type: 'Class',
+  qualifiedName: qname,
+});
+
+// ─── Empty input ───────────────────────────────────────────────────────────
+
+describe('finalizeScopeModel: empty input', () => {
+  it('produces a valid but empty bundle for zero parsedFiles', () => {
+    const out = finalizeScopeModel([]);
+    expect(out.scopeTree.size).toBe(0);
+    expect(out.defs.size).toBe(0);
+    expect(out.qualifiedNames.size).toBe(0);
+    expect(out.moduleScopes.size).toBe(0);
+    expect(out.methodDispatch.mroByOwnerDefId.size).toBe(0);
+    expect(out.imports.size).toBe(0);
+    expect(out.bindings.size).toBe(0);
+    expect(out.referenceSites).toEqual([]);
+    expect(out.sccs).toEqual([]);
+    expect(out.stats.totalFiles).toBe(0);
+    expect(out.stats.totalEdges).toBe(0);
+  });
+});
+
+// ─── Single file ───────────────────────────────────────────────────────────
+
+describe('finalizeScopeModel: single file', () => {
+  it('builds all per-file indexes from a single ParsedFile', () => {
+    const userClass = mkDef('def:User', 'models.ts', 'models.User');
+    const file = mkFile('models.ts', {
+      localDefs: [userClass],
+    });
+    const out = finalizeScopeModel([file]);
+
+    expect(out.scopeTree.size).toBe(1);
+    expect(out.defs.get('def:User')).toBe(userClass);
+    expect(out.qualifiedNames.get('models.User')).toEqual(['def:User']);
+    expect(out.moduleScopes.get('models.ts')).toBe(file.moduleScope);
+    expect(out.stats.totalFiles).toBe(1);
+  });
+
+  it('forwards per-file referenceSites into the aggregated list', () => {
+    const file = mkFile('a.ts', {
+      referenceSites: [
+        {
+          name: 'save',
+          atRange: { startLine: 5, startCol: 0, endLine: 5, endCol: 4 },
+          inScope: 'scope:a.ts#module',
+          kind: 'call',
+        },
+      ],
+    });
+    const out = finalizeScopeModel([file]);
+    expect(out.referenceSites).toHaveLength(1);
+    expect(out.referenceSites[0]!.name).toBe('save');
+  });
+});
+
+// ─── Multi-file with cross-file imports ────────────────────────────────────
+
+describe('finalizeScopeModel: cross-file imports', () => {
+  it('links a named import when the caller provides resolveImportTarget', () => {
+    const userClass = mkDef('def:User', 'models.ts', 'models.User');
+    const modelsFile = mkFile('models.ts', { localDefs: [userClass] });
+
+    const importOfUser: ParsedImport = {
+      kind: 'named',
+      localName: 'User',
+      importedName: 'User',
+      targetRaw: 'models.ts',
+    };
+    const appFile = mkFile('app.ts', { parsedImports: [importOfUser] });
+
+    const out = finalizeScopeModel([appFile, modelsFile], {
+      hooks: {
+        resolveImportTarget: (targetRaw) => (targetRaw === 'models.ts' ? 'models.ts' : null),
+      },
+    });
+
+    const appImports = out.imports.get(appFile.moduleScope) ?? [];
+    expect(appImports).toHaveLength(1);
+    expect(appImports[0]!.linkStatus).toBeUndefined();
+    expect(appImports[0]!.targetFile).toBe('models.ts');
+    expect(appImports[0]!.targetDefId).toBe('def:User');
+  });
+
+  it('leaves imports unresolved when no resolveImportTarget is supplied (default hook)', () => {
+    // Default `resolveImportTarget: () => null` — every import ends up
+    // with `linkStatus: 'unresolved'`. This is the zero-provider case
+    // today; behavior is well-defined, not a crash.
+    const importOfUser: ParsedImport = {
+      kind: 'named',
+      localName: 'User',
+      importedName: 'User',
+      targetRaw: 'models.ts',
+    };
+    const appFile = mkFile('app.ts', { parsedImports: [importOfUser] });
+
+    const out = finalizeScopeModel([appFile]);
+    const appImports = out.imports.get(appFile.moduleScope) ?? [];
+    expect(appImports).toHaveLength(1);
+    expect(appImports[0]!.linkStatus).toBe('unresolved');
+  });
+
+  it('surfaces FinalizeStats for observability', () => {
+    const userClass = mkDef('def:User', 'models.ts', 'models.User');
+    const modelsFile = mkFile('models.ts', { localDefs: [userClass] });
+    const appFile = mkFile('app.ts', {
+      parsedImports: [
+        {
+          kind: 'named',
+          localName: 'User',
+          importedName: 'User',
+          targetRaw: 'models.ts',
+        },
+      ],
+    });
+    const out = finalizeScopeModel([appFile, modelsFile], {
+      hooks: { resolveImportTarget: () => 'models.ts' },
+    });
+    expect(out.stats.totalFiles).toBe(2);
+    expect(out.stats.totalEdges).toBe(1);
+    expect(out.stats.linkedEdges).toBe(1);
+    expect(out.stats.unresolvedEdges).toBe(0);
+  });
+});
+
+// ─── Integration with MutableSemanticModel ─────────────────────────────────
+
+describe('MutableSemanticModel.attachScopeIndexes', () => {
+  it('starts as undefined and accepts a one-shot attach', () => {
+    const model = createSemanticModel();
+    expect(model.scopes).toBeUndefined();
+
+    const indexes = finalizeScopeModel([]);
+    model.attachScopeIndexes(indexes);
+
+    expect(model.scopes).toBe(indexes);
+    expect(model.scopes!.stats.totalFiles).toBe(0);
+  });
+
+  it('freezes the attached bundle (callers cannot mutate after attach)', () => {
+    const model = createSemanticModel();
+    const indexes: ScopeResolutionIndexes = finalizeScopeModel([]);
+    model.attachScopeIndexes(indexes);
+
+    expect(Object.isFrozen(model.scopes)).toBe(true);
+  });
+
+  it('throws on a second attach without clear()', () => {
+    const model = createSemanticModel();
+    model.attachScopeIndexes(finalizeScopeModel([]));
+    expect(() => model.attachScopeIndexes(finalizeScopeModel([]))).toThrowError(/already attached/);
+  });
+
+  it('clear() resets the bundle, enabling re-attach', () => {
+    const model = createSemanticModel();
+    model.attachScopeIndexes(finalizeScopeModel([]));
+    model.clear();
+    expect(model.scopes).toBeUndefined();
+    // Second attach now succeeds.
+    model.attachScopeIndexes(finalizeScopeModel([]));
+    expect(model.scopes).toBeDefined();
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/import-target-adapter.test.ts b/gitnexus/test/unit/scope-resolution/import-target-adapter.test.ts
new file mode 100644
index 000000000..8459fc4ba
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/import-target-adapter.test.ts
@@ -0,0 +1,152 @@
+/**
+ * Unit tests for `import-target-adapter` (RFC #909 Ring 2 PKG #922).
+ *
+ * Exercises the language-dispatching FinalizeHook. We don't need the
+ * real per-language resolvers here — mock `ImportResolverFn`s let each
+ * branch be tested in isolation. Real-resolver integration is covered
+ * by the existing per-language import-resolver test suites.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { SupportedLanguages } from 'gitnexus-shared';
+import {
+  buildImportTargetWorkspace,
+  resolveImportTargetAcrossLanguages,
+  type ImportTargetWorkspace,
+} from '../../../src/core/ingestion/import-target-adapter.js';
+import type {
+  ImportResolverFn,
+  ResolveCtx,
+} from '../../../src/core/ingestion/import-resolvers/types.js';
+import type { LanguageProvider } from '../../../src/core/ingestion/language-provider.js';
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+const emptyCtx: ResolveCtx = {
+  allFilePaths: new Set(),
+  allFileList: [],
+  normalizedFileList: [],
+  index: { bySuffix: new Map() } as unknown as ResolveCtx['index'],
+  resolveCache: new Map(),
+  configs: {
+    tsconfigPaths: null,
+    goModule: null,
+    composerConfig: null,
+    swiftPackageConfig: null,
+    csharpConfigs: [],
+  },
+};
+
+function fakeProvider(importResolver: ImportResolverFn | undefined): LanguageProvider {
+  return { importResolver } as unknown as LanguageProvider;
+}
+
+function workspace(
+  entries: Array<[SupportedLanguages, ImportResolverFn | undefined]>,
+): ImportTargetWorkspace {
+  const providers = new Map<SupportedLanguages, LanguageProvider>();
+  for (const [lang, resolver] of entries) providers.set(lang, fakeProvider(resolver));
+  return buildImportTargetWorkspace(providers, emptyCtx);
+}
+
+// ─── buildImportTargetWorkspace ────────────────────────────────────────────
+
+describe('buildImportTargetWorkspace', () => {
+  it('registers languages that expose an importResolver', () => {
+    const pyResolver: ImportResolverFn = () => ({ kind: 'files', files: ['resolved.py'] });
+    const ws = workspace([[SupportedLanguages.Python, pyResolver]]);
+    expect(ws.perLanguage.has(SupportedLanguages.Python)).toBe(true);
+  });
+
+  it("skips providers whose importResolver is absent (defensive — shouldn't happen in practice)", () => {
+    const ws = workspace([[SupportedLanguages.Python, undefined]]);
+    expect(ws.perLanguage.size).toBe(0);
+  });
+
+  it('threads the shared ResolveCtx into every entry', () => {
+    const pyResolver: ImportResolverFn = () => ({ kind: 'files', files: ['x.py'] });
+    const tsResolver: ImportResolverFn = () => ({ kind: 'files', files: ['x.ts'] });
+    const ws = workspace([
+      [SupportedLanguages.Python, pyResolver],
+      [SupportedLanguages.TypeScript, tsResolver],
+    ]);
+    expect(ws.perLanguage.get(SupportedLanguages.Python)!.ctx).toBe(emptyCtx);
+    expect(ws.perLanguage.get(SupportedLanguages.TypeScript)!.ctx).toBe(emptyCtx);
+  });
+});
+
+// ─── resolveImportTargetAcrossLanguages ────────────────────────────────────
+
+describe('resolveImportTargetAcrossLanguages', () => {
+  it('dispatches to the resolver for the fromFile extension', () => {
+    let seenPath: string | undefined;
+    const pyResolver: ImportResolverFn = (raw, _file) => {
+      seenPath = raw;
+      return { kind: 'files', files: ['models/user.py'] };
+    };
+    const ws = workspace([[SupportedLanguages.Python, pyResolver]]);
+    const result = resolveImportTargetAcrossLanguages('models.user', 'src/app.py', ws);
+    expect(seenPath).toBe('models.user');
+    expect(result).toBe('models/user.py');
+  });
+
+  it('routes to different resolvers based on the fromFile extension', () => {
+    const pyResolver: ImportResolverFn = () => ({ kind: 'files', files: ['resolved.py'] });
+    const tsResolver: ImportResolverFn = () => ({ kind: 'files', files: ['resolved.ts'] });
+    const ws = workspace([
+      [SupportedLanguages.Python, pyResolver],
+      [SupportedLanguages.TypeScript, tsResolver],
+    ]);
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', ws)).toBe('resolved.py');
+    expect(resolveImportTargetAcrossLanguages('x', 'a.ts', ws)).toBe('resolved.ts');
+  });
+
+  it('returns null when the resolver returns null', () => {
+    const pyResolver: ImportResolverFn = () => null;
+    const ws = workspace([[SupportedLanguages.Python, pyResolver]]);
+    expect(resolveImportTargetAcrossLanguages('external_pkg', 'app.py', ws)).toBeNull();
+  });
+
+  it('takes the first file from a package-kind result', () => {
+    const resolver: ImportResolverFn = () => ({
+      kind: 'package',
+      files: ['pkg/index.py', 'pkg/other.py'],
+      dirSuffix: 'pkg',
+    });
+    const ws = workspace([[SupportedLanguages.Python, resolver]]);
+    expect(resolveImportTargetAcrossLanguages('pkg', 'app.py', ws)).toBe('pkg/index.py');
+  });
+
+  it('returns null when a result has kind=files but an empty files[]', () => {
+    // Defensive: resolvers shouldn't return this shape, but tolerate it.
+    const resolver: ImportResolverFn = () => ({ kind: 'files', files: [] });
+    const ws = workspace([[SupportedLanguages.Python, resolver]]);
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', ws)).toBeNull();
+  });
+
+  it('returns null when no resolver is registered for the language', () => {
+    const ws = workspace([]); // empty
+    // .py file but no Python resolver registered
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', ws)).toBeNull();
+  });
+
+  it('returns null when fromFile has an unknown extension', () => {
+    const pyResolver: ImportResolverFn = () => ({ kind: 'files', files: ['resolved.py'] });
+    const ws = workspace([[SupportedLanguages.Python, pyResolver]]);
+    expect(resolveImportTargetAcrossLanguages('x', 'README.xyz', ws)).toBeNull();
+  });
+
+  it('returns null when workspaceIndex is undefined / malformed', () => {
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', undefined)).toBeNull();
+    // Cast to exercise the runtime guard against caller misuse.
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', {} as unknown)).toBeNull();
+  });
+
+  it('swallows resolver exceptions and returns null (treated upstream as unresolved)', () => {
+    const throwingResolver: ImportResolverFn = () => {
+      throw new Error('resolver boom');
+    };
+    const ws = workspace([[SupportedLanguages.Python, throwingResolver]]);
+    expect(resolveImportTargetAcrossLanguages('x', 'a.py', ws)).toBeNull();
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/method-dispatch-index.test.ts b/gitnexus/test/unit/scope-resolution/method-dispatch-index.test.ts
new file mode 100644
index 000000000..386474723
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/method-dispatch-index.test.ts
@@ -0,0 +1,235 @@
+/**
+ * Unit tests for `buildMethodDispatchIndex` / `MethodDispatchIndex`
+ * (RFC #909 Ring 2 SHARED #914).
+ *
+ * Covers: empty input, single-inheritance chain, diamond inheritance (caller-
+ * determined MRO order), interface-only dispatch, multiple implementors,
+ * dedup, first-write-wins, C3 vs BFS strategy parity (both honored verbatim),
+ * readonly surface + frozen output.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildMethodDispatchIndex, type MethodDispatchInput, type DefId } from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const input = (
+  owners: readonly DefId[],
+  mroByOwner: Record<DefId, readonly DefId[]>,
+  implementsByOwner: Record<DefId, readonly DefId[]> = {},
+): MethodDispatchInput => ({
+  owners,
+  computeMro: (owner) => mroByOwner[owner] ?? [],
+  implementsOf: (owner) => implementsByOwner[owner] ?? [],
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('buildMethodDispatchIndex', () => {
+  describe('empty / degenerate inputs', () => {
+    it('builds an empty index from no owners', () => {
+      const idx = buildMethodDispatchIndex(input([], {}));
+      expect(idx.mroByOwnerDefId.size).toBe(0);
+      expect(idx.implsByInterfaceDefId.size).toBe(0);
+      expect(idx.mroFor('anything')).toEqual([]);
+      expect(idx.implementorsOf('anything')).toEqual([]);
+    });
+
+    it('indexes an owner with no parents and no interfaces', () => {
+      const idx = buildMethodDispatchIndex(input(['def:A'], { 'def:A': [] }));
+      expect(idx.mroByOwnerDefId.size).toBe(1);
+      expect(idx.implsByInterfaceDefId.size).toBe(0);
+      expect(idx.mroFor('def:A')).toEqual([]);
+    });
+  });
+
+  describe('MRO materialization (single / multi inheritance)', () => {
+    it('records a single-inheritance chain verbatim from the callback', () => {
+      // A extends B extends C
+      const idx = buildMethodDispatchIndex(
+        input(['def:A', 'def:B', 'def:C'], {
+          'def:A': ['def:B', 'def:C'],
+          'def:B': ['def:C'],
+          'def:C': [],
+        }),
+      );
+      expect(idx.mroFor('def:A')).toEqual(['def:B', 'def:C']);
+      expect(idx.mroFor('def:B')).toEqual(['def:C']);
+      expect(idx.mroFor('def:C')).toEqual([]);
+    });
+
+    it('records a C3 linearization verbatim (Python diamond)', () => {
+      // D(B, C) where B(A), C(A). Classical C3 keeps A last because the
+      // merge step defers A until both B and C have been emitted.
+      // Our index stores MRO excluding self: [B, C, A].
+      const idx = buildMethodDispatchIndex(
+        input(['def:D'], { 'def:D': ['def:B', 'def:C', 'def:A'] }),
+      );
+      expect(idx.mroFor('def:D')).toEqual(['def:B', 'def:C', 'def:A']);
+    });
+
+    it('records a BFS linearization verbatim (Java-style first-wins)', () => {
+      // Same class hierarchy as the C3 case, but the BFS walker visits
+      // A before C via the B→A edge. Expected MRO differs from C3: [B, A, C].
+      // This test proves the materializer preserves whatever ordering the
+      // per-language `computeMro` callback produces — NOT that C3 and BFS
+      // produce identical output.
+      const idx = buildMethodDispatchIndex(
+        input(['def:D'], { 'def:D': ['def:B', 'def:A', 'def:C'] }),
+      );
+      expect(idx.mroFor('def:D')).toEqual(['def:B', 'def:A', 'def:C']);
+    });
+
+    it('records a Ruby-style kind-aware ancestry verbatim', () => {
+      // class C prepend P1 prepend P2; include M1 include M2
+      // ruby-mixin walk order (per callback): [P2, P1, M2, M1]
+      const idx = buildMethodDispatchIndex(
+        input(['def:C'], { 'def:C': ['def:P2', 'def:P1', 'def:M2', 'def:M1'] }),
+      );
+      expect(idx.mroFor('def:C')).toEqual(['def:P2', 'def:P1', 'def:M2', 'def:M1']);
+    });
+
+    it('records an empty chain for Rust qualified-syntax owners', () => {
+      // Rust: no auto-MRO; callback returns []
+      const idx = buildMethodDispatchIndex(input(['def:RustStruct'], { 'def:RustStruct': [] }));
+      expect(idx.mroFor('def:RustStruct')).toEqual([]);
+    });
+  });
+
+  describe('implements inversion', () => {
+    it('inverts a single class → interface mapping', () => {
+      const idx = buildMethodDispatchIndex(
+        input(['def:Impl'], { 'def:Impl': [] }, { 'def:Impl': ['def:IFace'] }),
+      );
+      expect(idx.implementorsOf('def:IFace')).toEqual(['def:Impl']);
+    });
+
+    it('aggregates multiple classes implementing the same interface', () => {
+      const idx = buildMethodDispatchIndex(
+        input(
+          ['def:A', 'def:B', 'def:C'],
+          { 'def:A': [], 'def:B': [], 'def:C': [] },
+          { 'def:A': ['def:I'], 'def:B': ['def:I'], 'def:C': ['def:J'] },
+        ),
+      );
+      expect(idx.implementorsOf('def:I')).toEqual(['def:A', 'def:B']);
+      expect(idx.implementorsOf('def:J')).toEqual(['def:C']);
+    });
+
+    it('preserves iteration order of owners in each implementors bucket', () => {
+      const idx = buildMethodDispatchIndex(
+        input(
+          ['def:Z', 'def:Y', 'def:X'],
+          { 'def:Z': [], 'def:Y': [], 'def:X': [] },
+          { 'def:Z': ['def:I'], 'def:Y': ['def:I'], 'def:X': ['def:I'] },
+        ),
+      );
+      expect(idx.implementorsOf('def:I')).toEqual(['def:Z', 'def:Y', 'def:X']);
+    });
+
+    it('deduplicates repeated (interface, owner) pairs within a single callback call', () => {
+      // Caller may legally return the same interface twice (e.g., a class that
+      // both `implements IFace` and inherits from a parent that also does).
+      const idx = buildMethodDispatchIndex(
+        input(['def:Impl'], { 'def:Impl': [] }, { 'def:Impl': ['def:I', 'def:I', 'def:I'] }),
+      );
+      expect(idx.implementorsOf('def:I')).toEqual(['def:Impl']);
+    });
+
+    it('deduplicates when the same owner is listed in `owners` twice (first-write-wins)', () => {
+      // First-write-wins parity with sibling indexes; subsequent owner entries
+      // should not re-invoke `computeMro` for existing MRO, and should not
+      // create duplicate implementor entries.
+      //
+      // NOTE on `implementsOf` call count: the builder calls `implementsOf`
+      // ONCE PER OCCURRENCE of an owner in `input.owners`, not once per
+      // unique owner. Duplicate owners therefore re-invoke `implementsOf`;
+      // the dedup lives at the bucket layer (via `implsSeen`), not the
+      // callback layer. Callers with expensive `implementsOf` callbacks
+      // should dedupe `input.owners` upfront. This counter assertion pins
+      // that contract so a future refactor can't silently collapse the
+      // second call without updating the docstring.
+      let mroCalls = 0;
+      let implementsOfCalls = 0;
+      const impls: Record<DefId, readonly DefId[]> = { 'def:A': ['def:I'] };
+      const idx = buildMethodDispatchIndex({
+        owners: ['def:A', 'def:A'],
+        computeMro: (_) => {
+          mroCalls++;
+          return ['def:B'];
+        },
+        implementsOf: (o) => {
+          implementsOfCalls++;
+          return impls[o] ?? [];
+        },
+      });
+      expect(mroCalls).toBe(1); // MRO dedup is at the callback layer (first-write-wins)
+      expect(implementsOfCalls).toBe(2); // implementsOf fires per occurrence; dedup at bucket
+      expect(idx.mroFor('def:A')).toEqual(['def:B']);
+      expect(idx.implementorsOf('def:I')).toEqual(['def:A']);
+    });
+  });
+
+  describe('lookup miss / safety surface', () => {
+    it('returns a frozen empty array on MRO miss', () => {
+      const idx = buildMethodDispatchIndex(input(['def:A'], { 'def:A': [] }));
+      const miss = idx.mroFor('def:Missing');
+      expect(miss).toEqual([]);
+      expect(() => (miss as unknown as DefId[]).push('x')).toThrow();
+    });
+
+    it('returns a frozen empty array on implementors miss', () => {
+      const idx = buildMethodDispatchIndex(input(['def:A'], { 'def:A': [] }));
+      const miss = idx.implementorsOf('def:Missing');
+      expect(miss).toEqual([]);
+      expect(() => (miss as unknown as DefId[]).push('x')).toThrow();
+    });
+
+    it('freezes stored MRO arrays (readonly surface)', () => {
+      const idx = buildMethodDispatchIndex(input(['def:A'], { 'def:A': ['def:B'] }));
+      const chain = idx.mroFor('def:A');
+      expect(() => (chain as unknown as DefId[]).push('x')).toThrow();
+    });
+
+    it('freezes stored implementors arrays (readonly surface)', () => {
+      const idx = buildMethodDispatchIndex(
+        input(['def:A'], { 'def:A': [] }, { 'def:A': ['def:I'] }),
+      );
+      const impls = idx.implementorsOf('def:I');
+      expect(() => (impls as unknown as DefId[]).push('x')).toThrow();
+    });
+
+    it('isolates stored MRO from later mutation of the callback-returned array', () => {
+      const mutable = ['def:B', 'def:C'];
+      const idx = buildMethodDispatchIndex({
+        owners: ['def:A'],
+        computeMro: () => mutable,
+        implementsOf: () => [],
+      });
+      mutable.push('def:D');
+      expect(idx.mroFor('def:A')).toEqual(['def:B', 'def:C']);
+    });
+  });
+
+  describe('readonly surface', () => {
+    it('exposes `mroByOwnerDefId` as a read-only Map for direct iteration', () => {
+      const idx = buildMethodDispatchIndex(
+        input(['def:A', 'def:B'], { 'def:A': [], 'def:B': ['def:A'] }),
+      );
+      const owners = Array.from(idx.mroByOwnerDefId.keys()).sort();
+      expect(owners).toEqual(['def:A', 'def:B']);
+    });
+
+    it('exposes `implsByInterfaceDefId` as a read-only Map for direct iteration', () => {
+      const idx = buildMethodDispatchIndex(
+        input(
+          ['def:A', 'def:B'],
+          { 'def:A': [], 'def:B': [] },
+          { 'def:A': ['def:I'], 'def:B': ['def:J'] },
+        ),
+      );
+      const keys = Array.from(idx.implsByInterfaceDefId.keys()).sort();
+      expect(keys).toEqual(['def:I', 'def:J']);
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/module-scope-index.test.ts b/gitnexus/test/unit/scope-resolution/module-scope-index.test.ts
new file mode 100644
index 000000000..08bc29ac1
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/module-scope-index.test.ts
@@ -0,0 +1,62 @@
+/**
+ * Unit tests for `buildModuleScopeIndex` / `ModuleScopeIndex`
+ * (RFC #909 Ring 2 SHARED #913).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildModuleScopeIndex, type ModuleScopeEntry, type ScopeId } from 'gitnexus-shared';
+
+const entry = (filePath: string, moduleScopeId: ScopeId): ModuleScopeEntry => ({
+  filePath,
+  moduleScopeId,
+});
+
+describe('buildModuleScopeIndex', () => {
+  it('builds an empty index from no entries', () => {
+    const idx = buildModuleScopeIndex([]);
+    expect(idx.size).toBe(0);
+    expect(idx.get('src/app.ts')).toBeUndefined();
+    expect(idx.has('src/app.ts')).toBe(false);
+  });
+
+  it('round-trips a single entry', () => {
+    const idx = buildModuleScopeIndex([entry('src/app.ts', 'scope:src/app.ts#1:0-100:0:Module')]);
+    expect(idx.size).toBe(1);
+    expect(idx.has('src/app.ts')).toBe(true);
+    expect(idx.get('src/app.ts')).toBe('scope:src/app.ts#1:0-100:0:Module');
+  });
+
+  it('stores distinct files under their own scopes', () => {
+    const entries: ModuleScopeEntry[] = [
+      entry('src/a.ts', 'scope:a'),
+      entry('src/b.ts', 'scope:b'),
+      entry('src/c.ts', 'scope:c'),
+    ];
+    const idx = buildModuleScopeIndex(entries);
+    expect(idx.size).toBe(3);
+    expect(idx.get('src/a.ts')).toBe('scope:a');
+    expect(idx.get('src/b.ts')).toBe('scope:b');
+    expect(idx.get('src/c.ts')).toBe('scope:c');
+  });
+
+  it('first-write-wins when the same filePath appears twice', () => {
+    const idx = buildModuleScopeIndex([
+      entry('src/app.ts', 'scope:first'),
+      entry('src/app.ts', 'scope:second'),
+    ]);
+    expect(idx.size).toBe(1);
+    expect(idx.get('src/app.ts')).toBe('scope:first');
+  });
+
+  it('returns undefined for a missing filePath (no throw)', () => {
+    const idx = buildModuleScopeIndex([entry('src/a.ts', 'scope:a')]);
+    expect(idx.get('src/missing.ts')).toBeUndefined();
+    expect(idx.has('src/missing.ts')).toBe(false);
+  });
+
+  it('exposes byFilePath as the underlying read-only Map', () => {
+    const idx = buildModuleScopeIndex([entry('src/a.ts', 'scope:a'), entry('src/b.ts', 'scope:b')]);
+    const paths = Array.from(idx.byFilePath.keys()).sort();
+    expect(paths).toEqual(['src/a.ts', 'src/b.ts']);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/parse-worker-scope-integration.test.ts b/gitnexus/test/unit/scope-resolution/parse-worker-scope-integration.test.ts
new file mode 100644
index 000000000..5d6959298
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/parse-worker-scope-integration.test.ts
@@ -0,0 +1,166 @@
+/**
+ * Unit tests for `extractParsedFile` — the parse-worker → ScopeExtractor
+ * bridge (RFC #909 Ring 2 PKG #920).
+ *
+ * The goal is to pin three invariants:
+ *
+ *   1. When a provider does NOT implement `emitScopeCaptures`, the helper
+ *      returns `undefined` silently. This is the state of every language
+ *      today — `ParseWorkerResult.parsedFiles` stays empty and the legacy
+ *      DAG continues unaffected.
+ *   2. When a provider DOES implement the hook, the helper threads its
+ *      output through `ScopeExtractor.extract` and returns a `ParsedFile`.
+ *   3. Exceptions from either the hook or the extractor are caught
+ *      locally. The helper returns `undefined` — scope-extraction
+ *      failures must NEVER break legacy parsing on the same file.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import { extractParsedFile } from '../../../src/core/ingestion/scope-extractor-bridge.js';
+import type { LanguageProvider } from '../../../src/core/ingestion/language-provider.js';
+
+// ─── Capture helpers ────────────────────────────────────────────────────────
+
+const cap = (
+  name: string,
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+  text = '',
+): Capture => ({ name, range: { startLine, startCol, endLine, endCol }, text });
+
+const moduleScopeMatch = (): CaptureMatch => ({
+  '@scope.module': cap('@scope.module', 1, 0, 100, 0),
+});
+
+/**
+ * Build a `LanguageProvider` whose shape is only as narrow as
+ * `extractParsedFile` reads. Tests cast to the full provider type since
+ * `extractParsedFile` is typed against `LanguageProvider` (not the narrow
+ * `ScopeExtractorHooks`); the real worker always has a full provider.
+ */
+function fakeProvider(
+  hooks: Partial<
+    Pick<LanguageProvider, 'emitScopeCaptures' | 'shouldCreateScope' | 'resolveScopeKind'>
+  >,
+): LanguageProvider {
+  return hooks as unknown as LanguageProvider;
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('extractParsedFile', () => {
+  describe('provider has NOT migrated (no emitScopeCaptures)', () => {
+    it('returns undefined — silent no-op for legacy languages', () => {
+      const provider = fakeProvider({}); // no hook
+      const result = extractParsedFile(provider, 'source text', 'src/file.ts');
+      expect(result).toBeUndefined();
+    });
+
+    it('never calls the scope extractor when the hook is absent — cannot throw', () => {
+      // If the extractor was wrongly invoked, it would complain about the
+      // missing Module scope for empty captures. This test proves the
+      // short-circuit actually fires.
+      const provider = fakeProvider({});
+      expect(() => extractParsedFile(provider, '', 'x.ts')).not.toThrow();
+    });
+  });
+
+  describe('provider HAS migrated', () => {
+    it('threads emitScopeCaptures output through ScopeExtractor', () => {
+      const provider = fakeProvider({
+        emitScopeCaptures: () => [moduleScopeMatch()],
+      });
+      const result = extractParsedFile(provider, 'source text', 'src/file.ts');
+      expect(result).toBeDefined();
+      expect(result!.filePath).toBe('src/file.ts');
+      expect(result!.scopes).toHaveLength(1);
+      expect(result!.scopes[0]!.kind).toBe('Module');
+    });
+
+    it('forwards the correct arguments to emitScopeCaptures', () => {
+      let seenText: string | undefined;
+      let seenPath: string | undefined;
+      const provider = fakeProvider({
+        emitScopeCaptures: (text, path) => {
+          seenText = text;
+          seenPath = path;
+          return [moduleScopeMatch()];
+        },
+      });
+      extractParsedFile(provider, 'the real text', 'deep/path/file.ts');
+      expect(seenText).toBe('the real text');
+      expect(seenPath).toBe('deep/path/file.ts');
+    });
+
+    it('honors provider hooks beyond emitScopeCaptures (shouldCreateScope)', () => {
+      // A Block scope the provider declines to create — the resulting
+      // ParsedFile should have only the Module scope, not the Block.
+      const provider = fakeProvider({
+        emitScopeCaptures: () => [
+          moduleScopeMatch(),
+          { '@scope.block': cap('@scope.block', 10, 0, 20, 0) },
+        ],
+        shouldCreateScope: (match) => match['@scope.block'] === undefined,
+      });
+      const result = extractParsedFile(provider, 'src', 'a.ts');
+      expect(result!.scopes).toHaveLength(1);
+      expect(result!.scopes[0]!.kind).toBe('Module');
+    });
+  });
+
+  describe('error resilience — never breaks legacy parsing', () => {
+    it('returns undefined when emitScopeCaptures throws', () => {
+      const provider = fakeProvider({
+        emitScopeCaptures: () => {
+          throw new Error('provider boom');
+        },
+      });
+      const result = extractParsedFile(provider, 'src', 'a.ts');
+      expect(result).toBeUndefined();
+    });
+
+    it('routes errors through the onWarn callback when provided', () => {
+      const warnings: string[] = [];
+      const provider = fakeProvider({
+        emitScopeCaptures: () => {
+          throw new Error('provider boom');
+        },
+      });
+      const result = extractParsedFile(provider, 'src', 'path/to/file.ts', (msg) => {
+        warnings.push(msg);
+      });
+      expect(result).toBeUndefined();
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0]).toContain('path/to/file.ts');
+      expect(warnings[0]).toContain('provider boom');
+    });
+
+    it('returns undefined when ScopeExtractor throws (missing Module scope)', () => {
+      // Emits a Class scope but no Module — extractor throws; helper
+      // swallows and returns undefined. Legacy parsing on the same file
+      // continues unaffected by this failure.
+      const provider = fakeProvider({
+        emitScopeCaptures: () => [{ '@scope.class': cap('@scope.class', 5, 0, 10, 0) }],
+      });
+      const result = extractParsedFile(provider, 'src', 'a.ts');
+      expect(result).toBeUndefined();
+    });
+
+    it('returns undefined when ScopeExtractor throws on malformed captures (overlap)', () => {
+      // Siblings with overlapping ranges trip the ScopeTreeInvariantError
+      // from #912. The helper catches it and returns undefined.
+      const provider = fakeProvider({
+        emitScopeCaptures: () => [
+          moduleScopeMatch(),
+          { '@scope.function': cap('@scope.function', 10, 0, 20, 0) },
+          { '@scope.function': cap('@scope.function', 15, 0, 25, 0) }, // overlap
+        ],
+      });
+      const result = extractParsedFile(provider, 'src', 'a.ts');
+      expect(result).toBeUndefined();
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/position-index.test.ts b/gitnexus/test/unit/scope-resolution/position-index.test.ts
new file mode 100644
index 000000000..ae037e4b2
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/position-index.test.ts
@@ -0,0 +1,209 @@
+/**
+ * Unit tests for `buildPositionIndex` / `PositionIndex`
+ * (RFC #909 Ring 2 SHARED #912).
+ *
+ * Covers: empty input, single scope, nested scopes (innermost-wins),
+ * positions before/after all scopes, boundary positions (inclusive ends),
+ * multi-file isolation, and duplicate-scope-id dedup.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildPositionIndex,
+  type Range,
+  type Scope,
+  type ScopeId,
+  type ScopeKind,
+} from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const r = (startLine: number, startCol: number, endLine: number, endCol: number): Range => ({
+  startLine,
+  startCol,
+  endLine,
+  endCol,
+});
+
+const mkScope = (
+  id: ScopeId,
+  filePath: string,
+  kind: ScopeKind,
+  range: Range,
+  parent: ScopeId | null = null,
+): Scope => ({
+  id,
+  parent,
+  kind,
+  range,
+  filePath,
+  bindings: new Map(),
+  ownedDefs: [],
+  imports: [],
+  typeBindings: new Map(),
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('buildPositionIndex', () => {
+  describe('empty / missing', () => {
+    it('returns undefined for any query on an empty index', () => {
+      const idx = buildPositionIndex([]);
+      expect(idx.size).toBe(0);
+      expect(idx.atPosition('src/any.ts', 1, 0)).toBeUndefined();
+    });
+
+    it('returns undefined for unindexed filePaths', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(1, 0, 10, 0))]);
+      expect(idx.atPosition('b.ts', 5, 0)).toBeUndefined();
+    });
+
+    it('returns undefined for positions before any scope in the file', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(5, 0, 10, 0))]);
+      expect(idx.atPosition('a.ts', 1, 0)).toBeUndefined();
+      expect(idx.atPosition('a.ts', 4, 99)).toBeUndefined();
+    });
+
+    it('returns undefined for positions after all scopes in the file', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(1, 0, 10, 5))]);
+      expect(idx.atPosition('a.ts', 11, 0)).toBeUndefined();
+      expect(idx.atPosition('a.ts', 10, 6)).toBeUndefined();
+    });
+  });
+
+  describe('single scope lookup', () => {
+    it('returns the scope id for a point inside its range', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(1, 0, 10, 0))]);
+      expect(idx.atPosition('a.ts', 5, 4)).toBe('scope:m');
+    });
+
+    it('includes the start boundary', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(5, 2, 10, 0))]);
+      expect(idx.atPosition('a.ts', 5, 2)).toBe('scope:m');
+      expect(idx.atPosition('a.ts', 5, 1)).toBeUndefined();
+    });
+
+    it('includes the end boundary', () => {
+      const idx = buildPositionIndex([mkScope('scope:m', 'a.ts', 'Module', r(1, 0, 10, 5))]);
+      expect(idx.atPosition('a.ts', 10, 5)).toBe('scope:m');
+      expect(idx.atPosition('a.ts', 10, 6)).toBeUndefined();
+    });
+  });
+
+  describe('innermost-containing wins', () => {
+    it('picks the innermost of nested scopes', () => {
+      // Module[1..100] ⊃ Class[5..80] ⊃ Function[10..60] ⊃ Block[20..50]
+      const idx = buildPositionIndex([
+        mkScope('scope:mod', 'a.ts', 'Module', r(1, 0, 100, 0)),
+        mkScope('scope:cls', 'a.ts', 'Class', r(5, 0, 80, 0), 'scope:mod'),
+        mkScope('scope:fn', 'a.ts', 'Function', r(10, 0, 60, 0), 'scope:cls'),
+        mkScope('scope:blk', 'a.ts', 'Block', r(20, 0, 50, 0), 'scope:fn'),
+      ]);
+      expect(idx.atPosition('a.ts', 30, 0)).toBe('scope:blk'); // deepest
+      expect(idx.atPosition('a.ts', 15, 0)).toBe('scope:fn'); // inside fn, outside blk
+      expect(idx.atPosition('a.ts', 7, 0)).toBe('scope:cls'); // inside class body only
+      expect(idx.atPosition('a.ts', 2, 0)).toBe('scope:mod'); // module top
+    });
+
+    it('innermost wins when two scopes start at the same position', () => {
+      // Two scopes both start at line 5 col 0; outer ends at 50, inner at 20.
+      const idx = buildPositionIndex([
+        mkScope('scope:outer', 'a.ts', 'Module', r(5, 0, 50, 0)),
+        mkScope('scope:inner', 'a.ts', 'Function', r(5, 0, 20, 0), 'scope:outer'),
+      ]);
+      expect(idx.atPosition('a.ts', 10, 0)).toBe('scope:inner'); // both contain; inner wins
+      expect(idx.atPosition('a.ts', 30, 0)).toBe('scope:outer'); // only outer contains
+    });
+
+    it('innermost wins when scopes share an end position but differ in start', () => {
+      const idx = buildPositionIndex([
+        mkScope('scope:outer', 'a.ts', 'Module', r(1, 0, 50, 0)),
+        mkScope('scope:inner', 'a.ts', 'Function', r(30, 0, 50, 0), 'scope:outer'),
+      ]);
+      expect(idx.atPosition('a.ts', 40, 0)).toBe('scope:inner');
+      expect(idx.atPosition('a.ts', 20, 0)).toBe('scope:outer');
+    });
+
+    it('returns the sibling whose range contains the query, not the other', () => {
+      // Two non-overlapping siblings under the same parent.
+      const idx = buildPositionIndex([
+        mkScope('scope:mod', 'a.ts', 'Module', r(1, 0, 100, 0)),
+        mkScope('scope:a', 'a.ts', 'Function', r(5, 0, 20, 0), 'scope:mod'),
+        mkScope('scope:b', 'a.ts', 'Function', r(25, 0, 40, 0), 'scope:mod'),
+      ]);
+      expect(idx.atPosition('a.ts', 10, 0)).toBe('scope:a');
+      expect(idx.atPosition('a.ts', 30, 0)).toBe('scope:b');
+      expect(idx.atPosition('a.ts', 22, 0)).toBe('scope:mod'); // gap between siblings
+    });
+
+    it('returns the right (later-start) sibling when two siblings share a boundary point', () => {
+      // Legal touching-boundary scenario per ScopeTree's non-overlap rule:
+      // [5:0..10:0] and [10:0..15:0] meet at (10, 0) but do not overlap
+      // (rangesOverlap treats end == start as "touches, not overlaps").
+      // A query AT the shared point is contained by BOTH siblings; the
+      // innermost-wins comparator breaks the tie by start position ASC:
+      // the right sibling (starts at 10:0) is scanned first during the
+      // backward pass and wins. See `atPosition` JSDoc.
+      const idx = buildPositionIndex([
+        mkScope('scope:mod', 'a.ts', 'Module', r(1, 0, 100, 0)),
+        mkScope('scope:left', 'a.ts', 'Block', r(5, 0, 10, 0), 'scope:mod'),
+        mkScope('scope:right', 'a.ts', 'Block', r(10, 0, 15, 0), 'scope:mod'),
+      ]);
+      expect(idx.atPosition('a.ts', 10, 0)).toBe('scope:right'); // shared boundary
+      expect(idx.atPosition('a.ts', 7, 0)).toBe('scope:left'); // inside left only
+      expect(idx.atPosition('a.ts', 12, 0)).toBe('scope:right'); // inside right only
+    });
+  });
+
+  describe('multi-file isolation', () => {
+    it('indexes each filePath independently — no cross-file hits', () => {
+      const idx = buildPositionIndex([
+        mkScope('scope:a-mod', 'a.ts', 'Module', r(1, 0, 50, 0)),
+        mkScope('scope:b-mod', 'b.ts', 'Module', r(1, 0, 50, 0)),
+      ]);
+      expect(idx.atPosition('a.ts', 10, 0)).toBe('scope:a-mod');
+      expect(idx.atPosition('b.ts', 10, 0)).toBe('scope:b-mod');
+    });
+
+    it('counts all indexed scopes in `size`', () => {
+      const idx = buildPositionIndex([
+        mkScope('scope:a-mod', 'a.ts', 'Module', r(1, 0, 50, 0)),
+        mkScope('scope:a-fn', 'a.ts', 'Function', r(10, 0, 20, 0), 'scope:a-mod'),
+        mkScope('scope:b-mod', 'b.ts', 'Module', r(1, 0, 50, 0)),
+      ]);
+      expect(idx.size).toBe(3);
+    });
+  });
+
+  describe('column handling on the same line', () => {
+    it('handles a single-line scope across columns', () => {
+      const idx = buildPositionIndex([
+        mkScope('scope:expr', 'a.ts', 'Expression', r(5, 10, 5, 20)),
+      ]);
+      expect(idx.atPosition('a.ts', 5, 10)).toBe('scope:expr'); // start inclusive
+      expect(idx.atPosition('a.ts', 5, 15)).toBe('scope:expr'); // middle
+      expect(idx.atPosition('a.ts', 5, 20)).toBe('scope:expr'); // end inclusive
+      expect(idx.atPosition('a.ts', 5, 9)).toBeUndefined();
+      expect(idx.atPosition('a.ts', 5, 21)).toBeUndefined();
+    });
+
+    it('handles nested scopes on the same line', () => {
+      const idx = buildPositionIndex([
+        mkScope('scope:outer', 'a.ts', 'Expression', r(5, 0, 5, 30)),
+        mkScope('scope:inner', 'a.ts', 'Expression', r(5, 10, 5, 20), 'scope:outer'),
+      ]);
+      expect(idx.atPosition('a.ts', 5, 15)).toBe('scope:inner');
+      expect(idx.atPosition('a.ts', 5, 5)).toBe('scope:outer');
+      expect(idx.atPosition('a.ts', 5, 25)).toBe('scope:outer');
+    });
+  });
+
+  describe('robustness', () => {
+    it('deduplicates scopes with the same id', () => {
+      const s = mkScope('scope:dup', 'a.ts', 'Module', r(1, 0, 10, 0));
+      const idx = buildPositionIndex([s, s, s]);
+      expect(idx.size).toBe(1);
+      expect(idx.atPosition('a.ts', 5, 0)).toBe('scope:dup');
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/qualified-name-index.test.ts b/gitnexus/test/unit/scope-resolution/qualified-name-index.test.ts
new file mode 100644
index 000000000..a9cbced57
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/qualified-name-index.test.ts
@@ -0,0 +1,125 @@
+/**
+ * Unit tests for `buildQualifiedNameIndex` / `QualifiedNameIndex`
+ * (RFC #909 Ring 2 SHARED #913).
+ *
+ * Covers: per-kind accumulation, multi-def-per-qname (partial classes /
+ * overloads), skipping defs without a qualifiedName, duplicate-pair dedup,
+ * and empty-bucket iteration guarantee.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildQualifiedNameIndex, type SymbolDefinition } from 'gitnexus-shared';
+
+const makeDef = (overrides: Partial<SymbolDefinition> = {}): SymbolDefinition => ({
+  nodeId: 'def:test',
+  filePath: 'src/test.ts',
+  type: 'Class',
+  ...overrides,
+});
+
+describe('buildQualifiedNameIndex', () => {
+  it('builds an empty index from no defs', () => {
+    const idx = buildQualifiedNameIndex([]);
+    expect(idx.size).toBe(0);
+    expect(idx.get('anything')).toEqual([]);
+    expect(idx.has('anything')).toBe(false);
+  });
+
+  it('indexes a single qualified-named def', () => {
+    const def = makeDef({ nodeId: 'def:app.User', qualifiedName: 'app.User' });
+    const idx = buildQualifiedNameIndex([def]);
+    expect(idx.size).toBe(1);
+    expect(idx.has('app.User')).toBe(true);
+    expect(idx.get('app.User')).toEqual(['def:app.User']);
+  });
+
+  it('accumulates distinct DefIds under the same qualified name (partial classes)', () => {
+    // C# partial classes: same qname, different files/nodeIds
+    const a = makeDef({
+      nodeId: 'def:app.User:Core',
+      qualifiedName: 'app.User',
+      filePath: 'src/User.Core.cs',
+    });
+    const b = makeDef({
+      nodeId: 'def:app.User:Api',
+      qualifiedName: 'app.User',
+      filePath: 'src/User.Api.cs',
+    });
+    const idx = buildQualifiedNameIndex([a, b]);
+    expect(idx.get('app.User')).toEqual(['def:app.User:Core', 'def:app.User:Api']);
+    // Hit-path bucket is frozen just like the miss path — consumers cannot
+    // mutate the returned array.
+    expect(() => (idx.get('app.User') as unknown as string[]).push('x')).toThrow();
+  });
+
+  it('preserves input order in the bucket', () => {
+    const a = makeDef({ nodeId: 'def:a', qualifiedName: 'app.Foo' });
+    const b = makeDef({ nodeId: 'def:b', qualifiedName: 'app.Foo' });
+    const c = makeDef({ nodeId: 'def:c', qualifiedName: 'app.Foo' });
+    const idx = buildQualifiedNameIndex([c, a, b]);
+    expect(idx.get('app.Foo')).toEqual(['def:c', 'def:a', 'def:b']);
+  });
+
+  it('separates defs that share a simple name but differ in qualifiedName', () => {
+    const appUser = makeDef({ nodeId: 'def:app.User', qualifiedName: 'app.User' });
+    const adminUser = makeDef({ nodeId: 'def:admin.User', qualifiedName: 'admin.User' });
+    const idx = buildQualifiedNameIndex([appUser, adminUser]);
+    expect(idx.get('app.User')).toEqual(['def:app.User']);
+    expect(idx.get('admin.User')).toEqual(['def:admin.User']);
+  });
+
+  it('skips defs that have no qualifiedName', () => {
+    const qnamed = makeDef({ nodeId: 'def:app.Foo', qualifiedName: 'app.Foo' });
+    const anon = makeDef({ nodeId: 'def:anon', qualifiedName: undefined });
+    const idx = buildQualifiedNameIndex([qnamed, anon]);
+    expect(idx.size).toBe(1);
+    expect(idx.get('app.Foo')).toEqual(['def:app.Foo']);
+    expect(idx.has('')).toBe(false);
+  });
+
+  it('skips defs with an empty-string qualifiedName', () => {
+    const empty = makeDef({ nodeId: 'def:empty', qualifiedName: '' });
+    const idx = buildQualifiedNameIndex([empty]);
+    expect(idx.size).toBe(0);
+    expect(idx.has('')).toBe(false);
+  });
+
+  it('deduplicates exact (qname, DefId) pairs when the same def appears twice in input', () => {
+    const def = makeDef({ nodeId: 'def:app.Foo', qualifiedName: 'app.Foo' });
+    const idx = buildQualifiedNameIndex([def, def]);
+    expect(idx.get('app.Foo')).toEqual(['def:app.Foo']); // not duplicated
+  });
+
+  it('indexes across heterogeneous kinds (Class + Method + Field may share qname convention)', () => {
+    const klass = makeDef({
+      nodeId: 'def:class:app.User',
+      type: 'Class',
+      qualifiedName: 'app.User',
+    });
+    const method = makeDef({
+      nodeId: 'def:method:app.User.save',
+      type: 'Method',
+      qualifiedName: 'app.User.save',
+    });
+    const idx = buildQualifiedNameIndex([klass, method]);
+    expect(idx.size).toBe(2);
+    expect(idx.get('app.User')).toEqual(['def:class:app.User']);
+    expect(idx.get('app.User.save')).toEqual(['def:method:app.User.save']);
+  });
+
+  it('returns a frozen empty array (not undefined) for misses so callers can iterate safely', () => {
+    const idx = buildQualifiedNameIndex([makeDef({ qualifiedName: 'app.Foo' })]);
+    const miss = idx.get('app.Missing');
+    expect(miss).toEqual([]);
+    expect(() => (miss as unknown as string[]).push('x')).toThrow();
+  });
+
+  it('exposes byQualifiedName as a read-only Map for direct iteration', () => {
+    const idx = buildQualifiedNameIndex([
+      makeDef({ nodeId: 'def:A', qualifiedName: 'app.A' }),
+      makeDef({ nodeId: 'def:B', qualifiedName: 'app.B' }),
+    ]);
+    const names = Array.from(idx.byQualifiedName.keys()).sort();
+    expect(names).toEqual(['app.A', 'app.B']);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/registries.test.ts b/gitnexus/test/unit/scope-resolution/registries.test.ts
new file mode 100644
index 000000000..b204287b5
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/registries.test.ts
@@ -0,0 +1,746 @@
+/**
+ * Unit tests for the scope-aware registries (RFC §4; Ring 2 SHARED #917).
+ *
+ * Tests are organized per RFC §4.2 step so a regression localizes to the
+ * step it broke:
+ *
+ *   §4.2 Step 1 — lexical scope-chain walk + shadowing
+ *   §4.2 Step 2 — type-binding / MRO walk (method/field registries)
+ *   §4.2 Step 3 — owner-scoped contributor
+ *   §4.2 Step 4 — kind filter + kind-match evidence
+ *   §4.2 Step 5 — arity filter
+ *   §4.2 Step 6 — global-qualified fallback
+ *   §4.2 Step 7 — rank + tie-break cascade
+ *   §4.5       — lookupQualified helper
+ *   §4.7       — invariants
+ *
+ * Corroborators (owner-match, unresolved-import cap, dynamic-unresolved)
+ * get their own sections.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildClassRegistry,
+  buildFieldRegistry,
+  buildMethodRegistry,
+  buildDefIndex,
+  buildMethodDispatchIndex,
+  buildModuleScopeIndex,
+  buildQualifiedNameIndex,
+  buildScopeTree,
+  lookupCore,
+  lookupQualified,
+  EvidenceWeights,
+  type BindingRef,
+  type ImportEdge,
+  type Range,
+  type RegistryContext,
+  type Resolution,
+  type Scope,
+  type ScopeId,
+  type ScopeKind,
+  type SymbolDefinition,
+  type TypeRef,
+} from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const r = (startLine: number, startCol: number, endLine: number, endCol: number): Range => ({
+  startLine,
+  startCol,
+  endLine,
+  endCol,
+});
+
+const mkDef = (overrides: Partial<SymbolDefinition> & { nodeId: string }): SymbolDefinition => ({
+  nodeId: overrides.nodeId,
+  filePath: overrides.filePath ?? 'x.ts',
+  type: overrides.type ?? 'Class',
+  ...overrides,
+});
+
+const mkBinding = (
+  def: SymbolDefinition,
+  origin: BindingRef['origin'],
+  via?: ImportEdge,
+): BindingRef => ({ def, origin, ...(via !== undefined ? { via } : {}) });
+
+interface ScopeSpec {
+  id: ScopeId;
+  parent: ScopeId | null;
+  kind?: ScopeKind;
+  range?: Range;
+  filePath?: string;
+  bindings?: Record<string, readonly BindingRef[]>;
+  ownedDefs?: readonly SymbolDefinition[];
+  typeBindings?: Record<string, TypeRef>;
+}
+
+const mkScope = (s: ScopeSpec): Scope => ({
+  id: s.id,
+  parent: s.parent,
+  kind: s.kind ?? 'Module',
+  range: s.range ?? r(1, 0, 1000, 0),
+  filePath: s.filePath ?? 'x.ts',
+  bindings: new Map(Object.entries(s.bindings ?? {})),
+  ownedDefs: s.ownedDefs ?? [],
+  imports: [],
+  typeBindings: new Map(Object.entries(s.typeBindings ?? {})),
+});
+
+const typeRef = (rawName: string, declaredAtScope: ScopeId): TypeRef => ({
+  rawName,
+  declaredAtScope,
+  source: 'parameter-annotation',
+});
+
+function makeCtx(
+  scopes: Scope[],
+  defs: SymbolDefinition[],
+  opts: {
+    mro?: Record<string, readonly string[]>;
+    implsByInterface?: Record<string, readonly string[]>;
+    arity?: (
+      callsite: { arity: number },
+      def: SymbolDefinition,
+    ) => 'compatible' | 'unknown' | 'incompatible';
+  } = {},
+): RegistryContext {
+  const defIndex = buildDefIndex(defs);
+  const qualifiedNameIndex = buildQualifiedNameIndex(defs);
+  const moduleScopes = buildModuleScopeIndex(
+    scopes
+      .filter((s) => s.kind === 'Module')
+      .map((s) => ({ filePath: s.filePath, moduleScopeId: s.id })),
+  );
+  const owners = Array.from(new Set(defs.map((d) => d.nodeId)));
+  const methodDispatch = buildMethodDispatchIndex({
+    owners,
+    computeMro: (owner) => opts.mro?.[owner] ?? [],
+    implementsOf: (owner) => {
+      const out: string[] = [];
+      for (const [iface, impls] of Object.entries(opts.implsByInterface ?? {})) {
+        if (impls.includes(owner)) out.push(iface);
+      }
+      return out;
+    },
+  });
+  return {
+    scopes: buildScopeTree(scopes),
+    defs: defIndex,
+    qualifiedNames: qualifiedNameIndex,
+    moduleScopes,
+    methodDispatch,
+    providers: opts.arity !== undefined ? { arityCompatibility: opts.arity } : {},
+  };
+}
+
+const evidenceOfKind = (res: Resolution, kind: string) => res.evidence.find((e) => e.kind === kind);
+
+// ─── §4.2 Step 1 — lexical scope-chain walk + shadowing ────────────────────
+
+describe('Step 1: lexical scope-chain walk', () => {
+  it('finds a class declared at the start scope with origin=local', () => {
+    const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(userClass, 'local')] },
+    });
+    const ctx = makeCtx([mod], [userClass]);
+    const registry = buildClassRegistry(ctx);
+    const results = registry.lookup('User', 'scope:m');
+
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(userClass);
+    expect(evidenceOfKind(results[0]!, 'local')?.weight).toBe(EvidenceWeights.local);
+  });
+
+  it('walks parent scopes when the name is not bound at the start scope', () => {
+    const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(userClass, 'import')] },
+    });
+    const fn = mkScope({
+      id: 'scope:f',
+      parent: 'scope:m',
+      kind: 'Function',
+      range: r(2, 0, 10, 0),
+    });
+    const ctx = makeCtx([mod, fn], [userClass]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:f');
+
+    expect(results[0]!.def).toBe(userClass);
+    const scopeChain = evidenceOfKind(results[0]!, 'scope-chain');
+    expect(scopeChain?.weight).toBe(EvidenceWeights.scopeChainPerDepth * 1);
+  });
+
+  it('enforces hard shadow: outer bindings are ignored once a name is bound at an inner scope', () => {
+    const outerClass = mkDef({ nodeId: 'def:outer', type: 'Class' });
+    const innerVar = mkDef({ nodeId: 'def:inner', type: 'Variable' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(outerClass, 'local')] },
+    });
+    const fn = mkScope({
+      id: 'scope:f',
+      parent: 'scope:m',
+      kind: 'Function',
+      range: r(2, 0, 10, 0),
+      bindings: { User: [mkBinding(innerVar, 'local')] },
+    });
+    const ctx = makeCtx([mod, fn], [outerClass, innerVar]);
+
+    // Inner binding is a Variable (not a Class) → class registry returns empty.
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:f');
+    expect(results).toEqual([]);
+  });
+
+  it('emits origin=import evidence when the binding is imported', () => {
+    const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(userClass, 'import')] },
+    });
+    const ctx = makeCtx([mod], [userClass]);
+    const res = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    expect(evidenceOfKind(res[0]!, 'import')?.weight).toBe(EvidenceWeights.import);
+  });
+});
+
+// ─── §4.2 Step 5 — arity filter ────────────────────────────────────────────
+
+describe('Step 5: arity filter', () => {
+  it('drops incompatible candidates when at least one compatible candidate exists', () => {
+    const save2 = mkDef({
+      nodeId: 'def:save-two',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      parameterCount: 2,
+    });
+    const save1 = mkDef({
+      nodeId: 'def:save-one',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      parameterCount: 1,
+    });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { save: [mkBinding(save2, 'local'), mkBinding(save1, 'local')] },
+    });
+    const ctx = makeCtx([mod], [save2, save1], {
+      arity: (callsite, def) => {
+        const count = def.parameterCount ?? 0;
+        if (count === callsite.arity) return 'compatible';
+        return 'incompatible';
+      },
+    });
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', {
+      callsite: { arity: 1 },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def.nodeId).toBe('def:save-one');
+    expect(evidenceOfKind(results[0]!, 'arity-match')?.weight).toBe(
+      EvidenceWeights.arityMatchCompatible,
+    );
+  });
+
+  it('keeps incompatible candidates when no compatible candidate exists (soft penalty)', () => {
+    const save3 = mkDef({
+      nodeId: 'def:save-three',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      parameterCount: 3,
+    });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { save: [mkBinding(save3, 'local')] },
+    });
+    const ctx = makeCtx([mod], [save3], {
+      arity: () => 'incompatible',
+    });
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', {
+      callsite: { arity: 1 },
+    });
+    expect(results).toHaveLength(1);
+    expect(evidenceOfKind(results[0]!, 'arity-match')?.weight).toBe(
+      EvidenceWeights.arityMatchIncompatible,
+    );
+  });
+
+  it('records arity=unknown when the provider is missing (neutral signal)', () => {
+    const m = mkDef({ nodeId: 'def:m', type: 'Method', qualifiedName: 'C.m' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { m: [mkBinding(m, 'local')] },
+    });
+    const ctx = makeCtx([mod], [m]); // no arity provider
+    const results = buildMethodRegistry(ctx).lookup('m', 'scope:m', {
+      callsite: { arity: 7 },
+    });
+    expect(evidenceOfKind(results[0]!, 'arity-match')?.weight).toBe(
+      EvidenceWeights.arityMatchUnknown,
+    );
+  });
+});
+
+// ─── §4.2 Step 6 — global-qualified fallback ───────────────────────────────
+
+describe('Step 6: global-qualified fallback', () => {
+  it('falls back to the qualified-name index when no lexical candidate is found', () => {
+    const cls = mkDef({ nodeId: 'def:app.User', qualifiedName: 'app.User', type: 'Class' });
+    const mod = mkScope({ id: 'scope:m', parent: null }); // no lexical binding
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('app.User', 'scope:m');
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(cls);
+    expect(evidenceOfKind(results[0]!, 'global-qualified')?.weight).toBe(
+      EvidenceWeights.globalQualified,
+    );
+  });
+
+  it('does NOT consult the global index when a lexical hit exists (shadowing)', () => {
+    const localCls = mkDef({ nodeId: 'def:local', type: 'Class' });
+    const globalCls = mkDef({
+      nodeId: 'def:global',
+      qualifiedName: 'other.User',
+      type: 'Class',
+    });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(localCls, 'local')] },
+    });
+    const ctx = makeCtx([mod], [localCls, globalCls]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(localCls);
+  });
+
+  it('does NOT apply the global fallback for non-dotted names', () => {
+    const cls = mkDef({ nodeId: 'def:x', qualifiedName: 'User', type: 'Class' });
+    const mod = mkScope({ id: 'scope:m', parent: null });
+    const ctx = makeCtx([mod], [cls]);
+    // 'User' has no dot → no qname fallback.
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    expect(results).toEqual([]);
+  });
+});
+
+// ─── §4.2 Step 7 — tie-breaks ──────────────────────────────────────────────
+
+describe('Step 7: tie-break cascade', () => {
+  it('inner scope shadows outer, yielding single result (hard-shadow baseline)', () => {
+    // Baseline: the hard-shadow rule in Step 1 means a near binding fully
+    // replaces the far one. No "confidence DESC" ordering to observe here
+    // because there is only one candidate — the far class never enters
+    // the result set. See the next test for true multi-candidate ranking.
+    const nearClass = mkDef({ nodeId: 'def:near', type: 'Class' });
+    const farClass = mkDef({ nodeId: 'def:far', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(farClass, 'local')] },
+    });
+    const fn = mkScope({
+      id: 'scope:f',
+      parent: 'scope:m',
+      kind: 'Function',
+      range: r(2, 0, 10, 0),
+      bindings: { User: [mkBinding(nearClass, 'local')] },
+    });
+    const ctx = makeCtx([mod, fn], [nearClass, farClass]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:f');
+
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(nearClass);
+  });
+
+  it('orders multiple same-scope candidates by confidence DESC', () => {
+    // Two candidates co-exist at the same scope, one with origin=local
+    // (weight 0.55) and one with origin=wildcard (weight 0.30). Both pass
+    // the Class kind filter; confidence DESC should sort local first.
+    const localClass = mkDef({ nodeId: 'def:local', type: 'Class' });
+    const wildcardClass = mkDef({ nodeId: 'def:wildcard', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: {
+        User: [mkBinding(wildcardClass, 'wildcard'), mkBinding(localClass, 'local')],
+      },
+    });
+    const ctx = makeCtx([mod], [localClass, wildcardClass]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    expect(results).toHaveLength(2);
+    expect(results[0]!.def).toBe(localClass); // local (0.55) > wildcard (0.30)
+    expect(results[1]!.def).toBe(wildcardClass);
+    expect(results[0]!.confidence).toBeGreaterThan(results[1]!.confidence);
+  });
+
+  it('breaks ties by DefId.localeCompare when all secondary keys are equal', () => {
+    const a = mkDef({ nodeId: 'def:aaa', type: 'Class' });
+    const b = mkDef({ nodeId: 'def:bbb', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(b, 'local'), mkBinding(a, 'local')] }, // reversed
+    });
+    const ctx = makeCtx([mod], [a, b]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    expect(results[0]!.def.nodeId).toBe('def:aaa');
+    expect(results[1]!.def.nodeId).toBe('def:bbb');
+  });
+});
+
+// ─── Corroborators: unresolved-import cap (per-signal) ─────────────────────
+
+describe('unresolved-import cap (per-signal)', () => {
+  it('halves the import evidence weight when via.linkStatus is unresolved', () => {
+    const cls = mkDef({ nodeId: 'def:User', type: 'Class' });
+    const unresolvedEdge: ImportEdge = {
+      localName: 'User',
+      targetFile: null,
+      targetExportedName: 'User',
+      kind: 'named',
+      linkStatus: 'unresolved',
+    };
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { User: [mkBinding(cls, 'import', unresolvedEdge)] },
+    });
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('User', 'scope:m');
+    const importEv = evidenceOfKind(results[0]!, 'import');
+    expect(importEv?.weight).toBe(
+      EvidenceWeights.import * EvidenceWeights.unlinkedImportMultiplier,
+    );
+  });
+
+  it('leaves arity & owner-match signals unaffected by the unresolved-import cap', () => {
+    const m = mkDef({
+      nodeId: 'def:m',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      parameterCount: 1,
+    });
+    const unresolved: ImportEdge = {
+      localName: 'save',
+      targetFile: null,
+      targetExportedName: 'save',
+      kind: 'named',
+      linkStatus: 'unresolved',
+    };
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { save: [mkBinding(m, 'import', unresolved)] },
+    });
+    const ctx = makeCtx([mod], [m], {
+      arity: () => 'compatible',
+    });
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', {
+      callsite: { arity: 1 },
+    });
+    expect(evidenceOfKind(results[0]!, 'arity-match')?.weight).toBe(
+      EvidenceWeights.arityMatchCompatible,
+    );
+  });
+});
+
+// ─── Corroborators: dynamic-unresolved degraded signal ─────────────────────
+
+describe('dynamic-unresolved passthrough', () => {
+  it('emits a degraded dynamic-import-unresolved signal for dynamic edges', () => {
+    const cls = mkDef({ nodeId: 'def:X', type: 'Class' });
+    const dynEdge: ImportEdge = {
+      localName: 'X',
+      targetFile: null,
+      targetExportedName: '',
+      kind: 'dynamic-unresolved',
+    };
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { X: [mkBinding(cls, 'import', dynEdge)] },
+    });
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('X', 'scope:m');
+    expect(evidenceOfKind(results[0]!, 'dynamic-import-unresolved')?.weight).toBe(
+      EvidenceWeights.dynamicImportUnresolved,
+    );
+  });
+});
+
+// ─── lookupQualified helper (§4.5) ─────────────────────────────────────────
+
+describe('lookupQualified (§4.5)', () => {
+  it('filters by acceptedKinds', () => {
+    const cls = mkDef({ nodeId: 'def:c', qualifiedName: 'app.User', type: 'Class' });
+    const fn = mkDef({ nodeId: 'def:f', qualifiedName: 'app.User', type: 'Function' });
+    const ctx = makeCtx([mkScope({ id: 'scope:m', parent: null })], [cls, fn]);
+    const results = lookupQualified('app.User', { acceptedKinds: ['Class'] }, ctx);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(cls);
+  });
+
+  it('returns empty for unknown qualified names', () => {
+    const ctx = makeCtx([mkScope({ id: 'scope:m', parent: null })], []);
+    expect(lookupQualified('app.Ghost', { acceptedKinds: ['Class'] }, ctx)).toEqual([]);
+  });
+
+  it('orders multiple partial-class defs deterministically by defId', () => {
+    const a = mkDef({ nodeId: 'def:aaa', qualifiedName: 'app.User', type: 'Class' });
+    const b = mkDef({ nodeId: 'def:bbb', qualifiedName: 'app.User', type: 'Class' });
+    const ctx = makeCtx([mkScope({ id: 'scope:m', parent: null })], [b, a]);
+    const results = lookupQualified('app.User', { acceptedKinds: ['Class'] }, ctx);
+    expect(results.map((r) => r.def.nodeId)).toEqual(['def:aaa', 'def:bbb']);
+  });
+});
+
+// ─── lookupCore with owner-scoped contributor (Step 3) ─────────────────────
+
+describe('Step 3: owner-scoped contributor', () => {
+  it('merges contributor hits as origin=local at the receiver scope', () => {
+    const userClass = mkDef({ nodeId: 'def:User', type: 'Class', qualifiedName: 'User' });
+    const saveMethod = mkDef({
+      nodeId: 'def:User.save',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      ownerId: 'def:User',
+    });
+    const mod = mkScope({ id: 'scope:m', parent: null });
+    const ctx = makeCtx([mod], [userClass, saveMethod]);
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', {
+      ownerScopedContributor: {
+        ownerDefId: 'def:User',
+        byName: (n) => (n === 'save' ? [saveMethod] : []),
+      },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(saveMethod);
+    expect(evidenceOfKind(results[0]!, 'local')?.weight).toBe(EvidenceWeights.local);
+    expect(evidenceOfKind(results[0]!, 'owner-match')?.weight).toBe(EvidenceWeights.ownerMatch);
+  });
+});
+
+// ─── Step 2: type-binding / MRO walk ───────────────────────────────────────
+
+describe('Step 2: type-binding + MRO walk', () => {
+  it('emits type-binding evidence with MRO-depth-decayed weight (explicit receiver)', () => {
+    const userClass = mkDef({ nodeId: 'def:User', type: 'Class', qualifiedName: 'User' });
+    const saveMethod = mkDef({
+      nodeId: 'def:User.save',
+      type: 'Method',
+      qualifiedName: 'User.save',
+      ownerId: 'def:User',
+    });
+    const callScope = mkScope({
+      id: 'scope:call',
+      parent: null,
+      typeBindings: { user: typeRef('User', 'scope:call') },
+    });
+    const ctx = makeCtx([callScope], [userClass, saveMethod]);
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:call', {
+      explicitReceiver: { name: 'user' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(saveMethod);
+    const typeBinding = evidenceOfKind(results[0]!, 'type-binding');
+    expect(typeBinding?.weight).toBe(EvidenceWeights.typeBindingByMroDepth[0]);
+  });
+
+  it('demotes Step-2-only candidates to tieBreakKey.origin=import (pins rank vs same-origin siblings)', () => {
+    // Two method defs named `impl`, both owned by the same interface and
+    // both reached ONLY via the Step 2 type-binding MRO walk (no lexical
+    // binding). Each candidate's `recordTypeBindingHit` path demotes its
+    // `tieBreakKey.origin` from the `ensureCandidate` default `'local'`
+    // to `'import'`. With both at equal confidence (owner-match + type-
+    // binding at depth 0), the tie-break cascade must fall through
+    // scope-depth / MRO-depth / origin (all equal) to DefId.localeCompare.
+    //
+    // If the demotion regressed (e.g., tieBreakKey.origin left as `'local'`),
+    // both candidates would still share the same origin and this test would
+    // pass by coincidence — so the test ALSO asserts `signals.origin` is
+    // absent from the evidence list (no false where-found weight emitted),
+    // which is the strongest observable invariant the demotion guarantees.
+    const iface = mkDef({
+      nodeId: 'def:Iface',
+      type: 'Interface',
+      qualifiedName: 'Iface',
+    });
+    const implA = mkDef({
+      nodeId: 'def:aaa.impl',
+      type: 'Method',
+      qualifiedName: 'Iface.impl',
+      ownerId: 'def:Iface',
+    });
+    const implB = mkDef({
+      nodeId: 'def:bbb.impl',
+      type: 'Method',
+      qualifiedName: 'Iface.impl',
+      ownerId: 'def:Iface',
+    });
+    const scope = mkScope({
+      id: 'scope:call',
+      parent: null,
+      typeBindings: { x: typeRef('Iface', 'scope:call') },
+    });
+    const ctx = makeCtx([scope], [iface, implA, implB]);
+    const results = buildMethodRegistry(ctx).lookup('impl', 'scope:call', {
+      explicitReceiver: { name: 'x' },
+    });
+    expect(results).toHaveLength(2);
+    // DefId.localeCompare: 'def:aaa.impl' < 'def:bbb.impl'.
+    expect(results[0]!.def).toBe(implA);
+    expect(results[1]!.def).toBe(implB);
+    // Demotion invariant: Step-2-only candidates have no `signals.origin`,
+    // so composeEvidence never emits a where-found signal for them.
+    for (const res of results) {
+      expect(evidenceOfKind(res, 'local')).toBeUndefined();
+      expect(evidenceOfKind(res, 'import')).toBeUndefined();
+      expect(evidenceOfKind(res, 'type-binding')).toBeDefined();
+    }
+  });
+
+  it('walks up the MRO when the method is declared on an ancestor', () => {
+    const baseClass = mkDef({ nodeId: 'def:Base', type: 'Class', qualifiedName: 'Base' });
+    const derivedClass = mkDef({ nodeId: 'def:Derived', type: 'Class', qualifiedName: 'Derived' });
+    const saveOnBase = mkDef({
+      nodeId: 'def:Base.save',
+      type: 'Method',
+      qualifiedName: 'Base.save',
+      ownerId: 'def:Base',
+    });
+    const callScope = mkScope({
+      id: 'scope:call',
+      parent: null,
+      typeBindings: { d: typeRef('Derived', 'scope:call') },
+    });
+    const ctx = makeCtx([callScope], [baseClass, derivedClass, saveOnBase], {
+      mro: { 'def:Derived': ['def:Base'] },
+    });
+    const results = buildMethodRegistry(ctx).lookup('save', 'scope:call', {
+      explicitReceiver: { name: 'd' },
+    });
+    expect(results).toHaveLength(1);
+    expect(results[0]!.def).toBe(saveOnBase);
+    // MRO depth for Base when receiver is Derived = 1.
+    expect(evidenceOfKind(results[0]!, 'type-binding')?.weight).toBe(
+      EvidenceWeights.typeBindingByMroDepth[1],
+    );
+  });
+});
+
+// ─── §4.7 invariants ──────────────────────────────────────────────────────
+
+describe('§4.7 invariants', () => {
+  it('Resolution has confidence per-candidate (not per-tier)', () => {
+    const cls = mkDef({ nodeId: 'def:c', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { X: [mkBinding(cls, 'local')] },
+    });
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('X', 'scope:m');
+    expect(typeof results[0]!.confidence).toBe('number');
+    expect(results[0]!.confidence).toBeGreaterThan(0);
+    expect(results[0]!.confidence).toBeLessThanOrEqual(1);
+  });
+
+  it('Resolution confidence is capped at 1.0', () => {
+    const cls = mkDef({ nodeId: 'def:c', type: 'Class' });
+    const dummyVia: ImportEdge = {
+      localName: 'X',
+      targetFile: 't.ts',
+      targetExportedName: 'X',
+      kind: 'named',
+    };
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      // Same def bound via multiple origins — evidence may stack.
+      bindings: { X: [mkBinding(cls, 'local', dummyVia)] },
+    });
+    const ctx = makeCtx([mod], [cls], { arity: () => 'compatible' });
+    const results = buildClassRegistry(ctx).lookup('X', 'scope:m');
+    expect(results[0]!.confidence).toBeLessThanOrEqual(1);
+  });
+
+  it('kind-match evidence is always present (weight 0) for debuggability', () => {
+    const cls = mkDef({ nodeId: 'def:c', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { X: [mkBinding(cls, 'local')] },
+    });
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('X', 'scope:m');
+    expect(evidenceOfKind(results[0]!, 'kind-match')).toBeDefined();
+    expect(evidenceOfKind(results[0]!, 'kind-match')!.weight).toBe(0);
+  });
+
+  it('caller can read [0] for one-shot answers', () => {
+    const cls = mkDef({ nodeId: 'def:c', type: 'Class' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { X: [mkBinding(cls, 'local')] },
+    });
+    const ctx = makeCtx([mod], [cls]);
+    const results = buildClassRegistry(ctx).lookup('X', 'scope:m');
+    expect(results[0]!.def).toBe(cls);
+  });
+});
+
+// ─── Misses ───────────────────────────────────────────────────────────────
+
+describe('misses', () => {
+  it('returns empty for an unknown name with no lexical or global hit', () => {
+    const mod = mkScope({ id: 'scope:m', parent: null });
+    const ctx = makeCtx([mod], []);
+    expect(buildClassRegistry(ctx).lookup('Ghost', 'scope:m')).toEqual([]);
+  });
+
+  it('filters out candidates whose kind is not in acceptedKinds', () => {
+    const method = mkDef({ nodeId: 'def:m', type: 'Method' });
+    const mod = mkScope({
+      id: 'scope:m',
+      parent: null,
+      bindings: { save: [mkBinding(method, 'local')] },
+    });
+    const ctx = makeCtx([mod], [method]);
+    // ClassRegistry excludes Method kind → empty.
+    expect(buildClassRegistry(ctx).lookup('save', 'scope:m')).toEqual([]);
+    // FieldRegistry also excludes Method → empty.
+    expect(buildFieldRegistry(ctx).lookup('save', 'scope:m')).toEqual([]);
+  });
+});
+
+// ─── lookupCore direct invocation ─────────────────────────────────────────
+
+describe('lookupCore direct invocation', () => {
+  it('accepts an empty params surface and returns empty for an unknown name', () => {
+    const mod = mkScope({ id: 'scope:m', parent: null });
+    const ctx = makeCtx([mod], []);
+    const results = lookupCore(
+      'Ghost',
+      'scope:m',
+      {
+        acceptedKinds: ['Class'],
+        useReceiverTypeBinding: false,
+        ownerScopedContributor: null,
+      },
+      ctx,
+    );
+    expect(results).toEqual([]);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/resolve-type-ref.test.ts b/gitnexus/test/unit/scope-resolution/resolve-type-ref.test.ts
new file mode 100644
index 000000000..3b7573d53
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/resolve-type-ref.test.ts
@@ -0,0 +1,318 @@
+/**
+ * Unit tests for `resolveTypeRef` (RFC #909 Ring 2 SHARED #916).
+ *
+ * Covers: local type, parameter/return annotation via scope walk, aliased
+ * import, re-exported type, shadowing by local variable, wildcard-origin
+ * ignored, qualified-name fallback (unique + ambiguous), broken scope chain,
+ * cycle guard.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  resolveTypeRef,
+  buildDefIndex,
+  buildQualifiedNameIndex,
+  type ResolveTypeRefContext,
+  type ScopeLookup,
+  type BindingRef,
+  type ImportEdge,
+  type Scope,
+  type ScopeId,
+  type SymbolDefinition,
+  type TypeRef,
+} from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const mkDef = (overrides: Partial<SymbolDefinition> & { nodeId: string }): SymbolDefinition => ({
+  nodeId: overrides.nodeId,
+  filePath: overrides.filePath ?? 'src/test.ts',
+  type: overrides.type ?? 'Class',
+  ...overrides,
+});
+
+const mkBinding = (
+  def: SymbolDefinition,
+  origin: BindingRef['origin'],
+  via?: ImportEdge,
+): BindingRef => ({ def, origin, ...(via !== undefined ? { via } : {}) });
+
+const mkScope = (
+  id: ScopeId,
+  parent: ScopeId | null,
+  bindings: Record<string, BindingRef[]> = {},
+  filePath = 'src/test.ts',
+): Scope => ({
+  id,
+  parent,
+  kind: 'Module',
+  range: { startLine: 1, startCol: 0, endLine: 100, endCol: 0 },
+  filePath,
+  bindings: new Map(Object.entries(bindings)),
+  ownedDefs: [],
+  imports: [],
+  typeBindings: new Map(),
+});
+
+const mkLookup = (scopes: Scope[]): ScopeLookup => {
+  const byId = new Map(scopes.map((s) => [s.id, s]));
+  return { getScope: (id) => byId.get(id) };
+};
+
+const mkCtx = (scopes: Scope[], defs: SymbolDefinition[]): ResolveTypeRefContext => ({
+  scopes: mkLookup(scopes),
+  defIndex: buildDefIndex(defs),
+  qualifiedNameIndex: buildQualifiedNameIndex(defs),
+});
+
+const typeRef = (
+  rawName: string,
+  declaredAtScope: ScopeId,
+  source: TypeRef['source'] = 'parameter-annotation',
+): TypeRef => ({ rawName, declaredAtScope, source });
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe('resolveTypeRef', () => {
+  describe('scope-chain walk', () => {
+    it('resolves a local type defined in the same scope', () => {
+      const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(userClass, 'local')],
+      });
+      const ctx = mkCtx([moduleScope], [userClass]);
+      const result = resolveTypeRef(typeRef('User', 'scope:module'), ctx);
+      expect(result).toBe(userClass);
+    });
+
+    it('walks parent scopes when the name is not bound locally (return-annotation case)', () => {
+      const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(userClass, 'local')],
+      });
+      const functionScope = mkScope('scope:fn', 'scope:module');
+      const ctx = mkCtx([moduleScope, functionScope], [userClass]);
+      const result = resolveTypeRef(typeRef('User', 'scope:fn', 'return-annotation'), ctx);
+      expect(result).toBe(userClass);
+    });
+
+    it('returns the closest binding when the name is bound at multiple levels', () => {
+      const outerUser = mkDef({ nodeId: 'def:outer', type: 'Class' });
+      const innerUser = mkDef({ nodeId: 'def:inner', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(outerUser, 'local')],
+      });
+      const classScope = mkScope('scope:class', 'scope:module', {
+        User: [mkBinding(innerUser, 'local')],
+      });
+      const ctx = mkCtx([moduleScope, classScope], [outerUser, innerUser]);
+      const result = resolveTypeRef(typeRef('User', 'scope:class'), ctx);
+      expect(result).toBe(innerUser); // inner shadows outer
+    });
+  });
+
+  describe('import origins', () => {
+    it('resolves a plain named import', () => {
+      const userClass = mkDef({ nodeId: 'def:User', filePath: 'models.ts', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(userClass, 'import')],
+      });
+      const ctx = mkCtx([moduleScope], [userClass]);
+      expect(resolveTypeRef(typeRef('User', 'scope:module'), ctx)).toBe(userClass);
+    });
+
+    it('resolves an aliased import under the alias (e.g., `import { User as Account }`)', () => {
+      // In `def save_user(user: Account)` where `Account` is an aliased import
+      // of `User`, we resolve `Account` to the underlying `User` class def.
+      const userClass = mkDef({ nodeId: 'def:User', filePath: 'models.ts', type: 'Class' });
+      const importEdge: ImportEdge = {
+        localName: 'Account',
+        targetFile: 'models.ts',
+        targetExportedName: 'User',
+        targetDefId: 'def:User',
+        kind: 'alias',
+      };
+      const moduleScope = mkScope('scope:module', null, {
+        Account: [mkBinding(userClass, 'import', importEdge)],
+      });
+      const ctx = mkCtx([moduleScope], [userClass]);
+      expect(resolveTypeRef(typeRef('Account', 'scope:module'), ctx)).toBe(userClass);
+    });
+
+    it('returns null for a namespace-origin binding whose def is not a type kind', () => {
+      const numpyMod = mkDef({ nodeId: 'def:numpy-mod', type: 'Namespace' });
+      // A namespace binding must resolve to a type-kind def to satisfy strict
+      // mode. Here the binding is the namespace module itself — `Namespace`
+      // is intentionally NOT in `TYPE_KINDS` (see resolve-type-ref.ts), so
+      // the binding is treated as a shadowing non-type and we fail fast.
+      const moduleScope = mkScope('scope:module', null, {
+        np: [mkBinding(numpyMod, 'namespace')],
+      });
+      const ctx = mkCtx([moduleScope], [numpyMod]);
+      expect(resolveTypeRef(typeRef('np', 'scope:module'), ctx)).toBeNull();
+    });
+
+    it('resolves a re-exported type (`export { X } from `./y`)', () => {
+      const userClass = mkDef({ nodeId: 'def:User', filePath: 'y.ts', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(userClass, 'reexport')],
+      });
+      const ctx = mkCtx([moduleScope], [userClass]);
+      expect(resolveTypeRef(typeRef('User', 'scope:module'), ctx)).toBe(userClass);
+    });
+
+    it('ignores wildcard origin — not in the strict set', () => {
+      const userClass = mkDef({ nodeId: 'def:User', filePath: 'models.ts', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(userClass, 'wildcard')],
+      });
+      const ctx = mkCtx([moduleScope], [userClass]);
+      // Binding exists but wildcard is not strict → return null (shadow).
+      expect(resolveTypeRef(typeRef('User', 'scope:module'), ctx)).toBeNull();
+    });
+
+    it('prefers a strict-origin type binding over a non-strict binding at the same scope', () => {
+      const wildcardClass = mkDef({ nodeId: 'def:wild', type: 'Class' });
+      const importClass = mkDef({ nodeId: 'def:import', type: 'Class' });
+      const moduleScope = mkScope('scope:module', null, {
+        // The strict-origin binding wins regardless of input order.
+        User: [mkBinding(wildcardClass, 'wildcard'), mkBinding(importClass, 'import')],
+      });
+      const ctx = mkCtx([moduleScope], [wildcardClass, importClass]);
+      expect(resolveTypeRef(typeRef('User', 'scope:module'), ctx)).toBe(importClass);
+    });
+  });
+
+  describe('shadowing (non-type binding fails fast)', () => {
+    it('returns null when a local variable shadows an outer imported type', () => {
+      // Outer module has `import { User }`; inner function declares `User = 5`.
+      // Per RFC §4.6, the local non-type shadows; strict resolver returns null.
+      const importedUser = mkDef({ nodeId: 'def:imp', type: 'Class' });
+      const localUser = mkDef({ nodeId: 'def:local', type: 'Variable' });
+      const moduleScope = mkScope('scope:module', null, {
+        User: [mkBinding(importedUser, 'import')],
+      });
+      const functionScope = mkScope('scope:fn', 'scope:module', {
+        User: [mkBinding(localUser, 'local')],
+      });
+      const ctx = mkCtx([moduleScope, functionScope], [importedUser, localUser]);
+      expect(resolveTypeRef(typeRef('User', 'scope:fn'), ctx)).toBeNull();
+    });
+
+    it('returns null when the only binding at the declaration scope is a Method', () => {
+      const method = mkDef({ nodeId: 'def:m', type: 'Method' });
+      const scope = mkScope('scope:class', null, {
+        save: [mkBinding(method, 'local')],
+      });
+      const ctx = mkCtx([scope], [method]);
+      expect(resolveTypeRef(typeRef('save', 'scope:class'), ctx)).toBeNull();
+    });
+
+    it('does NOT fall through to the qualified-name index when shadowed', () => {
+      // Even if `app.User` is a unique type in the qualified-name index, a
+      // shadowing non-type binding at the declaration scope should short-circuit.
+      const shadowVar = mkDef({ nodeId: 'def:v', type: 'Variable' });
+      const globalType = mkDef({
+        nodeId: 'def:g',
+        qualifiedName: 'app.User',
+        type: 'Class',
+      });
+      const scope = mkScope('scope:s', null, {
+        'app.User': [mkBinding(shadowVar, 'local')],
+      });
+      const ctx = mkCtx([scope], [shadowVar, globalType]);
+      expect(resolveTypeRef(typeRef('app.User', 'scope:s'), ctx)).toBeNull();
+    });
+  });
+
+  describe('dotted qualified-name fallback', () => {
+    it('resolves a unique qualified name when no scope binding matches', () => {
+      const userClass = mkDef({
+        nodeId: 'def:appUser',
+        qualifiedName: 'app.models.User',
+        type: 'Class',
+      });
+      const scope = mkScope('scope:s', null); // no bindings for `app.models.User`
+      const ctx = mkCtx([scope], [userClass]);
+      expect(resolveTypeRef(typeRef('app.models.User', 'scope:s'), ctx)).toBe(userClass);
+    });
+
+    it('does NOT apply the qualified-name fallback for non-dotted names', () => {
+      const simple = mkDef({ nodeId: 'def:s', qualifiedName: 'User', type: 'Class' });
+      const scope = mkScope('scope:s', null);
+      const ctx = mkCtx([scope], [simple]);
+      // Even though `User` is in the qname index as `User`, the fallback only
+      // fires for dotted names (scope walk is the answer for simple names).
+      expect(resolveTypeRef(typeRef('User', 'scope:s'), ctx)).toBeNull();
+    });
+
+    it('returns null when the qualified name is ambiguous across type defs', () => {
+      const a = mkDef({ nodeId: 'def:a', qualifiedName: 'app.User', type: 'Class' });
+      const b = mkDef({ nodeId: 'def:b', qualifiedName: 'app.User', type: 'Class' });
+      const scope = mkScope('scope:s', null);
+      const ctx = mkCtx([scope], [a, b]);
+      expect(resolveTypeRef(typeRef('app.User', 'scope:s'), ctx)).toBeNull();
+    });
+
+    it('ignores non-type-kind hits and accepts the single type hit', () => {
+      const cls = mkDef({ nodeId: 'def:c', qualifiedName: 'app.User', type: 'Class' });
+      const fn = mkDef({ nodeId: 'def:f', qualifiedName: 'app.User', type: 'Function' });
+      const scope = mkScope('scope:s', null);
+      const ctx = mkCtx([scope], [cls, fn]);
+      expect(resolveTypeRef(typeRef('app.User', 'scope:s'), ctx)).toBe(cls);
+    });
+
+    it('returns null when no qualified-name hit is a type kind', () => {
+      const fn = mkDef({ nodeId: 'def:f', qualifiedName: 'app.User', type: 'Function' });
+      const scope = mkScope('scope:s', null);
+      const ctx = mkCtx([scope], [fn]);
+      expect(resolveTypeRef(typeRef('app.User', 'scope:s'), ctx)).toBeNull();
+    });
+  });
+
+  describe('robustness', () => {
+    it('returns null for a missing type (no scope binding, no qname hit)', () => {
+      const scope = mkScope('scope:s', null);
+      const ctx = mkCtx([scope], []);
+      expect(resolveTypeRef(typeRef('User', 'scope:s'), ctx)).toBeNull();
+    });
+
+    it('returns null when the declaredAtScope id is not known to the lookup', () => {
+      const ctx = mkCtx([], []);
+      expect(resolveTypeRef(typeRef('User', 'scope:missing'), ctx)).toBeNull();
+    });
+
+    it('returns null when a parent pointer references an unknown scope (broken chain)', () => {
+      const functionScope = mkScope('scope:fn', 'scope:ghost');
+      const ctx = mkCtx([functionScope], []);
+      expect(resolveTypeRef(typeRef('User', 'scope:fn'), ctx)).toBeNull();
+    });
+
+    it('terminates cleanly on a cyclic parent chain (defensive guard)', () => {
+      // A well-formed scope tree is acyclic; construction bugs shouldn't hang.
+      const a: Scope = mkScope('scope:a', 'scope:b');
+      const b: Scope = mkScope('scope:b', 'scope:a');
+      const ctx = mkCtx([a, b], []);
+      expect(resolveTypeRef(typeRef('User', 'scope:a'), ctx)).toBeNull();
+    });
+
+    it('accepts all annotation source flavors uniformly', () => {
+      const userClass = mkDef({ nodeId: 'def:User', type: 'Class' });
+      const scope = mkScope('scope:s', null, {
+        User: [mkBinding(userClass, 'local')],
+      });
+      const ctx = mkCtx([scope], [userClass]);
+      for (const source of [
+        'annotation',
+        'parameter-annotation',
+        'return-annotation',
+        'self',
+        'assignment-inferred',
+        'constructor-inferred',
+        'receiver-propagated',
+      ] as const) {
+        expect(resolveTypeRef(typeRef('User', 'scope:s', source), ctx)).toBe(userClass);
+      }
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/scope-extractor.test.ts b/gitnexus/test/unit/scope-resolution/scope-extractor.test.ts
new file mode 100644
index 000000000..0a03e95f7
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/scope-extractor.test.ts
@@ -0,0 +1,558 @@
+/**
+ * Unit tests for `scope-extractor.extract` — the 5-pass driver
+ * (RFC §5.3; Ring 2 PKG #919).
+ *
+ * Tests are organized by pass so a regression localizes to the pass it
+ * broke. A `MockProvider` emits synthetic `CaptureMatch[]` with no real
+ * AST; the extractor is pure given those captures.
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+  Capture,
+  CaptureMatch,
+  ParsedImport,
+  ParsedTypeBinding,
+  ReferenceKind,
+  Scope,
+  ScopeKind,
+} from 'gitnexus-shared';
+import { extract, type ScopeExtractorHooks } from '../../../src/core/ingestion/scope-extractor.js';
+
+// ─── Synthetic-capture helpers ──────────────────────────────────────────────
+
+const cap = (
+  name: string,
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+  text = '',
+): Capture => ({
+  name,
+  range: { startLine, startCol, endLine, endCol },
+  text,
+});
+
+const scopeMatch = (
+  kind: Lowercase<ScopeKind>,
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+): CaptureMatch => ({
+  [`@scope.${kind}`]: cap(`@scope.${kind}`, startLine, startCol, endLine, endCol),
+});
+
+const declMatch = (
+  kindStr: string,
+  name: string,
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+  extras: Record<string, Capture> = {},
+): CaptureMatch => ({
+  [`@declaration.${kindStr}`]: cap(`@declaration.${kindStr}`, startLine, startCol, endLine, endCol),
+  '@declaration.name': cap('@declaration.name', startLine, startCol, endLine, endCol, name),
+  ...extras,
+});
+
+const importMatch = (
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+): CaptureMatch => ({
+  '@import.statement': cap('@import.statement', startLine, startCol, endLine, endCol),
+});
+
+const typeBindingMatch = (
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+): CaptureMatch => ({
+  '@type-binding.parameter': cap('@type-binding.parameter', startLine, startCol, endLine, endCol),
+});
+
+const refMatch = (
+  suffix: string,
+  name: string,
+  startLine: number,
+  startCol: number,
+  endLine: number,
+  endCol: number,
+  extras: Record<string, Capture> = {},
+): CaptureMatch => ({
+  [`@reference.${suffix}`]: cap(`@reference.${suffix}`, startLine, startCol, endLine, endCol),
+  '@reference.name': cap('@reference.name', startLine, startCol, endLine, endCol, name),
+  ...extras,
+});
+
+// ─── MockProvider ───────────────────────────────────────────────────────────
+//
+// The extractor declares its dependency on a narrow `ScopeExtractorHooks`
+// surface — not the full `LanguageProvider`. Tests implement exactly that
+// surface, so adding a new hook to `extract()` that's not in
+// `ScopeExtractorHooks` is a compile error, not a silent test pass.
+
+function mockProvider(hooks: Partial<ScopeExtractorHooks> = {}): ScopeExtractorHooks {
+  return hooks;
+}
+
+// ─── §Pass 1: scope tree construction ──────────────────────────────────────
+
+describe('Pass 1: scope tree', () => {
+  it('creates a single Module scope from one @scope.module match', () => {
+    const result = extract([scopeMatch('module', 1, 0, 100, 0)], 'a.ts', mockProvider());
+    expect(result.scopes).toHaveLength(1);
+    expect(result.scopes[0]!.kind).toBe('Module');
+    expect(result.scopes[0]!.parent).toBeNull();
+    expect(result.moduleScope).toBe(result.scopes[0]!.id);
+  });
+
+  it('nests Class under Module when the class range is contained in the module range', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), scopeMatch('class', 5, 0, 50, 0)],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.scopes).toHaveLength(2);
+    const cls = result.scopes.find((s) => s.kind === 'Class')!;
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    expect(cls.parent).toBe(mod.id);
+  });
+
+  it('nests Method under Class, Class under Module — deep nesting', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('class', 5, 0, 50, 0),
+        scopeMatch('function', 10, 2, 30, 2),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    const cls = result.scopes.find((s) => s.kind === 'Class')!;
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    expect(cls.parent).toBe(mod.id);
+    expect(fn.parent).toBe(cls.id);
+  });
+
+  it('places non-nested siblings at the same level under the module', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('function', 10, 0, 20, 0),
+        scopeMatch('function', 30, 0, 40, 0),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    const fns = result.scopes.filter((s) => s.kind === 'Function');
+    expect(fns).toHaveLength(2);
+    for (const fn of fns) expect(fn.parent).toBe(mod.id);
+  });
+
+  it('honors `provider.shouldCreateScope === false` by reparenting children to next real scope', () => {
+    // Block at [10:0..25:0] is SUPPRESSED; inner function at [12:0..20:0]
+    // should reparent to the enclosing Module instead of the Block.
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('block', 10, 0, 25, 0),
+        scopeMatch('function', 12, 0, 20, 0),
+      ],
+      'a.ts',
+      mockProvider({
+        shouldCreateScope: (match) => match['@scope.block'] === undefined,
+      }),
+    );
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    expect(result.scopes).toHaveLength(2); // block suppressed
+    expect(fn.parent).toBe(mod.id);
+  });
+
+  it('uses `provider.resolveScopeKind` to override the default kind from the suffix', () => {
+    // Provider upgrades a `@scope.block` to `Expression` for a comprehension-
+    // style use case.
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), scopeMatch('block', 10, 0, 15, 0)],
+      'a.ts',
+      mockProvider({
+        resolveScopeKind: (match) => (match['@scope.block'] !== undefined ? 'Expression' : null),
+      }),
+    );
+    expect(result.scopes.find((s) => s.kind === 'Expression')).toBeDefined();
+  });
+
+  it('throws ScopeTreeInvariantError when siblings overlap (provider bug)', () => {
+    expect(() =>
+      extract(
+        [
+          scopeMatch('module', 1, 0, 100, 0),
+          scopeMatch('function', 10, 0, 20, 0),
+          scopeMatch('function', 15, 0, 25, 0), // overlaps
+        ],
+        'a.ts',
+        mockProvider(),
+      ),
+    ).toThrow(/overlap/i);
+  });
+
+  it('throws when no Module scope is present', () => {
+    expect(() => extract([scopeMatch('function', 1, 0, 10, 0)], 'a.ts', mockProvider())).toThrow(
+      /Module/,
+    );
+  });
+});
+
+// ─── §Pass 2: declarations + local bindings ────────────────────────────────
+
+describe('Pass 2: declarations + local bindings', () => {
+  it('attaches a Class declaration to its enclosing Module scope', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('class', 5, 0, 50, 0),
+        declMatch('class', 'User', 5, 6, 5, 10),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    // The declaration sits at line 5 → innermost scope is Class (at 5:0..50:0).
+    const cls = result.scopes.find((s) => s.kind === 'Class')!;
+    expect(cls.ownedDefs).toHaveLength(1);
+    expect(cls.ownedDefs[0]!.type).toBe('Class');
+    expect(cls.ownedDefs[0]!.qualifiedName).toBe('User');
+    expect(cls.bindings.get('User')).toBeDefined();
+    expect(cls.bindings.get('User')![0]!.origin).toBe('local');
+  });
+
+  it('records the declaration in `localDefs` as well', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), declMatch('function', 'render', 5, 0, 5, 6)],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.localDefs).toHaveLength(1);
+    expect(result.localDefs[0]!.type).toBe('Function');
+  });
+
+  it('honors `provider.bindingScopeFor` to hoist a binding to an outer scope', () => {
+    // Treat every declaration as hoisted to the module scope.
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('function', 10, 0, 30, 0),
+        declMatch('variable', 'x', 15, 4, 15, 5),
+      ],
+      'a.ts',
+      mockProvider({
+        bindingScopeFor: (_match, _innermost, scopeTree) => {
+          for (const s of scopeTree.byId.values()) if (s.kind === 'Module') return s.id;
+          return null;
+        },
+      }),
+    );
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    // Binding hoisted to module; function scope's bindings empty for 'x'.
+    expect(mod.bindings.get('x')).toBeDefined();
+    expect(fn.bindings.get('x')).toBeUndefined();
+    // `ownedDefs` stays structural (innermost = function).
+    expect(fn.ownedDefs).toHaveLength(1);
+  });
+
+  it('ignores declarations with unknown kind suffixes', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), declMatch('mystery', 'x', 5, 0, 5, 1)],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.localDefs).toHaveLength(0);
+  });
+});
+
+// ─── §Pass 3: imports ──────────────────────────────────────────────────────
+
+describe('Pass 3: raw imports', () => {
+  it('collects imports via `provider.interpretImport`', () => {
+    const named: ParsedImport = {
+      kind: 'named',
+      localName: 'User',
+      importedName: 'User',
+      targetRaw: './models',
+    };
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), importMatch(3, 0, 3, 30)],
+      'a.ts',
+      mockProvider({
+        interpretImport: () => named,
+      }),
+    );
+    expect(result.parsedImports).toEqual([named]);
+  });
+
+  it('drops imports when `interpretImport` returns null', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), importMatch(3, 0, 3, 30)],
+      'a.ts',
+      mockProvider({
+        interpretImport: () => null,
+      }),
+    );
+    expect(result.parsedImports).toEqual([]);
+  });
+
+  it('emits no imports when the provider does not implement `interpretImport`', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), importMatch(3, 0, 3, 30)],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.parsedImports).toEqual([]);
+  });
+});
+
+// ─── §Pass 4: type bindings ───────────────────────────────────────────────
+
+describe('Pass 4: type bindings', () => {
+  it('attaches a parameter-annotation TypeRef to the innermost scope', () => {
+    const parsed: ParsedTypeBinding = {
+      boundName: 'user',
+      rawTypeName: 'User',
+      source: 'parameter-annotation',
+    };
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('function', 5, 0, 20, 0),
+        typeBindingMatch(6, 4, 6, 14),
+      ],
+      'a.ts',
+      mockProvider({
+        interpretTypeBinding: () => parsed,
+      }),
+    );
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    const tb = fn.typeBindings.get('user');
+    expect(tb).toBeDefined();
+    expect(tb!.rawName).toBe('User');
+    expect(tb!.source).toBe('parameter-annotation');
+    expect(tb!.declaredAtScope).toBe(fn.id);
+  });
+
+  it('skips type-binding matches when the provider returns null', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('function', 5, 0, 20, 0),
+        typeBindingMatch(6, 4, 6, 14),
+      ],
+      'a.ts',
+      mockProvider({
+        interpretTypeBinding: () => null,
+      }),
+    );
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    expect(fn.typeBindings.size).toBe(0);
+  });
+});
+
+// ─── §Pass 5: reference sites ─────────────────────────────────────────────
+
+describe('Pass 5: reference sites', () => {
+  it('emits a call reference with the innermost scope anchor', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        scopeMatch('function', 5, 0, 20, 0),
+        refMatch('call.free', 'print', 10, 4, 10, 9),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    expect(result.referenceSites).toHaveLength(1);
+    expect(result.referenceSites[0]!.name).toBe('print');
+    expect(result.referenceSites[0]!.kind).toBe('call');
+    expect(result.referenceSites[0]!.callForm).toBe('free');
+    expect(result.referenceSites[0]!.inScope).toBe(fn.id);
+  });
+
+  it('classifies member calls via the `@reference.call.member` sub-tag', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        refMatch('call.member', 'save', 3, 4, 3, 8, {
+          '@reference.receiver': cap('@reference.receiver', 3, 0, 3, 4, 'user'),
+        }),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.referenceSites[0]!.callForm).toBe('member');
+    expect(result.referenceSites[0]!.explicitReceiver).toEqual({ name: 'user' });
+  });
+
+  it('falls back to `provider.classifyCallForm` when the anchor has no sub-tag', () => {
+    const result = extract(
+      [scopeMatch('module', 1, 0, 100, 0), refMatch('call', 'foo', 3, 0, 3, 3)],
+      'a.ts',
+      mockProvider({
+        classifyCallForm: () => 'member',
+      }),
+    );
+    expect(result.referenceSites[0]!.callForm).toBe('member');
+  });
+
+  it('recognizes all reference kinds (call, read, write, inherits, type, import_use)', () => {
+    const kindsToEmit: Array<[string, ReferenceKind]> = [
+      ['call.free', 'call'],
+      ['read', 'read'],
+      ['write', 'write'],
+      ['inherits', 'inherits'],
+      ['type', 'type-reference'],
+      ['import_use', 'import-use'],
+    ];
+    const matches = [
+      scopeMatch('module', 1, 0, 100, 0),
+      ...kindsToEmit.map(([suffix], i) => refMatch(suffix, `ref${i}`, 10 + i, 0, 10 + i, 5)),
+    ];
+    const result = extract(matches, 'a.ts', mockProvider());
+    expect(result.referenceSites.map((s) => s.kind)).toEqual(kindsToEmit.map(([, kind]) => kind));
+  });
+
+  it('picks the call anchor over a wider-ranged @reference.receiver (regression for KNOWN_SUB_TAGS exclusion)', () => {
+    // Regression for the bug fixed before commit: a member call like
+    // `user.save()` where the receiver capture (`user`) spans MORE source
+    // than the call anchor (`save`). The broadest-range anchor heuristic
+    // would have picked the receiver — `anchorCaptureFor` must exclude
+    // known sub-tags (`@reference.receiver`, `@reference.name`, etc.) to
+    // route the match as a `call` reference.
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        {
+          // Receiver spans columns 0-10 (wider).
+          '@reference.receiver': cap('@reference.receiver', 3, 0, 3, 10, 'longUserName'),
+          // Call name spans columns 11-15 (narrower).
+          '@reference.name': cap('@reference.name', 3, 11, 3, 15, 'save'),
+          // The anchor — call.member — spans 0-17 (full expression). In the
+          // buggy behavior the receiver would have tied-or-won. Even here,
+          // the fix guarantees we pick the call anchor, never the sub-tag.
+          '@reference.call.member': cap('@reference.call.member', 3, 0, 3, 17),
+        },
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.referenceSites).toHaveLength(1);
+    expect(result.referenceSites[0]!.name).toBe('save'); // NOT 'longUserName'
+    expect(result.referenceSites[0]!.kind).toBe('call');
+    expect(result.referenceSites[0]!.callForm).toBe('member');
+    expect(result.referenceSites[0]!.explicitReceiver).toEqual({ name: 'longUserName' });
+  });
+
+  it('parses arity from @reference.arity when present', () => {
+    const result = extract(
+      [
+        scopeMatch('module', 1, 0, 100, 0),
+        refMatch('call.free', 'foo', 3, 0, 3, 3, {
+          '@reference.arity': cap('@reference.arity', 3, 0, 3, 0, '2'),
+        }),
+      ],
+      'a.ts',
+      mockProvider(),
+    );
+    expect(result.referenceSites[0]!.arity).toBe(2);
+  });
+});
+
+// ─── §End-to-end fixture ──────────────────────────────────────────────────
+
+describe('end-to-end fixture (all 5 passes together)', () => {
+  it('produces a well-formed ParsedFile from a representative multi-pass input', () => {
+    const matches: CaptureMatch[] = [
+      // Pass 1: nested scopes
+      scopeMatch('module', 1, 0, 100, 0),
+      scopeMatch('class', 5, 0, 50, 0),
+      scopeMatch('function', 10, 2, 40, 2),
+      // Pass 2: declarations
+      declMatch('class', 'User', 5, 6, 5, 10),
+      declMatch('method', 'save', 10, 2, 10, 6),
+      declMatch('field', 'count', 7, 2, 7, 7),
+      // Pass 3: import
+      importMatch(3, 0, 3, 30),
+      // Pass 4: type binding
+      typeBindingMatch(10, 14, 10, 18),
+      // Pass 5: references
+      refMatch('call.member', 'log', 20, 4, 20, 7, {
+        '@reference.receiver': cap('@reference.receiver', 20, 0, 20, 4, 'self'),
+      }),
+      refMatch('read', 'count', 25, 4, 25, 9),
+    ];
+
+    const parsedImport: ParsedImport = {
+      kind: 'named',
+      localName: 'Logger',
+      importedName: 'Logger',
+      targetRaw: './logger',
+    };
+    const parsedTypeBinding: ParsedTypeBinding = {
+      boundName: 'name',
+      rawTypeName: 'string',
+      source: 'parameter-annotation',
+    };
+
+    const result = extract(
+      matches,
+      'user.ts',
+      mockProvider({
+        interpretImport: () => parsedImport,
+        interpretTypeBinding: () => parsedTypeBinding,
+      }),
+    );
+
+    // Three scopes, properly nested.
+    expect(result.scopes).toHaveLength(3);
+    const kinds = result.scopes.map((s: Scope) => s.kind);
+    expect(kinds).toEqual(expect.arrayContaining(['Module', 'Class', 'Function']));
+
+    // Declarations landed on the correct scopes.
+    const cls = result.scopes.find((s) => s.kind === 'Class')!;
+    const fn = result.scopes.find((s) => s.kind === 'Function')!;
+    expect(cls.ownedDefs.map((d) => d.qualifiedName).sort()).toEqual(['User', 'count'].sort());
+    expect(fn.ownedDefs.map((d) => d.qualifiedName)).toEqual(['save']);
+
+    // Local bindings present.
+    expect(cls.bindings.get('User')).toBeDefined();
+    expect(cls.bindings.get('count')).toBeDefined();
+    expect(fn.bindings.get('save')).toBeDefined();
+
+    // Import collected.
+    expect(result.parsedImports).toEqual([parsedImport]);
+
+    // Type binding attached to function scope.
+    expect(fn.typeBindings.get('name')?.rawName).toBe('string');
+
+    // References emitted.
+    expect(result.referenceSites).toHaveLength(2);
+    expect(result.referenceSites.map((r) => r.kind)).toEqual(['call', 'read']);
+
+    // `localDefs` is the union across scopes.
+    expect(result.localDefs).toHaveLength(3);
+    expect(result.localDefs.map((d) => d.type).sort()).toEqual(
+      ['Class', 'Method', 'Property'].sort(),
+    );
+
+    // Module scope id matches the ParsedFile header.
+    const mod = result.scopes.find((s) => s.kind === 'Module')!;
+    expect(result.moduleScope).toBe(mod.id);
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/scope-id.test.ts b/gitnexus/test/unit/scope-resolution/scope-id.test.ts
new file mode 100644
index 000000000..901c89868
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/scope-id.test.ts
@@ -0,0 +1,81 @@
+/**
+ * Unit tests for `makeScopeId` (RFC #909 Ring 2 SHARED #912).
+ *
+ * Covers canonical shape, determinism across calls, string interning,
+ * and that different inputs produce different ids.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { makeScopeId, clearScopeIdInternPool, type Range, type ScopeKind } from 'gitnexus-shared';
+
+const r = (startLine: number, startCol: number, endLine: number, endCol: number): Range => ({
+  startLine,
+  startCol,
+  endLine,
+  endCol,
+});
+
+describe('makeScopeId', () => {
+  beforeEach(() => {
+    clearScopeIdInternPool();
+  });
+
+  it('produces the canonical RFC §2.2 shape', () => {
+    const id = makeScopeId({ filePath: 'src/app.ts', range: r(1, 0, 100, 0), kind: 'Module' });
+    expect(id).toBe('scope:src/app.ts#1:0-100:0:Module');
+  });
+
+  it('encodes each ScopeKind verbatim in the id', () => {
+    const kinds: readonly ScopeKind[] = [
+      'Module',
+      'Namespace',
+      'Class',
+      'Function',
+      'Block',
+      'Expression',
+    ];
+    for (const kind of kinds) {
+      const id = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind });
+      expect(id.endsWith(`:${kind}`)).toBe(true);
+    }
+  });
+
+  it('returns the SAME string reference for structurally identical inputs (interned)', () => {
+    const a = makeScopeId({ filePath: 'src/a.ts', range: r(5, 4, 10, 2), kind: 'Function' });
+    const b = makeScopeId({ filePath: 'src/a.ts', range: r(5, 4, 10, 2), kind: 'Function' });
+    expect(a).toBe(b);
+    // `Object.is` catches the same reference even for weird strings.
+    expect(Object.is(a, b)).toBe(true);
+  });
+
+  it('distinguishes ids that differ only by filePath', () => {
+    const a = makeScopeId({ filePath: 'src/a.ts', range: r(1, 0, 2, 0), kind: 'Module' });
+    const b = makeScopeId({ filePath: 'src/b.ts', range: r(1, 0, 2, 0), kind: 'Module' });
+    expect(a).not.toBe(b);
+  });
+
+  it('distinguishes ids that differ only by range', () => {
+    const a = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind: 'Function' });
+    const b = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 3, 0), kind: 'Function' });
+    expect(a).not.toBe(b);
+  });
+
+  it('distinguishes ids that differ only by kind', () => {
+    const a = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind: 'Function' });
+    const b = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind: 'Block' });
+    expect(a).not.toBe(b);
+  });
+
+  it('is safe to call repeatedly (pure)', () => {
+    const inputs = { filePath: 'f.ts', range: r(1, 0, 5, 0), kind: 'Function' as const };
+    const ids = Array.from({ length: 10 }, () => makeScopeId(inputs));
+    expect(new Set(ids).size).toBe(1);
+  });
+
+  it('clearScopeIdInternPool drops the intern pool without changing id shape', () => {
+    const before = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind: 'Module' });
+    clearScopeIdInternPool();
+    const after = makeScopeId({ filePath: 'f.ts', range: r(1, 0, 2, 0), kind: 'Module' });
+    expect(after).toBe(before); // same string value, canonical-by-construction
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/scope-tree.test.ts b/gitnexus/test/unit/scope-resolution/scope-tree.test.ts
new file mode 100644
index 000000000..7173ba3fc
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/scope-tree.test.ts
@@ -0,0 +1,299 @@
+/**
+ * Unit tests for `buildScopeTree` / `ScopeTree` (RFC #909 Ring 2 SHARED #912).
+ *
+ * Covers: empty tree, single-module tree, nested module→class→function,
+ * siblings, ancestors walk, children lookup, readonly surface, and all six
+ * invariant violations (non-module without parent, parent not found, parent
+ * doesn't contain child, siblings overlap, cross-file parent, duplicate id).
+ * Also confirms that a `ScopeTree` satisfies the `ScopeLookup` contract from
+ * #916 so `resolveTypeRef` can consume it directly.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  buildScopeTree,
+  ScopeTreeInvariantError,
+  resolveTypeRef,
+  buildDefIndex,
+  buildQualifiedNameIndex,
+  type BindingRef,
+  type Range,
+  type Scope,
+  type ScopeId,
+  type ScopeKind,
+  type SymbolDefinition,
+} from 'gitnexus-shared';
+
+// ─── Test helpers ───────────────────────────────────────────────────────────
+
+const r = (startLine: number, startCol: number, endLine: number, endCol: number): Range => ({
+  startLine,
+  startCol,
+  endLine,
+  endCol,
+});
+
+interface ScopeFixture {
+  id: ScopeId;
+  parent: ScopeId | null;
+  kind: ScopeKind;
+  range: Range;
+  filePath?: string;
+  bindings?: Record<string, readonly BindingRef[]>;
+}
+
+const mkScope = (f: ScopeFixture): Scope => ({
+  id: f.id,
+  parent: f.parent,
+  kind: f.kind,
+  range: f.range,
+  filePath: f.filePath ?? 'src/test.ts',
+  bindings: new Map(Object.entries(f.bindings ?? {})),
+  ownedDefs: [],
+  imports: [],
+  typeBindings: new Map(),
+});
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('buildScopeTree', () => {
+  describe('shape + lookup', () => {
+    it('builds an empty tree from no scopes', () => {
+      const tree = buildScopeTree([]);
+      expect(tree.size).toBe(0);
+      expect(tree.has('scope:missing')).toBe(false);
+      expect(tree.getScope('scope:missing')).toBeUndefined();
+      expect(tree.getParent('scope:missing')).toBeUndefined();
+      expect(tree.getChildren('scope:missing')).toEqual([]);
+      expect(tree.getAncestors('scope:missing')).toEqual([]);
+    });
+
+    it('round-trips a single module scope', () => {
+      const m = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 100, 0) });
+      const tree = buildScopeTree([m]);
+      expect(tree.size).toBe(1);
+      expect(tree.has('scope:m')).toBe(true);
+      expect(tree.getScope('scope:m')).toBe(m);
+      expect(tree.getParent('scope:m')).toBeUndefined();
+      expect(tree.getChildren('scope:m')).toEqual([]);
+      expect(tree.getAncestors('scope:m')).toEqual([]);
+    });
+
+    it('tracks parent/children for a nested module → class → function tree', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 50, 0) });
+      const cls = mkScope({
+        id: 'scope:c',
+        parent: 'scope:m',
+        kind: 'Class',
+        range: r(5, 0, 40, 0),
+      });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:c',
+        kind: 'Function',
+        range: r(10, 2, 30, 2),
+      });
+      const tree = buildScopeTree([mod, cls, fn]);
+
+      expect(tree.size).toBe(3);
+      expect(tree.getParent('scope:f')).toBe(cls);
+      expect(tree.getParent('scope:c')).toBe(mod);
+      expect(tree.getChildren('scope:m')).toEqual(['scope:c']);
+      expect(tree.getChildren('scope:c')).toEqual(['scope:f']);
+      expect(tree.getAncestors('scope:f')).toEqual(['scope:c', 'scope:m']);
+      expect(tree.getAncestors('scope:c')).toEqual(['scope:m']);
+    });
+
+    it('records multiple siblings in input order', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 100, 0) });
+      const fn1 = mkScope({
+        id: 'scope:f1',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 10, 0),
+      });
+      const fn2 = mkScope({
+        id: 'scope:f2',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(15, 0, 20, 0),
+      });
+      const fn3 = mkScope({
+        id: 'scope:f3',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(25, 0, 30, 0),
+      });
+      const tree = buildScopeTree([mod, fn2, fn1, fn3]); // deliberately out of order
+      expect(tree.getChildren('scope:m')).toEqual(['scope:f2', 'scope:f1', 'scope:f3']);
+    });
+  });
+
+  describe('ScopeLookup compatibility (#916)', () => {
+    it('resolveTypeRef can consume a ScopeTree directly', () => {
+      const userClass: SymbolDefinition = {
+        nodeId: 'def:User',
+        filePath: 'src/test.ts',
+        type: 'Class',
+      };
+      const module = mkScope({
+        id: 'scope:m',
+        parent: null,
+        kind: 'Module',
+        range: r(1, 0, 100, 0),
+        bindings: { User: [{ def: userClass, origin: 'local' }] },
+      });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 10, 0),
+      });
+
+      const tree = buildScopeTree([module, fn]);
+      const result = resolveTypeRef(
+        { rawName: 'User', declaredAtScope: 'scope:f', source: 'parameter-annotation' },
+        {
+          scopes: tree,
+          defIndex: buildDefIndex([userClass]),
+          qualifiedNameIndex: buildQualifiedNameIndex([userClass]),
+        },
+      );
+      expect(result).toBe(userClass);
+    });
+  });
+
+  describe('readonly surface', () => {
+    it('freezes children arrays', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 50, 0) });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 10, 0),
+      });
+      const tree = buildScopeTree([mod, fn]);
+      const children = tree.getChildren('scope:m');
+      expect(() => (children as unknown as ScopeId[]).push('x')).toThrow();
+    });
+
+    it('freezes ancestor arrays', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 50, 0) });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 10, 0),
+      });
+      const tree = buildScopeTree([mod, fn]);
+      const ancestors = tree.getAncestors('scope:f');
+      expect(() => (ancestors as unknown as ScopeId[]).push('x')).toThrow();
+    });
+  });
+
+  describe('invariant violations', () => {
+    it('throws when a non-Module scope has a null parent', () => {
+      const orphan = mkScope({
+        id: 'scope:f',
+        parent: null,
+        kind: 'Function',
+        range: r(1, 0, 5, 0),
+      });
+      expect(() => buildScopeTree([orphan])).toThrowError(ScopeTreeInvariantError);
+      expect(() => buildScopeTree([orphan])).toThrowError(/Module/);
+    });
+
+    it('throws when a parent pointer references a scope not in the tree', () => {
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:ghost',
+        kind: 'Function',
+        range: r(1, 0, 5, 0),
+      });
+      expect(() => buildScopeTree([fn])).toThrowError(ScopeTreeInvariantError);
+    });
+
+    it('throws when a parent range does not strictly contain a child range', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 10, 0) });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 50, 0), // extends beyond the module
+      });
+      expect(() => buildScopeTree([mod, fn])).toThrowError(ScopeTreeInvariantError);
+      expect(() => buildScopeTree([mod, fn])).toThrowError(/strictly contain/i);
+    });
+
+    it('rejects child ranges identical to the parent (not strictly contained)', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 10, 0) });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(1, 0, 10, 0),
+      });
+      expect(() => buildScopeTree([mod, fn])).toThrowError(ScopeTreeInvariantError);
+    });
+
+    it('throws when sibling ranges overlap', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 100, 0) });
+      const a = mkScope({
+        id: 'scope:a',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 20, 0),
+      });
+      const b = mkScope({
+        id: 'scope:b',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(15, 0, 30, 0), // overlaps with a
+      });
+      expect(() => buildScopeTree([mod, a, b])).toThrowError(ScopeTreeInvariantError);
+      expect(() => buildScopeTree([mod, a, b])).toThrowError(/overlap/i);
+    });
+
+    it('accepts sibling ranges that merely touch at the boundary', () => {
+      const mod = mkScope({ id: 'scope:m', parent: null, kind: 'Module', range: r(1, 0, 100, 0) });
+      const a = mkScope({
+        id: 'scope:a',
+        parent: 'scope:m',
+        kind: 'Block',
+        range: r(5, 0, 10, 0),
+      });
+      const b = mkScope({
+        id: 'scope:b',
+        parent: 'scope:m',
+        kind: 'Block',
+        range: r(10, 0, 15, 0), // touches a at 10:0 but does not overlap
+      });
+      expect(() => buildScopeTree([mod, a, b])).not.toThrow();
+    });
+
+    it('throws when parent and child live in different files', () => {
+      const mod = mkScope({
+        id: 'scope:m',
+        parent: null,
+        kind: 'Module',
+        range: r(1, 0, 100, 0),
+        filePath: 'a.ts',
+      });
+      const fn = mkScope({
+        id: 'scope:f',
+        parent: 'scope:m',
+        kind: 'Function',
+        range: r(5, 0, 10, 0),
+        filePath: 'b.ts',
+      });
+      expect(() => buildScopeTree([mod, fn])).toThrowError(ScopeTreeInvariantError);
+      expect(() => buildScopeTree([mod, fn])).toThrowError(/filePath/i);
+    });
+
+    it('throws on duplicate scope ids', () => {
+      const a = mkScope({ id: 'scope:dup', parent: null, kind: 'Module', range: r(1, 0, 10, 0) });
+      const b = mkScope({ id: 'scope:dup', parent: null, kind: 'Module', range: r(1, 0, 10, 0) });
+      expect(() => buildScopeTree([a, b])).toThrowError(ScopeTreeInvariantError);
+    });
+  });
+});
diff --git a/gitnexus/test/unit/scope-resolution/shadow-harness.test.ts b/gitnexus/test/unit/scope-resolution/shadow-harness.test.ts
new file mode 100644
index 000000000..c6770c82d
--- /dev/null
+++ b/gitnexus/test/unit/scope-resolution/shadow-harness.test.ts
@@ -0,0 +1,290 @@
+/**
+ * Unit tests for `shadow-harness` (RFC #909 Ring 2 PKG #923).
+ *
+ * Covers flag detection, record accumulation, aggregation, and JSON
+ * persistence (real fs in a per-test tmpdir).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  EvidenceWeights,
+  SupportedLanguages,
+  type Resolution,
+  type ShadowCallsite,
+  type SymbolDefinition,
+} from 'gitnexus-shared';
+import {
+  createShadowHarness,
+  type PersistedShadowReport,
+  type ShadowHarness,
+} from '../../../src/core/ingestion/shadow-harness.js';
+
+// ─── Env isolation — GITNEXUS_SHADOW_MODE bleeds between tests otherwise ──
+
+let savedEnv: string | undefined;
+beforeEach(() => {
+  savedEnv = process.env['GITNEXUS_SHADOW_MODE'];
+  delete process.env['GITNEXUS_SHADOW_MODE'];
+});
+afterEach(() => {
+  if (savedEnv === undefined) delete process.env['GITNEXUS_SHADOW_MODE'];
+  else process.env['GITNEXUS_SHADOW_MODE'] = savedEnv;
+});
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────
+
+const callsite = (filePath = 'a.ts', line = 1): ShadowCallsite => ({
+  filePath,
+  range: { startLine: line, startCol: 0, endLine: line, endCol: 10 },
+});
+
+const def = (nodeId: string): SymbolDefinition => ({
+  nodeId,
+  filePath: 'x.ts',
+  type: 'Class',
+});
+
+const resolution = (nodeId: string): Resolution => ({
+  def: def(nodeId),
+  confidence: EvidenceWeights.local,
+  evidence: [{ kind: 'local', weight: EvidenceWeights.local }],
+});
+
+function enable(): void {
+  process.env['GITNEXUS_SHADOW_MODE'] = 'true';
+}
+
+function freshHarness(): ShadowHarness {
+  return createShadowHarness();
+}
+
+// ─── Flag detection ───────────────────────────────────────────────────────
+
+describe('createShadowHarness: enabled flag', () => {
+  it('is disabled by default (no env var set)', () => {
+    expect(freshHarness().enabled).toBe(false);
+  });
+
+  it("is enabled when GITNEXUS_SHADOW_MODE is 'true' / '1' / 'yes' / case-insensitive", () => {
+    for (const value of ['true', '1', 'yes', 'TRUE', '  Yes  ']) {
+      process.env['GITNEXUS_SHADOW_MODE'] = value;
+      expect(freshHarness().enabled).toBe(true);
+    }
+  });
+
+  it('stays disabled for falsy-looking or typo values', () => {
+    for (const value of ['', 'false', '0', 'off', 'tru']) {
+      process.env['GITNEXUS_SHADOW_MODE'] = value;
+      expect(freshHarness().enabled).toBe(false);
+    }
+  });
+
+  it('record() is a no-op when disabled', () => {
+    const h = freshHarness(); // disabled
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    expect(h.size()).toBe(0);
+  });
+
+  it('does NOT re-check the env var per call (constructed-once semantics)', () => {
+    const h = freshHarness(); // disabled at construction
+    process.env['GITNEXUS_SHADOW_MODE'] = 'true'; // flip AFTER construction
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    // Still disabled — the harness captured its `enabled` at construction.
+    expect(h.size()).toBe(0);
+  });
+});
+
+// ─── Record + snapshot ────────────────────────────────────────────────────
+
+describe('record + snapshot', () => {
+  it('accumulates records across languages', () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    h.record({
+      language: SupportedLanguages.TypeScript,
+      callsite: callsite('b.ts'),
+      legacy: [resolution('def:b')],
+      newResult: [],
+      primary: 'registry',
+    });
+    expect(h.size()).toBe(2);
+  });
+
+  it('snapshot reports per-language rows with correct outcomes', () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite('a.py', 2),
+      legacy: [resolution('def:b')],
+      newResult: [],
+      primary: 'legacy',
+    });
+    const report = h.snapshot(new Date('2026-04-18T00:00:00Z'));
+    expect(report.perLanguage).toHaveLength(1);
+    const py = report.perLanguage[0]!;
+    expect(py.language).toBe(SupportedLanguages.Python);
+    expect(py.totalCalls).toBe(2);
+    expect(py.bothAgree).toBe(1);
+    expect(py.onlyLegacy).toBe(1);
+  });
+
+  it('snapshot is deterministic across repeated calls', () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    const now = new Date('2026-04-18T12:00:00Z');
+    const a = h.snapshot(now);
+    const b = h.snapshot(now);
+    expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+  });
+
+  it('clear() resets the accumulator and primaryByLanguage', async () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'registry',
+    });
+    expect(h.size()).toBe(1);
+    h.clear();
+    expect(h.size()).toBe(0);
+    // Verify primary is also cleared: persist after a fresh record with a
+    // different primary should reflect the new value only.
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite('a.py'),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'gn-sh-clear-'));
+    try {
+      await h.persist(dir);
+      const payload = JSON.parse(fs.readFileSync(path.join(dir, 'latest.json'), 'utf8'));
+      expect(payload.primaryByLanguage.python).toBe('legacy');
+    } finally {
+      await fsp.rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+// ─── Persistence ──────────────────────────────────────────────────────────
+
+describe('persist', () => {
+  let tmpDir: string;
+  beforeEach(async () => {
+    tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'gn-shadow-harness-'));
+  });
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('creates outputDir if it does not exist', async () => {
+    enable();
+    const h = freshHarness();
+    const nested = path.join(tmpDir, 'nested', 'a', 'b');
+    await h.persist(nested);
+    expect(fs.existsSync(nested)).toBe(true);
+    expect(fs.existsSync(path.join(nested, 'latest.json'))).toBe(true);
+  });
+
+  it('writes BOTH a timestamped file and latest.json with the same payload', async () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.Python,
+      callsite: callsite(),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'legacy',
+    });
+    const perRunPath = await h.persist(tmpDir, new Date('2026-04-18T12:34:56Z'));
+    const latestPath = path.join(tmpDir, 'latest.json');
+
+    expect(fs.existsSync(perRunPath)).toBe(true);
+    expect(fs.existsSync(latestPath)).toBe(true);
+    expect(fs.readFileSync(perRunPath, 'utf8')).toBe(fs.readFileSync(latestPath, 'utf8'));
+  });
+
+  it('persisted payload matches the schema v1 shape', async () => {
+    enable();
+    const h = freshHarness();
+    h.record({
+      language: SupportedLanguages.TypeScript,
+      callsite: callsite('a.ts'),
+      legacy: [resolution('def:a')],
+      newResult: [resolution('def:a')],
+      primary: 'registry',
+    });
+    const now = new Date('2026-04-18T00:00:00Z');
+    await h.persist(tmpDir, now);
+    const payload: PersistedShadowReport = JSON.parse(
+      fs.readFileSync(path.join(tmpDir, 'latest.json'), 'utf8'),
+    );
+    expect(payload.schemaVersion).toBe(1);
+    expect(payload.runId).toMatch(/^\d{8}-\d{6}-[0-9a-f]{8}$/);
+    expect(payload.generatedAt).toBe('2026-04-18T00:00:00.000Z');
+    expect(payload.primaryByLanguage.typescript).toBe('registry');
+    expect(payload.report.overall.totalCalls).toBe(1);
+    expect(payload.report.overall.bothAgree).toBe(1);
+  });
+
+  it('runId embeds the run timestamp for chronological sorting', async () => {
+    enable();
+    const h1 = freshHarness();
+    const h2 = freshHarness();
+    const p1 = await h1.persist(tmpDir, new Date('2026-04-18T00:00:00Z'));
+    const p2 = await h2.persist(tmpDir, new Date('2026-04-18T01:00:00Z'));
+    // Timestamp prefix means the second file sorts after the first.
+    expect(path.basename(p2) > path.basename(p1)).toBe(true);
+  });
+
+  it('persists an empty report gracefully (no records, no error)', async () => {
+    enable();
+    const h = freshHarness();
+    await h.persist(tmpDir);
+    const payload = JSON.parse(fs.readFileSync(path.join(tmpDir, 'latest.json'), 'utf8'));
+    expect(payload.report.overall.totalCalls).toBe(0);
+    expect(payload.report.perLanguage).toEqual([]);
+  });
+});
diff --git a/gitnexus/test/unit/semantic-chunk-search.test.ts b/gitnexus/test/unit/semantic-chunk-search.test.ts
new file mode 100644
index 000000000..6660d6917
--- /dev/null
+++ b/gitnexus/test/unit/semantic-chunk-search.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it, vi } from 'vitest';
+import { collectBestChunks } from '../../src/core/embeddings/types.js';
+
+describe('collectBestChunks', () => {
+  it('keeps fetching until enough unique nodeIds are available', async () => {
+    const rows = [
+      ...Array.from({ length: 6 }, (_, i) => ({
+        nodeId: 'Function:a',
+        chunkIndex: i,
+        startLine: 10 + i,
+        endLine: 11 + i,
+        distance: 0.1 + i * 0.01,
+      })),
+      ...Array.from({ length: 6 }, (_, i) => ({
+        nodeId: 'Function:b',
+        chunkIndex: i,
+        startLine: 20 + i,
+        endLine: 21 + i,
+        distance: 0.2 + i * 0.01,
+      })),
+      {
+        nodeId: 'Function:c',
+        chunkIndex: 0,
+        startLine: 30,
+        endLine: 31,
+        distance: 0.3,
+      },
+      {
+        nodeId: 'Function:d',
+        chunkIndex: 0,
+        startLine: 40,
+        endLine: 41,
+        distance: 0.4,
+      },
+    ];
+
+    const fetchRows = vi.fn(async (fetchLimit: number) => rows.slice(0, fetchLimit));
+
+    const bestChunks = await collectBestChunks(3, fetchRows);
+
+    expect(fetchRows).toHaveBeenCalledTimes(2);
+    expect(fetchRows).toHaveBeenNthCalledWith(1, 12);
+    expect(fetchRows).toHaveBeenNthCalledWith(2, 24);
+    expect(Array.from(bestChunks.keys()).slice(0, 3)).toEqual([
+      'Function:a',
+      'Function:b',
+      'Function:c',
+    ]);
+  });
+
+  it('continues fetching beyond the default 200-row window when unique nodes are still missing', async () => {
+    const rows = [
+      ...Array.from({ length: 200 }, (_, i) => ({
+        nodeId: i < 120 ? 'Function:a' : 'Function:b',
+        chunkIndex: i,
+        startLine: i + 1,
+        endLine: i + 2,
+        distance: 0.01 + i * 0.001,
+      })),
+      {
+        nodeId: 'Function:c',
+        chunkIndex: 0,
+        startLine: 500,
+        endLine: 501,
+        distance: 0.5,
+      },
+      {
+        nodeId: 'Function:d',
+        chunkIndex: 0,
+        startLine: 600,
+        endLine: 601,
+        distance: 0.6,
+      },
+      {
+        nodeId: 'Function:e',
+        chunkIndex: 0,
+        startLine: 700,
+        endLine: 701,
+        distance: 0.7,
+      },
+    ];
+
+    const fetchRows = vi.fn(async (fetchLimit: number) => rows.slice(0, fetchLimit));
+
+    const bestChunks = await collectBestChunks(5, fetchRows);
+
+    expect(fetchRows).toHaveBeenCalledTimes(6);
+    expect(fetchRows).toHaveBeenNthCalledWith(1, 20);
+    expect(fetchRows).toHaveBeenNthCalledWith(2, 40);
+    expect(fetchRows).toHaveBeenNthCalledWith(3, 80);
+    expect(fetchRows).toHaveBeenNthCalledWith(4, 160);
+    expect(fetchRows).toHaveBeenNthCalledWith(5, 200);
+    expect(fetchRows).toHaveBeenNthCalledWith(6, 400);
+    expect(Array.from(bestChunks.keys())).toEqual([
+      'Function:a',
+      'Function:b',
+      'Function:c',
+      'Function:d',
+      'Function:e',
+    ]);
+  });
+
+  it('stops when the vector search is exhausted before reaching the limit', async () => {
+    const rows = [
+      {
+        nodeId: 'Function:a',
+        chunkIndex: 0,
+        startLine: 1,
+        endLine: 2,
+        distance: 0.1,
+      },
+      {
+        nodeId: 'Function:a',
+        chunkIndex: 1,
+        startLine: 3,
+        endLine: 4,
+        distance: 0.2,
+      },
+      {
+        nodeId: 'Function:b',
+        chunkIndex: 0,
+        startLine: 5,
+        endLine: 6,
+        distance: 0.3,
+      },
+    ];
+
+    const fetchRows = vi.fn(async (_fetchLimit: number) => rows);
+
+    const bestChunks = await collectBestChunks(5, fetchRows);
+
+    expect(fetchRows).toHaveBeenCalledTimes(1);
+    expect(Array.from(bestChunks.keys())).toEqual(['Function:a', 'Function:b']);
+  });
+
+  it('jumps to and continues past the 200-row window when needed for large limits', async () => {
+    const rows = [
+      ...Array.from({ length: 200 }, (_, i) => ({
+        nodeId: `Function:${Math.floor(i / 50)}`,
+        chunkIndex: i,
+        startLine: i + 1,
+        endLine: i + 2,
+        distance: 0.01 + i * 0.001,
+      })),
+      ...Array.from({ length: 60 }, (_, i) => ({
+        nodeId: `Function:extra-${i}`,
+        chunkIndex: 0,
+        startLine: 300 + i,
+        endLine: 301 + i,
+        distance: 1 + i * 0.001,
+      })),
+    ];
+
+    const fetchRows = vi.fn(async (fetchLimit: number) => rows.slice(0, fetchLimit));
+
+    const bestChunks = await collectBestChunks(60, fetchRows);
+
+    expect(fetchRows).toHaveBeenNthCalledWith(1, 240);
+    expect(fetchRows).toHaveBeenNthCalledWith(2, 480);
+    expect(bestChunks.size).toBe(60);
+  });
+});
diff --git a/gitnexus/test/unit/shadow/aggregate.test.ts b/gitnexus/test/unit/shadow/aggregate.test.ts
new file mode 100644
index 000000000..00fb44652
--- /dev/null
+++ b/gitnexus/test/unit/shadow/aggregate.test.ts
@@ -0,0 +1,234 @@
+/**
+ * Unit tests for `aggregateDiffs` (RFC #909 Ring 2 SHARED #918).
+ *
+ * Covers bucketing by language, parity math (incl. zero-resolved edge),
+ * evidence-kind breakdown, and stable sort order on the output rows.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  aggregateDiffs,
+  SupportedLanguages,
+  type LanguageParityRow,
+  type ResolutionEvidence,
+  type ShadowAgreement,
+  type ShadowDiff,
+} from 'gitnexus-shared';
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const FIXED_NOW = new Date('2026-04-18T12:00:00.000Z');
+
+const makeDiff = (
+  agreement: ShadowAgreement,
+  evidenceKinds: readonly ResolutionEvidence['kind'][] = [],
+): ShadowDiff => ({
+  callsite: { filePath: 'src/x.ts', line: 1, col: 0, calledName: 'foo' },
+  legacy: null,
+  newResult: null,
+  agreement,
+  evidenceDelta: evidenceKinds.map((kind) => ({ kind, weight: 0.3 })),
+});
+
+const entry = (language: SupportedLanguages, diff: ShadowDiff) => ({ language, diff });
+
+const findRow = (
+  rows: readonly LanguageParityRow[],
+  language: SupportedLanguages,
+): LanguageParityRow => {
+  const row = rows.find((r) => r.language === language);
+  if (!row) throw new Error(`no row for ${language}`);
+  return row;
+};
+
+// ─── Empty input ────────────────────────────────────────────────────────────
+
+describe('aggregateDiffs — empty input', () => {
+  it('returns empty perLanguage, zeroed overall, generatedAt populated', () => {
+    const report = aggregateDiffs([], FIXED_NOW);
+    expect(report.perLanguage).toEqual([]);
+    expect(report.overall).toEqual({
+      totalCalls: 0,
+      bothAgree: 0,
+      onlyLegacy: 0,
+      onlyNew: 0,
+      bothDisagree: 0,
+      bothEmpty: 0,
+      parity: 0,
+    });
+    expect(report.generatedAt).toBe('2026-04-18T12:00:00.000Z');
+  });
+});
+
+// ─── Single language, single outcome ────────────────────────────────────────
+
+describe('aggregateDiffs — single language', () => {
+  it('all both-agree → parity = 1.0', () => {
+    const diffs = [
+      entry(SupportedLanguages.Python, makeDiff('both-agree')),
+      entry(SupportedLanguages.Python, makeDiff('both-agree')),
+      entry(SupportedLanguages.Python, makeDiff('both-agree')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    expect(report.perLanguage).toHaveLength(1);
+    const row = findRow(report.perLanguage, SupportedLanguages.Python);
+    expect(row).toMatchObject({
+      language: SupportedLanguages.Python,
+      totalCalls: 3,
+      bothAgree: 3,
+      onlyLegacy: 0,
+      onlyNew: 0,
+      bothDisagree: 0,
+      bothEmpty: 0,
+      parity: 1,
+    });
+  });
+
+  it('mixed outcomes → parity excludes both-empty from denominator', () => {
+    const diffs = [
+      entry(SupportedLanguages.TypeScript, makeDiff('both-agree')),
+      entry(SupportedLanguages.TypeScript, makeDiff('both-agree')),
+      entry(SupportedLanguages.TypeScript, makeDiff('only-legacy', ['global-name'])),
+      entry(SupportedLanguages.TypeScript, makeDiff('only-new', ['local'])),
+      entry(SupportedLanguages.TypeScript, makeDiff('both-disagree', ['import'])),
+      entry(SupportedLanguages.TypeScript, makeDiff('both-empty')),
+      entry(SupportedLanguages.TypeScript, makeDiff('both-empty')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    const row = findRow(report.perLanguage, SupportedLanguages.TypeScript);
+    expect(row.totalCalls).toBe(7);
+    expect(row.bothAgree).toBe(2);
+    expect(row.onlyLegacy).toBe(1);
+    expect(row.onlyNew).toBe(1);
+    expect(row.bothDisagree).toBe(1);
+    expect(row.bothEmpty).toBe(2);
+    // parity = bothAgree / (totalCalls - bothEmpty) = 2 / (7 - 2) = 0.4
+    expect(row.parity).toBeCloseTo(0.4, 10);
+  });
+
+  it('all both-empty → parity = 0 (not NaN)', () => {
+    const diffs = [
+      entry(SupportedLanguages.Java, makeDiff('both-empty')),
+      entry(SupportedLanguages.Java, makeDiff('both-empty')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    const row = findRow(report.perLanguage, SupportedLanguages.Java);
+    expect(row.totalCalls).toBe(2);
+    expect(row.bothEmpty).toBe(2);
+    expect(row.parity).toBe(0);
+    expect(Number.isNaN(row.parity)).toBe(false);
+  });
+});
+
+// ─── Multi-language ─────────────────────────────────────────────────────────
+
+describe('aggregateDiffs — multiple languages', () => {
+  it('buckets rows by language and sums overall column-wise', () => {
+    const diffs = [
+      entry(SupportedLanguages.Python, makeDiff('both-agree')),
+      entry(SupportedLanguages.Python, makeDiff('both-disagree', ['local'])),
+      entry(SupportedLanguages.Ruby, makeDiff('both-agree')),
+      entry(SupportedLanguages.Ruby, makeDiff('both-agree')),
+      entry(SupportedLanguages.Ruby, makeDiff('only-new', ['type-binding'])),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    expect(report.perLanguage).toHaveLength(2);
+
+    const python = findRow(report.perLanguage, SupportedLanguages.Python);
+    expect(python.totalCalls).toBe(2);
+    expect(python.bothAgree).toBe(1);
+    expect(python.bothDisagree).toBe(1);
+    expect(python.parity).toBe(0.5);
+
+    const ruby = findRow(report.perLanguage, SupportedLanguages.Ruby);
+    expect(ruby.totalCalls).toBe(3);
+    expect(ruby.bothAgree).toBe(2);
+    expect(ruby.onlyNew).toBe(1);
+    expect(ruby.parity).toBeCloseTo(2 / 3, 10);
+
+    expect(report.overall).toEqual({
+      totalCalls: 5,
+      bothAgree: 3,
+      onlyLegacy: 0,
+      onlyNew: 1,
+      bothDisagree: 1,
+      bothEmpty: 0,
+      parity: 3 / 5,
+    });
+  });
+
+  it('perLanguage rows are sorted alphabetically by language value for stable output', () => {
+    const diffs = [
+      entry(SupportedLanguages.TypeScript, makeDiff('both-agree')),
+      entry(SupportedLanguages.C, makeDiff('both-agree')),
+      entry(SupportedLanguages.Python, makeDiff('both-agree')),
+      entry(SupportedLanguages.Java, makeDiff('both-agree')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    const ordered = report.perLanguage.map((r) => r.language);
+    // Alphabetical by enum VALUE: 'c' < 'java' < 'python' < 'typescript'
+    expect(ordered).toEqual([
+      SupportedLanguages.C,
+      SupportedLanguages.Java,
+      SupportedLanguages.Python,
+      SupportedLanguages.TypeScript,
+    ]);
+  });
+});
+
+// ─── Evidence breakdown ─────────────────────────────────────────────────────
+
+describe('aggregateDiffs — evidence breakdown', () => {
+  it('counts divergence evidence kinds across non-agreeing rows only', () => {
+    const diffs = [
+      entry(SupportedLanguages.Go, makeDiff('both-disagree', ['import', 'owner-match'])),
+      entry(SupportedLanguages.Go, makeDiff('only-legacy', ['import', 'global-name'])),
+      entry(SupportedLanguages.Go, makeDiff('only-new', ['local'])),
+      // both-agree contributes 0 to evidence breakdown regardless of any attached evidence
+      entry(SupportedLanguages.Go, makeDiff('both-agree', ['import'])),
+      // both-empty also contributes 0
+      entry(SupportedLanguages.Go, makeDiff('both-empty')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    const row = findRow(report.perLanguage, SupportedLanguages.Go);
+    expect(Array.from(row.evidenceBreakdown.entries())).toEqual([
+      ['global-name', 1],
+      ['import', 2],
+      ['local', 1],
+      ['owner-match', 1],
+    ]);
+  });
+
+  it('emits empty evidenceBreakdown when all calls agree or are empty', () => {
+    const diffs = [
+      entry(SupportedLanguages.Rust, makeDiff('both-agree')),
+      entry(SupportedLanguages.Rust, makeDiff('both-empty')),
+    ];
+    const report = aggregateDiffs(diffs, FIXED_NOW);
+    const row = findRow(report.perLanguage, SupportedLanguages.Rust);
+    expect(row.evidenceBreakdown.size).toBe(0);
+  });
+});
+
+// ─── Determinism ────────────────────────────────────────────────────────────
+
+describe('aggregateDiffs — determinism', () => {
+  it('injected `now` is used verbatim for generatedAt', () => {
+    const t = new Date('2030-01-01T00:00:00.000Z');
+    const report = aggregateDiffs([], t);
+    expect(report.generatedAt).toBe('2030-01-01T00:00:00.000Z');
+  });
+
+  it('same input produces byte-identical JSON (stable keys + sort)', () => {
+    const diffs = [
+      entry(SupportedLanguages.Python, makeDiff('both-disagree', ['local', 'import'])),
+      entry(SupportedLanguages.Java, makeDiff('both-agree')),
+    ];
+    const a = aggregateDiffs(diffs, FIXED_NOW);
+    const b = aggregateDiffs(diffs, FIXED_NOW);
+    // Round-trip through JSON to drop Map identity and force structural comparison.
+    const toJson = (r: typeof a): string =>
+      JSON.stringify(r, (_key, v: unknown) => (v instanceof Map ? Object.fromEntries(v) : v));
+    expect(toJson(a)).toBe(toJson(b));
+  });
+});
diff --git a/gitnexus/test/unit/shadow/diff.test.ts b/gitnexus/test/unit/shadow/diff.test.ts
new file mode 100644
index 000000000..e9baa606f
--- /dev/null
+++ b/gitnexus/test/unit/shadow/diff.test.ts
@@ -0,0 +1,192 @@
+/**
+ * Unit tests for `diffResolutions` (RFC #909 Ring 2 SHARED #918).
+ *
+ * Pins the 5 `ShadowAgreement` outcomes and the symmetric-by-kind evidence-
+ * delta contract. Inputs are pure data fixtures — no real pipeline state.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  diffResolutions,
+  type Resolution,
+  type ResolutionEvidence,
+  type ShadowCallsite,
+  type SymbolDefinition,
+} from 'gitnexus-shared';
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const callsite: ShadowCallsite = {
+  filePath: 'src/app.ts',
+  line: 42,
+  col: 8,
+  calledName: 'save',
+};
+
+const makeDef = (nodeId: string): SymbolDefinition => ({
+  nodeId,
+  filePath: 'src/models.ts',
+  type: 'Method',
+});
+
+const makeEvidence = (kind: ResolutionEvidence['kind'], weight = 0.5): ResolutionEvidence => ({
+  kind,
+  weight,
+});
+
+const makeResolution = (
+  nodeId: string,
+  evidenceKinds: readonly ResolutionEvidence['kind'][],
+): Resolution => ({
+  def: makeDef(nodeId),
+  confidence: Math.min(1, evidenceKinds.length * 0.3),
+  evidence: evidenceKinds.map((k) => makeEvidence(k)),
+});
+
+// ─── Agreement outcomes ─────────────────────────────────────────────────────
+
+describe('diffResolutions — agreement outcomes', () => {
+  it("both arrays empty → 'both-empty' with no evidence delta", () => {
+    const result = diffResolutions(callsite, [], []);
+    expect(result.agreement).toBe('both-empty');
+    expect(result.evidenceDelta).toEqual([]);
+    expect(result.legacy).toBeNull();
+    expect(result.newResult).toBeNull();
+  });
+
+  it("identical top DefIds → 'both-agree' with empty evidence delta", () => {
+    const legacy = [makeResolution('def:User.save', ['local', 'owner-match'])];
+    const next = [makeResolution('def:User.save', ['local', 'kind-match'])];
+    const result = diffResolutions(callsite, legacy, next);
+    expect(result.agreement).toBe('both-agree');
+    expect(result.evidenceDelta).toEqual([]);
+    expect(result.legacy).toBe(legacy[0]);
+    expect(result.newResult).toBe(next[0]);
+  });
+
+  it("legacy empty, new non-empty → 'only-new' with new's evidence as delta", () => {
+    const next = [makeResolution('def:User.save', ['local', 'owner-match'])];
+    const result = diffResolutions(callsite, [], next);
+    expect(result.agreement).toBe('only-new');
+    expect(result.evidenceDelta).toEqual(next[0].evidence);
+    expect(result.legacy).toBeNull();
+    expect(result.newResult).toBe(next[0]);
+  });
+
+  it("legacy non-empty, new empty → 'only-legacy' with legacy's evidence as delta", () => {
+    const legacy = [makeResolution('def:User.save', ['global-name'])];
+    const result = diffResolutions(callsite, legacy, []);
+    expect(result.agreement).toBe('only-legacy');
+    expect(result.evidenceDelta).toEqual(legacy[0].evidence);
+    expect(result.legacy).toBe(legacy[0]);
+    expect(result.newResult).toBeNull();
+  });
+
+  it("different top DefIds → 'both-disagree'", () => {
+    const legacy = [makeResolution('def:ModelA.save', ['global-name'])];
+    const next = [makeResolution('def:ModelB.save', ['local'])];
+    const result = diffResolutions(callsite, legacy, next);
+    expect(result.agreement).toBe('both-disagree');
+    expect(result.legacy).toBe(legacy[0]);
+    expect(result.newResult).toBe(next[0]);
+  });
+});
+
+// ─── Evidence delta — symmetric difference by `kind` ────────────────────────
+
+describe('diffResolutions — evidence delta (symmetric-by-kind)', () => {
+  it("'both-disagree' with disjoint evidence → delta contains both sides' kinds", () => {
+    const legacy = [makeResolution('def:A', ['global-name'])];
+    const next = [makeResolution('def:B', ['local', 'owner-match'])];
+    const result = diffResolutions(callsite, legacy, next);
+    expect(result.evidenceDelta.map((e) => e.kind)).toEqual([
+      'global-name',
+      'local',
+      'owner-match',
+    ]);
+  });
+
+  it("'both-disagree' with overlapping kinds → overlapping kinds removed from delta", () => {
+    const legacy = [makeResolution('def:A', ['local', 'scope-chain', 'global-name'])];
+    const next = [makeResolution('def:B', ['local', 'import', 'owner-match'])];
+    const result = diffResolutions(callsite, legacy, next);
+    // 'local' is on both sides → dropped
+    // Remaining: legacy-only ['scope-chain', 'global-name'], then new-only ['import', 'owner-match']
+    expect(result.evidenceDelta.map((e) => e.kind)).toEqual([
+      'scope-chain',
+      'global-name',
+      'import',
+      'owner-match',
+    ]);
+  });
+
+  it("'both-disagree' with fully overlapping kinds → empty evidence delta", () => {
+    const legacy = [makeResolution('def:A', ['local', 'owner-match'])];
+    const next = [makeResolution('def:B', ['owner-match', 'local'])];
+    const result = diffResolutions(callsite, legacy, next);
+    // Same kind set, different order → symmetric difference is empty
+    expect(result.evidenceDelta).toEqual([]);
+    expect(result.agreement).toBe('both-disagree'); // agreement still disagrees because nodeIds differ
+  });
+
+  it('differing weights on the same kind → NOT a delta (keyed on kind only)', () => {
+    const legacy = [
+      {
+        def: makeDef('def:A'),
+        confidence: 0.9,
+        evidence: [{ kind: 'local' as const, weight: 0.55 }],
+      },
+    ];
+    const next = [
+      {
+        def: makeDef('def:B'),
+        confidence: 0.1,
+        evidence: [{ kind: 'local' as const, weight: 0.25 }],
+      },
+    ];
+    const result = diffResolutions(callsite, legacy, next);
+    expect(result.agreement).toBe('both-disagree');
+    expect(result.evidenceDelta).toEqual([]);
+  });
+});
+
+// ─── Metadata + ordering ────────────────────────────────────────────────────
+
+describe('diffResolutions — metadata + ordering', () => {
+  it('ignores resolutions beyond index 0 (top match only)', () => {
+    const legacy = [
+      makeResolution('def:User.save', ['local']),
+      makeResolution('def:other', ['global-name']),
+    ];
+    const next = [
+      makeResolution('def:User.save', ['local']),
+      // The 2nd entry is here to verify index-0 isolation — the only kind
+      // requirement is that it be a valid `ResolutionEvidence.kind` so the
+      // fixture is type-correct. `'global-name'` is a real kind that
+      // `diffResolutions` never treats specially.
+      makeResolution('def:yet-another', ['global-name']),
+    ];
+    const result = diffResolutions(callsite, legacy, next);
+    expect(result.agreement).toBe('both-agree');
+  });
+
+  it('preserves callsite verbatim', () => {
+    const result = diffResolutions(callsite, [], []);
+    expect(result.callsite).toBe(callsite);
+  });
+
+  it("'both-disagree' delta order: legacy-only first (input order), then new-only", () => {
+    const legacy = [makeResolution('def:A', ['owner-match', 'scope-chain', 'kind-match'])];
+    const next = [makeResolution('def:B', ['import', 'owner-match', 'arity-match'])];
+    const result = diffResolutions(callsite, legacy, next);
+    // 'owner-match' overlaps → dropped
+    // legacy-only in original order: ['scope-chain', 'kind-match']
+    // then new-only in original order: ['import', 'arity-match']
+    expect(result.evidenceDelta.map((e) => e.kind)).toEqual([
+      'scope-chain',
+      'kind-match',
+      'import',
+      'arity-match',
+    ]);
+  });
+});
diff --git a/gitnexus/test/unit/symbol-table.test.ts b/gitnexus/test/unit/symbol-table.test.ts
index 7bf0d7b4b..28fc8e08b 100644
--- a/gitnexus/test/unit/symbol-table.test.ts
+++ b/gitnexus/test/unit/symbol-table.test.ts
@@ -1678,6 +1678,230 @@ describe('lookupMethodByOwnerWithMRO', () => {
     expect(result).toBeDefined();
     expect(result!.nodeId).toBe('method:User:getName');
   });
+
+  // ── ruby-mixin: kind-aware MRO walk (prepend > self > include) ────
+  //
+  // Ruby's `'ruby-mixin'` strategy is the only one that does NOT short-circuit
+  // on direct-owner lookup first — prepend providers must beat the class's
+  // own method of the same name. These tests exercise the walk order directly
+  // through lookupMethodByOwnerWithMRO rather than through the full pipeline.
+
+  it("ruby-mixin: prepend provider beats class's own method (shadow)", () => {
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/prep.rb', 'PrependedOverride', 'trait:PrependedOverride', 'Trait');
+    ctx.model.symbols.add('lib/account.rb', 'serialize', 'method:Account:serialize', 'Method', {
+      returnType: 'String',
+      ownerId: 'class:Account',
+    });
+    ctx.model.symbols.add(
+      'lib/prep.rb',
+      'serialize',
+      'method:PrependedOverride:serialize',
+      'Method',
+      { returnType: 'String', ownerId: 'trait:PrependedOverride' },
+    );
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'PrependedOverride',
+        kind: 'prepend',
+      },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    const result = lookupMethodByOwnerWithMRO(
+      'class:Account',
+      'serialize',
+      map,
+      ctx.model,
+      'ruby-mixin',
+    );
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:PrependedOverride:serialize');
+  });
+
+  it("ruby-mixin: class's own method wins over include provider (shadow)", () => {
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/mixin.rb', 'Greetable', 'trait:Greetable', 'Trait');
+    ctx.model.symbols.add('lib/account.rb', 'greet', 'method:Account:greet', 'Method', {
+      returnType: 'String',
+      ownerId: 'class:Account',
+    });
+    ctx.model.symbols.add('lib/mixin.rb', 'greet', 'method:Greetable:greet', 'Method', {
+      returnType: 'String',
+      ownerId: 'trait:Greetable',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'Greetable',
+        kind: 'include',
+      },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    const result = lookupMethodByOwnerWithMRO(
+      'class:Account',
+      'greet',
+      map,
+      ctx.model,
+      'ruby-mixin',
+    );
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:Account:greet');
+  });
+
+  it('ruby-mixin: include provider used when class lacks the method', () => {
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/mixin.rb', 'Greetable', 'trait:Greetable', 'Trait');
+    ctx.model.symbols.add('lib/mixin.rb', 'greet', 'method:Greetable:greet', 'Method', {
+      returnType: 'String',
+      ownerId: 'trait:Greetable',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'Greetable',
+        kind: 'include',
+      },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    const result = lookupMethodByOwnerWithMRO(
+      'class:Account',
+      'greet',
+      map,
+      ctx.model,
+      'ruby-mixin',
+    );
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:Greetable:greet');
+  });
+
+  it('ruby-mixin: extend providers excluded from instance-dispatch walk', () => {
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/logger.rb', 'LoggerMixin', 'trait:LoggerMixin', 'Trait');
+    ctx.model.symbols.add('lib/logger.rb', 'log', 'method:LoggerMixin:log', 'Method', {
+      returnType: 'void',
+      ownerId: 'trait:LoggerMixin',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'LoggerMixin',
+        kind: 'extend',
+      },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    // Instance dispatch: `extend` providers MUST NOT appear in the walk.
+    // Result is undefined — Account has no instance `log`.
+    const result = lookupMethodByOwnerWithMRO('class:Account', 'log', map, ctx.model, 'ruby-mixin');
+    expect(result).toBeUndefined();
+  });
+
+  it('ruby-mixin: singleton ancestryOverride routes to extend provider', () => {
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/logger.rb', 'LoggerMixin', 'trait:LoggerMixin', 'Trait');
+    ctx.model.symbols.add('lib/logger.rb', 'log', 'method:LoggerMixin:log', 'Method', {
+      returnType: 'void',
+      ownerId: 'trait:LoggerMixin',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'LoggerMixin',
+        kind: 'extend',
+      },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    // Singleton dispatch: caller pre-computes the singleton ancestry and
+    // passes it as ancestryOverride. The walker scans it linearly without
+    // the prepend/direct/include partition.
+    const singletonAncestry = map.getSingletonAncestry('class:Account').map((e) => e.parentId);
+    const result = lookupMethodByOwnerWithMRO(
+      'class:Account',
+      'log',
+      map,
+      ctx.model,
+      'ruby-mixin',
+      undefined,
+      singletonAncestry,
+    );
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:LoggerMixin:log');
+  });
+
+  it('ruby-mixin: transitive mixin — module provides method via an included module', () => {
+    // class Account; include Outer; end
+    // module Outer; include Inner; end
+    // module Inner; def helper; end; end
+    ctx.model.symbols.add('lib/account.rb', 'Account', 'class:Account', 'Class');
+    ctx.model.symbols.add('lib/outer.rb', 'Outer', 'trait:Outer', 'Trait');
+    ctx.model.symbols.add('lib/inner.rb', 'Inner', 'trait:Inner', 'Trait');
+    ctx.model.symbols.add('lib/inner.rb', 'helper', 'method:Inner:helper', 'Method', {
+      returnType: 'void',
+      ownerId: 'trait:Inner',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      {
+        filePath: 'lib/account.rb',
+        className: 'Account',
+        parentName: 'Outer',
+        kind: 'include',
+      },
+      { filePath: 'lib/outer.rb', className: 'Outer', parentName: 'Inner', kind: 'include' },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    const result = lookupMethodByOwnerWithMRO(
+      'class:Account',
+      'helper',
+      map,
+      ctx.model,
+      'ruby-mixin',
+    );
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:Inner:helper');
+  });
+
+  it('ruby-mixin: stacked prepends — last-prepended wins', () => {
+    // class A; prepend P1; prepend P2; end
+    // Ruby MRO places P2 ahead of P1; last-prepended is closest to self.
+    ctx.model.symbols.add('lib/a.rb', 'A', 'class:A', 'Class');
+    ctx.model.symbols.add('lib/p1.rb', 'P1', 'trait:P1', 'Trait');
+    ctx.model.symbols.add('lib/p2.rb', 'P2', 'trait:P2', 'Trait');
+    ctx.model.symbols.add('lib/p1.rb', 'foo', 'method:P1:foo', 'Method', {
+      returnType: 'String',
+      ownerId: 'trait:P1',
+    });
+    ctx.model.symbols.add('lib/p2.rb', 'foo', 'method:P2:foo', 'Method', {
+      returnType: 'String',
+      ownerId: 'trait:P2',
+    });
+
+    const heritage: ExtractedHeritage[] = [
+      { filePath: 'lib/a.rb', className: 'A', parentName: 'P1', kind: 'prepend' },
+      { filePath: 'lib/a.rb', className: 'A', parentName: 'P2', kind: 'prepend' },
+    ];
+    const map = buildHeritageMap(heritage, ctx);
+
+    const result = lookupMethodByOwnerWithMRO('class:A', 'foo', map, ctx.model, 'ruby-mixin');
+    expect(result).toBeDefined();
+    expect(result!.nodeId).toBe('method:P2:foo');
+  });
 });
 
 // ---------------------------------------------------------------------------
diff --git a/gitnexus/test/unit/text-generator.test.ts b/gitnexus/test/unit/text-generator.test.ts
new file mode 100644
index 000000000..28e16044d
--- /dev/null
+++ b/gitnexus/test/unit/text-generator.test.ts
@@ -0,0 +1,248 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateEmbeddingText,
+  truncateDescription,
+  extractDeclarationOnly,
+} from '../../src/core/embeddings/text-generator.js';
+import { isChunkableLabel } from '../../src/core/embeddings/types.js';
+import type { EmbeddableNode } from '../../src/core/embeddings/types.js';
+
+const baseNode: EmbeddableNode = {
+  id: 'Function:src/utils.ts:parseJSON',
+  name: 'parseJSON',
+  label: 'Function',
+  filePath: 'src/utils/parser.ts',
+  content: 'function parseJSON(text: string): Result<any> {\n  return JSON.parse(text);\n}',
+  startLine: 10,
+  endLine: 12,
+};
+
+describe('text-generator', () => {
+  describe('generateEmbeddingText', () => {
+    it('includes metadata header for Function', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        isExported: true,
+        repoName: 'backend-user-ms',
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Function: parseJSON');
+      expect(text).toContain('Repo: backend-user-ms');
+      expect(text).toContain('Path: src/utils/parser.ts');
+      expect(text).toContain('Export: true');
+      expect(text).toContain('function parseJSON');
+    });
+
+    it('includes Server line when serverName is set', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        repoName: 'backend-user-ms',
+        serverName: 'user-service',
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Server: user-service');
+    });
+
+    it('omits Server line when serverName is undefined', () => {
+      const text = generateEmbeddingText(baseNode, baseNode.content);
+      expect(text).not.toContain('Server:');
+    });
+
+    it('includes truncated description', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        description: 'This function parses JSON text and returns a typed result object.',
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('This function parses JSON text');
+    });
+
+    it('generates short node text for TypeAlias without chunking', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'TypeAlias',
+        name: 'Result',
+        content: 'type Result<T> = Success<T> | Error;',
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('TypeAlias: Result');
+      expect(text).toContain('type Result<T> = Success<T> | Error;');
+    });
+
+    it('generates Class text with AST-extracted method/field names', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'Class',
+        name: 'Parser',
+        methodNames: ['parseJSON', 'validate'],
+        fieldNames: ['options', 'cache'],
+        content: `class Parser {
+  options: ParserOptions;
+  private cache: Map<string, any>;
+  parseJSON(text: string) { return JSON.parse(text); }
+  validate() { return true; }
+}`,
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Class: Parser');
+      expect(text).toContain('Methods: parseJSON, validate');
+      expect(text).toContain('Properties: options, cache');
+      // Method bodies should NOT appear in declaration section
+      expect(text).not.toContain('return JSON.parse');
+      expect(text).not.toContain('return true');
+    });
+
+    it('generates Class text without method names when not provided', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'Class',
+        name: 'Parser',
+        content: `class Parser {
+  parse(input) { }
+}`,
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Class: Parser');
+      expect(text).not.toContain('Methods:');
+    });
+
+    it('generates Interface text with structural names and signatures', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'Interface',
+        name: 'Handler',
+        methodNames: ['handle', 'validate'],
+        fieldNames: ['name'],
+        content: `interface Handler {
+  handle(event: Event): void;
+  validate(input: string): boolean;
+  readonly name: string;
+}`,
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Interface: Handler');
+      expect(text).toContain('Methods: handle, validate');
+      expect(text).toContain('Properties: name');
+      expect(text).toContain('handle(event: Event): void;');
+      expect(text).toContain('readonly name: string;');
+    });
+
+    it('includes chunk body for structural node chunks', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'Class',
+        name: 'Parser',
+        methodNames: ['parseJSON', 'validate'],
+        fieldNames: ['options', 'cache'],
+        content: `class Parser {
+  options: ParserOptions;
+  cache: Map<string, any>;
+  parseJSON(text: string) { return JSON.parse(text); }
+  validate() { return true; }
+}`,
+      };
+      const chunkBody = `parseJSON(text: string) { return JSON.parse(text); }`;
+      const text = generateEmbeddingText(node, chunkBody);
+      expect(text).toContain('Class: Parser');
+      expect(text).toContain('Methods: parseJSON, validate');
+      expect(text).toContain('class Parser {');
+      expect(text).toContain('parseJSON(text: string) { return JSON.parse(text); }');
+    });
+  });
+
+  describe('Constructor label', () => {
+    it('is recognized as chunkable', () => {
+      expect(isChunkableLabel('Constructor')).toBe(true);
+    });
+
+    it('is recognized as embeddable', () => {
+      const node: EmbeddableNode = {
+        ...baseNode,
+        label: 'Constructor',
+        name: 'constructor',
+        content: 'constructor(private service: ApiClient) {\n  this.service = service;\n}',
+      };
+      const text = generateEmbeddingText(node, node.content);
+      expect(text).toContain('Constructor: constructor');
+      expect(text).toContain('this.service = service');
+    });
+  });
+
+  describe('extractDeclarationOnly', () => {
+    it('strips method bodies from TS class', () => {
+      const content = `class Foo {
+  prop1: string;
+  method1() {
+    if (x) { nested }
+  }
+  method2() { return 1; }
+}`;
+      const result = extractDeclarationOnly(content);
+      expect(result).toContain('class Foo {');
+      expect(result).toContain('prop1: string;');
+      expect(result).not.toContain('if (x)');
+      expect(result).not.toContain('return 1');
+    });
+
+    it('keeps single-line methods with semicolon (property initializers)', () => {
+      const content = `class Foo {
+  config = { timeout: 5000 };
+  count = 0;
+}`;
+      const result = extractDeclarationOnly(content);
+      expect(result).toContain('config = { timeout: 5000 };');
+      expect(result).toContain('count = 0;');
+    });
+
+    it('returns empty for non-brace languages (Python)', () => {
+      const content = `class User:
+    def __init__(self, name):
+        self.name = name`;
+      const result = extractDeclarationOnly(content);
+      expect(result).toBe('');
+    });
+
+    it('preserves all fields in Rust struct', () => {
+      const content = `struct User {
+    name: String,
+    age: u32,
+}`;
+      const result = extractDeclarationOnly(content);
+      expect(result).toContain('struct User {');
+      expect(result).toContain('name: String,');
+      expect(result).toContain('age: u32,');
+    });
+
+    it('preserves all lines in interface (no method bodies)', () => {
+      const content = `interface Handler {
+  handle(event: Event): void;
+  validate(input: string): boolean;
+}`;
+      const result = extractDeclarationOnly(content);
+      expect(result).toContain('interface Handler {');
+      expect(result).toContain('handle(event: Event): void;');
+      expect(result).toContain('validate(input: string): boolean;');
+    });
+  });
+
+  describe('truncateDescription', () => {
+    it('returns short text unchanged', () => {
+      expect(truncateDescription('short text', 150)).toBe('short text');
+    });
+
+    it('truncates at sentence boundary', () => {
+      const text = 'First sentence. Second sentence. Third very long sentence that goes on and on.';
+      const result = truncateDescription(text, 40);
+      expect(result).toContain('First sentence');
+      expect(result.length).toBeLessThan(text.length);
+    });
+
+    it('truncates at word boundary when no sentence end', () => {
+      const text =
+        'this is a long description without any sentence ending punctuation marks at all';
+      const result = truncateDescription(text, 30);
+      expect(result.length).toBeLessThanOrEqual(30);
+      expect(result.length).toBeLessThan(text.length);
+    });
+  });
+});
diff --git a/gitnexus/test/unit/tree-sitter-queries.test.ts b/gitnexus/test/unit/tree-sitter-queries.test.ts
index ffb207bdd..64212c25c 100644
--- a/gitnexus/test/unit/tree-sitter-queries.test.ts
+++ b/gitnexus/test/unit/tree-sitter-queries.test.ts
@@ -10,6 +10,7 @@ import {
   CSHARP_QUERIES,
   RUST_QUERIES,
   PHP_QUERIES,
+  RUBY_QUERIES,
   SWIFT_QUERIES,
   DART_QUERIES,
 } from '../../src/core/ingestion/tree-sitter-queries.js';
@@ -356,4 +357,77 @@ describe('tree-sitter queries', () => {
       expect(DART_QUERIES).toContain('function_expression_body');
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Variable/constant declaration capture tests
+  // ---------------------------------------------------------------------------
+
+  describe('Variable/constant declaration captures', () => {
+    it('TypeScript captures const/let as @definition.const', () => {
+      expect(TYPESCRIPT_QUERIES).toContain('@definition.const');
+      expect(TYPESCRIPT_QUERIES).toContain('lexical_declaration');
+    });
+
+    it('TypeScript captures var as @definition.variable', () => {
+      expect(TYPESCRIPT_QUERIES).toContain('@definition.variable');
+      expect(TYPESCRIPT_QUERIES).toContain('variable_declaration');
+    });
+
+    it('JavaScript captures const/let as @definition.const', () => {
+      expect(JAVASCRIPT_QUERIES).toContain('@definition.const');
+    });
+
+    it('JavaScript captures var as @definition.variable', () => {
+      expect(JAVASCRIPT_QUERIES).toContain('@definition.variable');
+    });
+
+    it('Python captures plain assignments as @definition.variable', () => {
+      expect(PYTHON_QUERIES).toContain('@definition.variable');
+    });
+
+    it('Go captures const_declaration and var_declaration', () => {
+      expect(GO_QUERIES).toContain('@definition.const');
+      expect(GO_QUERIES).toContain('@definition.variable');
+      expect(GO_QUERIES).toContain('short_var_declaration');
+    });
+
+    it('Java captures local_variable_declaration', () => {
+      expect(JAVA_QUERIES).toContain('local_variable_declaration');
+      expect(JAVA_QUERIES).toContain('@definition.variable');
+    });
+
+    it('C captures init_declarator as @definition.variable', () => {
+      expect(C_QUERIES).toContain('init_declarator');
+      expect(C_QUERIES).toContain('@definition.variable');
+    });
+
+    it('C++ captures init_declarator as @definition.variable', () => {
+      expect(CPP_QUERIES).toContain('init_declarator');
+      expect(CPP_QUERIES).toContain('@definition.variable');
+    });
+
+    it('C# captures local_declaration_statement', () => {
+      expect(CSHARP_QUERIES).toContain('local_declaration_statement');
+      expect(CSHARP_QUERIES).toContain('@definition.variable');
+    });
+
+    it('Rust retains const_item and static_item captures', () => {
+      expect(RUST_QUERIES).toContain('@definition.const');
+      expect(RUST_QUERIES).toContain('@definition.static');
+    });
+
+    it('PHP captures const_declaration', () => {
+      expect(PHP_QUERIES).toContain('const_declaration');
+      expect(PHP_QUERIES).toContain('@definition.const');
+    });
+
+    it('Ruby captures constant assignments', () => {
+      expect(RUBY_QUERIES).toContain('@definition.const');
+    });
+
+    it('Dart captures declaration as @definition.variable', () => {
+      expect(DART_QUERIES).toContain('(declaration');
+      expect(DART_QUERIES).toContain('@definition.variable');
+    });
+  });
 });
diff --git a/gitnexus/test/unit/type-env.test.ts b/gitnexus/test/unit/type-env.test.ts
index 27f449f91..dffbc047e 100644
--- a/gitnexus/test/unit/type-env.test.ts
+++ b/gitnexus/test/unit/type-env.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { buildTypeEnv, type TypeEnvironment } from '../../src/core/ingestion/type-env.js';
 import { BindingAccumulator } from '../../src/core/ingestion/binding-accumulator.js';
-import { type SymbolDefinition } from '../../src/core/ingestion/model/symbol-table.js';
+import { type SymbolDefinition } from 'gitnexus-shared';
 import {
   createSemanticModel,
   type SemanticModel,
diff --git a/gitnexus/test/unit/variable-extraction.test.ts b/gitnexus/test/unit/variable-extraction.test.ts
new file mode 100644
index 000000000..d40993e2c
--- /dev/null
+++ b/gitnexus/test/unit/variable-extraction.test.ts
@@ -0,0 +1,633 @@
+import { describe, it, expect } from 'vitest';
+import { createVariableExtractor } from '../../src/core/ingestion/variable-extractors/generic.js';
+import {
+  typescriptVariableConfig,
+  javascriptVariableConfig,
+} from '../../src/core/ingestion/variable-extractors/configs/typescript-javascript.js';
+import { pythonVariableConfig } from '../../src/core/ingestion/variable-extractors/configs/python.js';
+import { goVariableConfig } from '../../src/core/ingestion/variable-extractors/configs/go.js';
+import { rustVariableConfig } from '../../src/core/ingestion/variable-extractors/configs/rust.js';
+import {
+  cVariableConfig,
+  cppVariableConfig,
+} from '../../src/core/ingestion/variable-extractors/configs/c-cpp.js';
+import { rubyVariableConfig } from '../../src/core/ingestion/variable-extractors/configs/ruby.js';
+import type { VariableExtractorContext } from '../../src/core/ingestion/variable-types.js';
+import { SupportedLanguages } from '../../src/config/supported-languages.js';
+import Parser from 'tree-sitter';
+import TypeScript from 'tree-sitter-typescript';
+import Python from 'tree-sitter-python';
+import Go from 'tree-sitter-go';
+import Rust from 'tree-sitter-rust';
+import Cpp from 'tree-sitter-cpp';
+import C from 'tree-sitter-c';
+import Ruby from 'tree-sitter-ruby';
+
+const parser = new Parser();
+
+// ---------------------------------------------------------------------------
+// TypeScript config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — TypeScript', () => {
+  const extractor = createVariableExtractor(typescriptVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.ts',
+    language: SupportedLanguages.TypeScript,
+  };
+
+  it('extracts const declaration', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('const MAX_SIZE = 100;');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(true);
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MAX_SIZE');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+    expect(info!.visibility).toBe('private');
+  });
+
+  it('extracts let declaration as mutable', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('let counter = 0;');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(true);
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('counter');
+    expect(info!.isConst).toBe(false);
+    expect(info!.isMutable).toBe(true);
+  });
+
+  it('extracts typed const declaration', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('const name: string = "hello";');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('name');
+    expect(info!.type).toBe('string');
+    expect(info!.isConst).toBe(true);
+  });
+
+  it('detects export as public visibility', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('export const API_KEY = "abc";');
+    // export_statement wraps lexical_declaration
+    const exportStatement = tree.rootNode.child(0)!;
+    // The lexical_declaration is the child of export_statement
+    const declNode = exportStatement.namedChildren.find((c) => c.type === 'lexical_declaration');
+    expect(declNode).toBeDefined();
+    const info = extractor.extract(declNode!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('API_KEY');
+    expect(info!.visibility).toBe('public');
+  });
+
+  it('rejects non-variable nodes', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('function foo() {}');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(false);
+    expect(extractor.extract(node, ctx)).toBeNull();
+  });
+
+  it('extracts var declaration as mutable variable', () => {
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('var x = 5;');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.isMutable).toBe(true);
+    expect(info!.isConst).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// JavaScript config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — JavaScript', () => {
+  const extractor = createVariableExtractor(javascriptVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.js',
+    language: SupportedLanguages.JavaScript,
+  };
+
+  it('extracts const declaration', () => {
+    parser.setLanguage(TypeScript.typescript); // JS subset of TS grammar
+    const tree = parser.parse('const PORT = 3000;');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('PORT');
+    expect(info!.isConst).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Python config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — Python', () => {
+  const extractor = createVariableExtractor(pythonVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.py',
+    language: SupportedLanguages.Python,
+  };
+
+  it('extracts UPPER_CASE constant', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('MAX_SIZE = 100');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(true);
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MAX_SIZE');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+    expect(info!.visibility).toBe('public');
+  });
+
+  it('extracts regular assignment as mutable', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('counter = 0');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('counter');
+    expect(info!.isConst).toBe(false);
+    expect(info!.isMutable).toBe(true);
+  });
+
+  it('extracts annotated assignment with type', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('name: str = "hello"');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('name');
+    expect(info!.type).toBe('str');
+  });
+
+  it('detects underscore prefix as protected', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('_internal = 42');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.visibility).toBe('protected');
+  });
+
+  it('detects double underscore prefix as private', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('__secret = 42');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.visibility).toBe('private');
+  });
+
+  it('does not treat dunder names as private', () => {
+    parser.setLanguage(Python);
+    const tree = parser.parse('__name__ = "main"');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.visibility).toBe('public');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Go config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — Go', () => {
+  const extractor = createVariableExtractor(goVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.go',
+    language: SupportedLanguages.Go,
+  };
+
+  it('extracts const declaration', () => {
+    parser.setLanguage(Go);
+    const tree = parser.parse('package main\nconst MaxSize = 100');
+    // Find const_declaration
+    let constNode = null;
+    for (let i = 0; i < tree.rootNode.namedChildCount; i++) {
+      const child = tree.rootNode.namedChild(i);
+      if (child?.type === 'const_declaration') {
+        constNode = child;
+        break;
+      }
+    }
+    expect(constNode).not.toBeNull();
+    expect(extractor.isVariableDeclaration(constNode!)).toBe(true);
+
+    const info = extractor.extract(constNode!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MaxSize');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+    expect(info!.visibility).toBe('public'); // uppercase = exported
+  });
+
+  it('extracts var declaration', () => {
+    parser.setLanguage(Go);
+    const tree = parser.parse('package main\nvar counter int = 0');
+    let varNode = null;
+    for (let i = 0; i < tree.rootNode.namedChildCount; i++) {
+      const child = tree.rootNode.namedChild(i);
+      if (child?.type === 'var_declaration') {
+        varNode = child;
+        break;
+      }
+    }
+    expect(varNode).not.toBeNull();
+
+    const info = extractor.extract(varNode!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('counter');
+    expect(info!.isConst).toBe(false);
+    expect(info!.isMutable).toBe(true);
+    expect(info!.type).toBe('int');
+  });
+
+  it('detects lowercase as package-private', () => {
+    parser.setLanguage(Go);
+    const tree = parser.parse('package main\nconst maxSize = 100');
+    let constNode = null;
+    for (let i = 0; i < tree.rootNode.namedChildCount; i++) {
+      const child = tree.rootNode.namedChild(i);
+      if (child?.type === 'const_declaration') {
+        constNode = child;
+        break;
+      }
+    }
+    expect(constNode).not.toBeNull();
+
+    const info = extractor.extract(constNode!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.visibility).toBe('package');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rust config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — Rust', () => {
+  const extractor = createVariableExtractor(rustVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.rs',
+    language: SupportedLanguages.Rust,
+  };
+
+  it('extracts const_item', () => {
+    parser.setLanguage(Rust);
+    const tree = parser.parse('const MAX_SIZE: usize = 100;');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(true);
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MAX_SIZE');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isStatic).toBe(false);
+    expect(info!.isMutable).toBe(false);
+    expect(info!.type).toBe('usize');
+    expect(info!.visibility).toBe('private');
+  });
+
+  it('extracts static_item', () => {
+    parser.setLanguage(Rust);
+    const tree = parser.parse('static COUNTER: i32 = 0;');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('COUNTER');
+    expect(info!.isStatic).toBe(true);
+    expect(info!.isConst).toBe(false);
+    expect(info!.isMutable).toBe(false);
+  });
+
+  it('extracts pub const as public', () => {
+    parser.setLanguage(Rust);
+    const tree = parser.parse('pub const API_VERSION: &str = "v1";');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.visibility).toBe('public');
+    expect(info!.isConst).toBe(true);
+  });
+
+  it('extracts static mut as mutable', () => {
+    parser.setLanguage(Rust);
+    const tree = parser.parse('static mut BUFFER: Vec<u8> = Vec::new();');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.isStatic).toBe(true);
+    expect(info!.isMutable).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// C/C++ config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — C', () => {
+  const extractor = createVariableExtractor(cVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.c',
+    language: SupportedLanguages.C,
+  };
+
+  it('extracts const declaration', () => {
+    parser.setLanguage(C);
+    const tree = parser.parse('const int MAX_SIZE = 100;');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.isVariableDeclaration(node)).toBe(true);
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MAX_SIZE');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+  });
+
+  it('extracts static variable', () => {
+    parser.setLanguage(C);
+    const tree = parser.parse('static int counter = 0;');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('counter');
+    expect(info!.isStatic).toBe(true);
+    expect(info!.visibility).toBe('private'); // static = file-private
+  });
+});
+
+describe('VariableExtractor — C++', () => {
+  const extractor = createVariableExtractor(cppVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.cpp',
+    language: SupportedLanguages.CPlusPlus,
+  };
+
+  it('extracts constexpr declaration', () => {
+    parser.setLanguage(Cpp);
+    const tree = parser.parse('constexpr int SIZE = 10;');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('SIZE');
+    expect(info!.isConst).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Ruby config
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — Ruby', () => {
+  const extractor = createVariableExtractor(rubyVariableConfig);
+  const ctx: VariableExtractorContext = {
+    filePath: 'test.rb',
+    language: SupportedLanguages.Ruby,
+  };
+
+  it('extracts Ruby constant assignment', () => {
+    parser.setLanguage(Ruby);
+    const tree = parser.parse('MAX_SIZE = 100');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('MAX_SIZE');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+    expect(info!.visibility).toBe('public');
+  });
+
+  it('extracts regular variable assignment', () => {
+    parser.setLanguage(Ruby);
+    const tree = parser.parse('counter = 0');
+    const node = tree.rootNode.child(0)!;
+
+    const info = extractor.extract(node, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('counter');
+    expect(info!.isConst).toBe(false);
+    expect(info!.isMutable).toBe(true);
+    expect(info!.visibility).toBe('private');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Factory generic tests
+// ---------------------------------------------------------------------------
+
+describe('createVariableExtractor — factory', () => {
+  const factoryCtx: VariableExtractorContext = {
+    filePath: 'test.ts',
+    language: SupportedLanguages.TypeScript,
+  };
+
+  it('creates extractor with correct language', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    expect(extractor.language).toBe(SupportedLanguages.TypeScript);
+  });
+
+  it('returns null for non-variable nodes', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('class Foo {}');
+    const node = tree.rootNode.child(0)!;
+    expect(extractor.extract(node, factoryCtx)).toBeNull();
+  });
+
+  it('line number is 1-based', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('const x = 1;');
+    const node = tree.rootNode.child(0)!;
+    const info = extractor.extract(node, factoryCtx);
+    expect(info).not.toBeNull();
+    expect(info!.line).toBe(1);
+    expect(info!.sourceFile).toBe('test.ts');
+  });
+
+  it('sets scope to module for top-level declarations', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('const x = 1;');
+    const node = tree.rootNode.child(0)!;
+    const info = extractor.extract(node, factoryCtx);
+    expect(info).not.toBeNull();
+    // rootNode is 'program' → module scope
+    expect(info!.scope).toBe('module');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Block-scoped variable extraction tests
+// ---------------------------------------------------------------------------
+
+describe('VariableExtractor — block-scoped declarations', () => {
+  it('TypeScript: detects block scope for const inside function', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.ts',
+      language: SupportedLanguages.TypeScript,
+    };
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('function foo() { const x = 5; }');
+    // program > function_declaration > statement_block > lexical_declaration
+    const fnBody = tree.rootNode.child(0)!.childForFieldName('body')!;
+    const constDecl = fnBody.namedChildren.find((c) => c.type === 'lexical_declaration');
+    expect(constDecl).toBeDefined();
+    const info = extractor.extract(constDecl!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.scope).toBe('block');
+    expect(info!.isConst).toBe(true);
+    expect(info!.isMutable).toBe(false);
+  });
+
+  it('TypeScript: detects block scope for let inside arrow function', () => {
+    const extractor = createVariableExtractor(typescriptVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.ts',
+      language: SupportedLanguages.TypeScript,
+    };
+    parser.setLanguage(TypeScript.typescript);
+    const tree = parser.parse('const fn = () => { let y = 10; };');
+    // program > lexical_declaration > variable_declarator > arrow_function > statement_block
+    const lexDecl = tree.rootNode.child(0)!;
+    const varDeclarator = lexDecl.namedChildren.find((c) => c.type === 'variable_declarator')!;
+    const arrowFn = varDeclarator.childForFieldName('value')!;
+    const body = arrowFn.childForFieldName('body')!;
+    const letDecl = body.namedChildren.find((c) => c.type === 'lexical_declaration');
+    expect(letDecl).toBeDefined();
+    const info = extractor.extract(letDecl!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('y');
+    expect(info!.scope).toBe('block');
+    expect(info!.isMutable).toBe(true);
+    expect(info!.isConst).toBe(false);
+  });
+
+  it('Go: detects block scope for short var declaration inside function', () => {
+    const extractor = createVariableExtractor(goVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.go',
+      language: SupportedLanguages.Go,
+    };
+    parser.setLanguage(Go);
+    const tree = parser.parse('package main\nfunc foo() { x := 5 }');
+    // source_file > function_declaration > block > short_var_declaration
+    const funcDecl = tree.rootNode.namedChildren.find((c) => c.type === 'function_declaration')!;
+    const body = funcDecl.childForFieldName('body')!;
+    const shortVarDecl = body.namedChildren.find((c) => c.type === 'short_var_declaration');
+    expect(shortVarDecl).toBeDefined();
+    const info = extractor.extract(shortVarDecl!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.scope).toBe('block');
+    expect(info!.isMutable).toBe(true);
+  });
+
+  it('Rust: detects block scope for let inside function', () => {
+    const extractor = createVariableExtractor(rustVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.rs',
+      language: SupportedLanguages.Rust,
+    };
+    parser.setLanguage(Rust);
+    const tree = parser.parse('fn foo() { let mut x = 5; }');
+    // source_file > function_item > block > let_declaration
+    const funcItem = tree.rootNode.namedChildren.find((c) => c.type === 'function_item')!;
+    const body = funcItem.childForFieldName('body')!;
+    const letDecl = body.namedChildren.find((c) => c.type === 'let_declaration');
+    expect(letDecl).toBeDefined();
+    const info = extractor.extract(letDecl!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.scope).toBe('block');
+    expect(info!.isMutable).toBe(true);
+  });
+
+  it('C: detects block scope for declaration inside function', () => {
+    const extractor = createVariableExtractor(cVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.c',
+      language: SupportedLanguages.C,
+    };
+    parser.setLanguage(C);
+    const tree = parser.parse('void foo() { int x = 5; }');
+    // translation_unit > function_definition > compound_statement > declaration
+    const funcDef = tree.rootNode.namedChildren.find((c) => c.type === 'function_definition')!;
+    const body = funcDef.childForFieldName('body')!;
+    const decl = body.namedChildren.find((c) => c.type === 'declaration');
+    expect(decl).toBeDefined();
+    const info = extractor.extract(decl!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.scope).toBe('block');
+    expect(info!.isMutable).toBe(true);
+  });
+
+  it('Python: detects block scope for assignment inside function', () => {
+    const extractor = createVariableExtractor(pythonVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.py',
+      language: SupportedLanguages.Python,
+    };
+    parser.setLanguage(Python);
+    const tree = parser.parse('def foo():\n    x = 5');
+    // module > function_definition > block > expression_statement > assignment
+    const funcDef = tree.rootNode.namedChildren.find((c) => c.type === 'function_definition')!;
+    const body = funcDef.childForFieldName('body')!;
+    const exprStmt = body.namedChildren.find((c) => c.type === 'expression_statement');
+    expect(exprStmt).toBeDefined();
+    const info = extractor.extract(exprStmt!, ctx);
+    expect(info).not.toBeNull();
+    expect(info!.name).toBe('x');
+    expect(info!.scope).toBe('block');
+  });
+
+  it('Python: rejects non-assignment expression statements (e.g. function calls)', () => {
+    const extractor = createVariableExtractor(pythonVariableConfig);
+    const ctx: VariableExtractorContext = {
+      filePath: 'test.py',
+      language: SupportedLanguages.Python,
+    };
+    parser.setLanguage(Python);
+    const tree = parser.parse('print("hello")');
+    const exprStmt = tree.rootNode.child(0)!;
+    expect(exprStmt.type).toBe('expression_statement');
+    // extract() should return null because this is a call, not an assignment
+    const info = extractor.extract(exprStmt, ctx);
+    expect(info).toBeNull();
+  });
+});