chore(security): upgrade @vercel/node in gitnexus-web and remediate transitive advisories (#1705)

* fix(mcp): disambiguate duplicate-name repo resolution for worktrees

When multiple indexed repos share the same registry name (main checkout plus linked worktrees), MCP tools no longer silently pick the first sibling. Resolution prefers the repo matching process.cwd()'s git root, throws RegistryAmbiguousTargetError when still ambiguous, and uses canonical path matching aligned with the CLI registry.

Fixes #1658. Complements worktree detect_changes fixes in #1654/#1691.

* fix(mcp): refresh registry on duplicate-name ambiguity before failing

resolveRepo now retries resolveRepoFromCache after RegistryAmbiguousTargetError so stale in-memory siblings clear when the registry changes. Adds detect_changes callTool ambiguity test, registry-refresh regression test, pickRepoHandleForCwd MCP cwd doc, and temp-dir cleanup in #1658 fixtures.

* chore(autofix): apply prettier + eslint fixes via /autofix command

* fix(mcp): PR #1753 review follow-ups + collision-id case bug

Address Findings 3-6 from the production-readiness review on PR #1753,
plus a latent bug surfaced while writing the F5 regression test:

- F3: drop the no-op `try { ... } catch (err) { throw err; }` wrapper
  around the miss-path retry in `resolveRepo`; the catch only re-threw.
- F4: rewrite the misleading "child/repo" example on the relative-path
  tier — `child/repo` would be classified as path-like and never reach
  this branch. Comment now describes bare, separator-free names
  resolved against `process.cwd()`.
- F5: add regression test for the stable hashed-id tier so a duplicate
  sibling can be reached by its `<name>-<hash>` id. Writing this test
  exposed that `repoId()` produced a mixed-case base64url suffix while
  `resolveRepoFromCache` lowercased the param before the Map lookup, so
  collision ids with any uppercase byte in the hash were unreachable.
  Fix: lowercase the hash in `repoId` so it survives `paramLower`.
- F6: add regression test asserting two repos sharing a name prefix
  (`project-a`, `project-b`) cause `resolveRepo("project")` to reject
  as not-found rather than silently returning the first partial match.

* refactor(mcp): tighten PR #1753 follow-up tests + pin hash length

Address three P2 maintainability findings from the ce-code-review pass
on commit aa7f2050:

- Export `REPO_ID_HASH_LENGTH` from local-backend.ts and use it in both
  `repoId()` and the hashed-id test. Closes the silent-drift hole where
  the test's inline formula could fall out of sync with the source
  without any signal.
- Extract `makeSharedPrefixFixture(nameA, nameB)` next to
  `makeDuplicateNameFixture`. Centralises the temp-dir + `.gitnexus`
  scaffolding + `duplicateFixtureDirs.push()` cleanup contract so
  future callers can't drop the cleanup step.
- Reorder the hashed-id test's comment block so the intentional-coupling
  rationale leads, before the description of the formula being mirrored.

* chore(autofix): apply prettier + eslint fixes via /autofix command

* chore: re-run CI

---------

Co-authored-by: Test <test@example.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.claude/skills/gitnexus/gitnexus-cli/SKILL.md

@@ -17,11 +17,11 @@ npx gitnexus analyze
 
 Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates CLAUDE.md / AGENTS.md context files.
 
-| Flag                | Effect                                                                                                  |
-| ------------------- | ------------------------------------------------------------------------------------------------------- |
-| `--force`           | Force full re-index even if up to date                                                                  |
-| `--embeddings`      | Enable embedding generation for semantic search (off by default)                                        |
-| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them.    |
+| Flag           | Effect                                                           |
+| -------------- | ---------------------------------------------------------------- |
+| `--force`      | Force full re-index even if up to date                           |
+| `--embeddings` | Enable embedding generation for semantic search (off by default) |
+| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
 
 **When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.
 

.github/workflows/ci-tests.yml

@@ -75,3 +75,105 @@ jobs:
           build: 'true'
       - run: npx vitest run
         working-directory: gitnexus
+
+  # End-to-end smoke test for the #1728 packaging fix: pack the published
+  # tarball, install it globally into a temp prefix, and assert no junction
+  # creation (the EPERM root cause) plus working CLI plus vendor cleanliness
+  # (#836). Runs on windows-latest because that is the platform the fix
+  # targets; the in-repo `npm ci` job above only exercises the dev-tree path
+  # and skips the tarball reify step where the historical EPERM occurred.
+  packaged-install-smoke:
+    name: packaged install smoke (${{ matrix.os }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      # persist-credentials: false — this job runs npm pack + npm install -g
+      # from a tarball and never pushes back; the token in .git/config would
+      # be at risk of leaking through any future artifact-upload step
+      # (zizmor artipacked audit). Disable upfront.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-gitnexus
+        with:
+          build: 'true'
+
+      - name: Pack gitnexus tarball
+        shell: bash
+        run: npm pack
+        working-directory: gitnexus
+
+      - name: Install gitnexus tarball into isolated prefix
+        shell: bash
+        run: |
+          set -euo pipefail
+          PREFIX="$RUNNER_TEMP/gitnexus-smoke"
+          mkdir -p "$PREFIX"
+          TARBALL=$(find . -maxdepth 1 -name 'gitnexus-*.tgz' -print -quit)
+          if [ -z "$TARBALL" ]; then
+            echo "ERROR: no gitnexus-*.tgz tarball found in $(pwd)" >&2
+            exit 1
+          fi
+          echo "Installing $TARBALL into $PREFIX"
+          npm install -g --prefix "$PREFIX" "./$TARBALL" --no-audit --no-fund
+          echo "PREFIX=$PREFIX" >> "$GITHUB_ENV"
+        working-directory: gitnexus
+
+      - name: Assert no junctions or vendor build artifacts
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Locate the installed gitnexus package across npm prefix layouts
+          # (lib/node_modules on POSIX, node_modules on Windows).
+          for candidate in "$PREFIX/lib/node_modules/gitnexus" "$PREFIX/node_modules/gitnexus"; do
+            if [ -d "$candidate" ]; then
+              INSTALLED="$candidate"
+              break
+            fi
+          done
+          if [ -z "${INSTALLED:-}" ]; then
+            echo "ERROR: installed gitnexus package not found under $PREFIX" >&2
+            ls -la "$PREFIX" || true
+            exit 1
+          fi
+          echo "Installed package at: $INSTALLED"
+
+          # #836 invariant: no node_modules/ or build/ under any vendor/*.
+          BAD=$(find "$INSTALLED/vendor" \( -name node_modules -o -name build \) -print 2>/dev/null || true)
+          if [ -n "$BAD" ]; then
+            echo "ERROR: vendor tree contains forbidden build artifacts (#836):" >&2
+            echo "$BAD" >&2
+            exit 1
+          fi
+
+          # #1728 invariant: materialized grammar dirs are real directories,
+          # not junctions/symlinks (which is what the EPERM regression created).
+          for name in tree-sitter-dart tree-sitter-proto tree-sitter-swift; do
+            entry="$INSTALLED/node_modules/$name"
+            if [ ! -e "$entry" ]; then
+              echo "WARN: $name not materialized (toolchain/prebuild may be unavailable on $RUNNER_OS)"
+              continue
+            fi
+            if [ -L "$entry" ]; then
+              echo "ERROR: $entry is a symlink/junction — #1728 regression" >&2
+              exit 1
+            fi
+            if [ ! -d "$entry" ]; then
+              echo "ERROR: $entry is not a directory" >&2
+              exit 1
+            fi
+          done
+
+      - name: Assert gitnexus --version works
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            "$PREFIX/gitnexus.cmd" --version
+          else
+            "$PREFIX/bin/gitnexus" --version
+          fi

.github/workflows/codeql.yml

@@ -48,7 +48,7 @@ jobs:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           languages: ${{ matrix.language }}
           queries: security-and-quality
@@ -69,6 +69,6 @@ jobs:
               - '**/test/fixtures/**'
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           category: '/language:${{ matrix.language }}'

.github/workflows/dependency-review.yml

@@ -33,7 +33,7 @@ jobs:
           persist-credentials: false
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
           fail-on-severity: high
           comment-summary-in-pr: on-failure

.github/workflows/pr-labeler.yml

@@ -108,7 +108,7 @@ jobs:
       # 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@563bf132657a13ded0b01fcb723c5a58cdd824e2 # v7.2.1
+      - uses: release-drafter/release-drafter@c2e2804cc59f45f57076a99af580d0fedb697927 # v7.3.0
         with:
           config-name: release-drafter.yml
           dry-run: true

.github/workflows/scorecard.yml

@@ -53,6 +53,6 @@ jobs:
           retention-days: 5
 
       - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: results.sarif

.github/workflows/trivy.yml

@@ -76,7 +76,7 @@ jobs:
           exit-code: '0'
 
       - name: Upload to Security tab
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: trivy-${{ matrix.image.name }}.sarif
           category: trivy-${{ matrix.image.name }}

.github/workflows/workflow-lint.yml

@@ -76,7 +76,7 @@ jobs:
         continue-on-error: true
 
       - name: Upload SARIF
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: zizmor.sarif
           category: zizmor

AGENTS.md

@@ -62,131 +62,64 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows). Use MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
-> If any tool warns the index is stale, run `npx gitnexus analyze` first.
+> 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.** `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 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
-
-- **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.
+- **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"})`.
 
 ## Never Do
 
-- 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 | 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_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` |
-| `query` (group mode) | Cross-repo search in a group (RRF-merged) | `gitnexus_query({repo: "@myGroup", query: "auth"})` |
-| `context` (group mode) | 360° view across all member repos | `gitnexus_context({repo: "@myGroup", name: "validateUser"})` |
-| `impact` (group mode) | Cross-repo blast radius via Contract Bridge | `gitnexus_impact({repo: "@myGroup", target: "X", direction: "upstream"})` |
-
-> Group mode: pass `repo: "@<groupName>"` to fan out across all member repos, or `repo: "@<groupName>/<memberPath>"` to target a single member (path keys from `group.yaml`). Optional `service: "<monorepo/path>"` filters by service root. Group-level state (contracts, staleness) lives in the resources table below — there are **no** `group_query` / `group_context` / `group_impact` / `group_contracts` / `group_status` MCP tools.
->
-> For a full walkthrough of setting up a group across multiple repos that communicate over gRPC, see [docs/guides/microservices-grpc.md](docs/guides/microservices-grpc.md).
-
-## Impact Risk Levels
-
-| Depth | Meaning | Action |
-|-------|---------|--------|
-| 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 |
+- 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.
 
 ## Resources
 
 | Resource | Use for |
 |----------|---------|
-| `gitnexus://repo/GitNexus/context` | Codebase overview, index freshness |
+| `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 |
-| `gitnexus://group/{name}/contracts` | Group Contract Registry (provider/consumer rows + cross-links) |
-| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness report |
 
-## Self-Check Before Finishing
+## CLI
 
-1. `gitnexus_impact` was run for all modified symbols
-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
-
-```bash
-npx gitnexus analyze                 # incremental by default; preserves embeddings
-npx gitnexus analyze --force         # full rebuild from scratch (opt out of incremental)
-npx gitnexus analyze --embeddings    # also generate embeddings for new/changed nodes
-npx gitnexus analyze --drop-embeddings  # explicit opt-in to wipe existing embeddings
-```
-
-`analyze` runs **incrementally by default**. The pipeline still parses every file every run (cross-file resolution requires it), but tree-sitter parsing is **served from a content-addressed cache** under `.gitnexus/parse-cache/` (per-chunk JSON shards plus `index.json`) for chunks whose file contents haven't changed since the last run. Older installs may still have a legacy single file `.gitnexus/parse-cache.json`, which is read for backward compatibility but no longer written. Only changed-file rows (and their importers) are rewritten in LadybugDB; unchanged-file rows are preserved. Output is byte-equivalent to a full rebuild. Pass `--force` to wipe and re-index from scratch (e.g., to recover from a corrupt index, or after upgrading GitNexus).
-
-The parse cache key is **content-addressed and version-tagged**: it survives `--force` runs, and is automatically invalidated by a `gitnexus` package upgrade (so a new tree-sitter grammar doesn't silently replay stale parse output). Safe to delete the whole `.gitnexus/parse-cache/` directory (and remove any legacy `.gitnexus/parse-cache.json` if present) at any time — it'll be rebuilt on the next analyze.
-
-Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe.
-
-> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself.
-
-## CLI Skills
-
-| 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` |
-
-## Hook env knobs
-
-The Claude Code hook (`gitnexus/hooks/claude/gitnexus-hook.cjs` and the mirrored plugin copy under `gitnexus-claude-plugin/hooks/`) honours these env vars. Defaults work for normal installations; set them only to override resolution. All path overrides ignore values that do not exist on disk and fall through to the standard resolution chain.
-
-| Env var | Type | Default | Purpose |
-|---------|------|---------|---------|
-| `GITNEXUS_HOOK_CLI_PATH` | path | resolved via package layout / `require.resolve` | Override path to the `gitnexus` CLI entry the hook spawns for `augment`. |
-| `GITNEXUS_HOOK_LSOF_PATH` | path | `lsof` on `PATH` (with `/usr/bin/lsof`, `/usr/sbin/lsof`, `/sbin/lsof` fallbacks) | Override POSIX `lsof` location for the DB-lock probe. |
-| `GITNEXUS_HOOK_PS_PATH` | path | `ps` on `PATH` (with `/bin/ps`, `/usr/bin/ps` fallbacks) | Override POSIX `ps` location. |
-| `GITNEXUS_HOOK_POWERSHELL_PATH` | path | `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` (then `SysWOW64`, then `powershell.exe` on `PATH`) | Override Windows PowerShell location used by the Restart-Manager probe. |
-| `GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS` | integer ms | `1200` | Max wall-clock for the Linux `/proc` fd scan before bailing out to the `lsof` fallback. |
-| `GITNEXUS_HOOK_RM_TARGET` | path | derived | Restart-Manager target file (the LadybugDB path under `.gitnexus/`). Set internally by the hook; rarely overridden manually. |
-| `GITNEXUS_DEBUG` | boolean (`1`/`true`) | unset | Verbose stderr from the hook: prints discarded augment-stderr prefixes and one-shot `.ps1` load-failure warnings. |
+| 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` |
+| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
+| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
+| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
+| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
+| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
+| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
+| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
+| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
+| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
+| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
+| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
+| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
+| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
+| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
+| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
+| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
+| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
+| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
+| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
+| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
 
 <!-- gitnexus:end -->
 

CLAUDE.md

@@ -52,3 +52,67 @@ If always-on instructions grow, load deep conventions via conditional reads (e.g
 ## GitNexus rules
 
 See the `<!-- gitnexus:start --> … <!-- gitnexus:end -->` block in **[AGENTS.md](AGENTS.md)** for the canonical MCP tools, impact analysis rules, and index instructions.
+
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **GitNexus** (26675 symbols, 35395 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"})`.
+
+## 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.
+
+## 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 |
+
+## 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` |
+| Work in the Ingestion area (239 symbols) | `.claude/skills/generated/ingestion/SKILL.md` |
+| Work in the Extractors area (135 symbols) | `.claude/skills/generated/extractors/SKILL.md` |
+| Work in the Components area (112 symbols) | `.claude/skills/generated/components/SKILL.md` |
+| Work in the Lbug area (96 symbols) | `.claude/skills/generated/lbug/SKILL.md` |
+| Work in the Group area (94 symbols) | `.claude/skills/generated/group/SKILL.md` |
+| Work in the Cli area (92 symbols) | `.claude/skills/generated/cli/SKILL.md` |
+| Work in the Configs area (92 symbols) | `.claude/skills/generated/configs/SKILL.md` |
+| Work in the Type-extractors area (90 symbols) | `.claude/skills/generated/type-extractors/SKILL.md` |
+| Work in the Hooks area (88 symbols) | `.claude/skills/generated/hooks/SKILL.md` |
+| Work in the Unit area (80 symbols) | `.claude/skills/generated/unit/SKILL.md` |
+| Work in the Cpp area (73 symbols) | `.claude/skills/generated/cpp/SKILL.md` |
+| Work in the Scope-resolution area (72 symbols) | `.claude/skills/generated/scope-resolution/SKILL.md` |
+| Work in the Server area (66 symbols) | `.claude/skills/generated/server/SKILL.md` |
+| Work in the Local area (61 symbols) | `.claude/skills/generated/local/SKILL.md` |
+| Work in the Wiki area (60 symbols) | `.claude/skills/generated/wiki/SKILL.md` |
+| Work in the Workers area (57 symbols) | `.claude/skills/generated/workers/SKILL.md` |
+| Work in the Embeddings area (56 symbols) | `.claude/skills/generated/embeddings/SKILL.md` |
+| Work in the Typescript area (53 symbols) | `.claude/skills/generated/typescript/SKILL.md` |
+| Work in the Storage area (51 symbols) | `.claude/skills/generated/storage/SKILL.md` |
+| Work in the Php area (48 symbols) | `.claude/skills/generated/php/SKILL.md` |
+
+<!-- gitnexus:end -->

README.md

@@ -1,4 +1,5 @@
 # GitNexus
+
 **⚠️ Important Notice:** GitNexus has NO official cryptocurrency, token, or coin. Any token/coin using the GitNexus name on Pump.fun or any other platform is **not affiliated with, endorsed by, or created by** this project or its maintainers. Do not purchase any cryptocurrency claiming association with GitNexus.
 
 <div align="center">
@@ -30,14 +31,9 @@
 
 Indexes any codebase into a knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart tools so AI agents never miss code.
 
-
-
-
 https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
-
-
-> *Like DeepWiki, but deeper.* DeepWiki helps you *understand* code. GitNexus lets you *analyze* it — because a knowledge graph tracks every relationship, not just descriptions.
+> _Like DeepWiki, but deeper._ DeepWiki helps you _understand_ code. GitNexus lets you _analyze_ it — because a knowledge graph tracks every relationship, not just descriptions.
 
 **TL;DR:** The **Web UI** is a quick way to chat with any repo. The **CLI + MCP** is how you make your AI agent actually reliable — it gives Cursor, Claude Code, Codex, and friends a deep architectural view of your codebase so they stop missing dependencies, breaking call chains, and shipping blind edits. Even smaller models get full architectural clarity, making it compete with Goliath models.
 
@@ -47,18 +43,17 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 
 [![Star History Chart](https://api.star-history.com/svg?repos=abhigyanpatwari/GitNexus&type=date&legend=top-left)](https://www.star-history.com/#abhigyanpatwari/GitNexus&type=date&legend=top-left)
 
-
 ## Two Ways to Use GitNexus
 
-|                   | **CLI + MCP**                                            | **Web UI**                                             |
-| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
-| **What**    | Index repos locally, connect AI agents via MCP                 | Visual graph explorer + AI chat in browser                   |
-| **For**     | Daily development with Cursor, Claude Code, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                   |
-| **Scale**   | Full repos, any size                                           | Limited by browser memory (~5k files), or unlimited via backend mode |
-| **Install** | `npm install -g gitnexus`                                    | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app) |
-| **Storage** | LadybugDB native (fast, persistent)                               | LadybugDB WASM (in-memory, per session)                         |
-| **Parsing** | Tree-sitter native bindings                                    | Tree-sitter WASM                                             |
-| **Privacy** | Everything local, no network                                   | Everything in-browser, no server                             |
+|             | **CLI + MCP**                                                         | **Web UI**                                                           |
+| ----------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **What**    | Index repos locally, connect AI agents via MCP                        | Visual graph explorer + AI chat in browser                           |
+| **For**     | Daily development with Cursor, Claude Code, Codex, Windsurf, OpenCode | Quick exploration, demos, one-off analysis                           |
+| **Scale**   | Full repos, any size                                                  | Limited by browser memory (~5k files), or unlimited via backend mode |
+| **Install** | `npm install -g gitnexus`                                             | No install — [gitnexus.vercel.app](https://gitnexus.vercel.app)      |
+| **Storage** | LadybugDB native (fast, persistent)                                   | LadybugDB WASM (in-memory, per session)                              |
+| **Parsing** | Tree-sitter native bindings                                           | Tree-sitter WASM                                                     |
+| **Privacy** | Everything local, no network                                          | Everything in-browser, no server                                     |
 
 > **Bridge mode:** `gitnexus serve` connects the two — the web UI auto-detects the local server and can browse all your CLI-indexed repos without re-uploading or re-indexing.
 
@@ -69,6 +64,7 @@ https://github.com/user-attachments/assets/172685ba-8e54-4ea7-9ad1-e31a3398da72
 GitNexus is available as an **enterprise offering** - either as a fully managed **SaaS** or a **self-hosted** deployment. Also available for **commercial use** of the OSS version with proper licensing.
 
 Enterprise includes:
+
 - **PR Review** - automated blast radius analysis on pull requests
 - **Auto-updating Code Wiki** - always up-to-date documentation (Code Wiki is also available in OSS)
 - **Auto-reindexing** - knowledge graph stays fresh automatically
@@ -77,6 +73,7 @@ Enterprise includes:
 - **Priority feature/language support** - request new languages or features
 
 **Upcoming:**
+
 - Auto regression forensics
 - End-to-end test generation
 
@@ -109,7 +106,7 @@ That's it. This indexes the codebase, installs agent skills, registers Claude Co
 
 To configure MCP for your editor, run `npx gitnexus setup` once — or set it up manually below.
 
-> **Faster install (no C++ toolchain needed):** set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip the native `tree-sitter-dart` and `tree-sitter-proto` builds. Dart/Proto files won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild.
+> **Faster install (no C++ toolchain needed):** set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` before `npm install -g gitnexus` to skip vendored grammar materialize/build (`tree-sitter-dart`, `tree-sitter-proto`, `tree-sitter-swift`). Dart/Proto/Swift files won't be parsed, but install completes in seconds without `python3`/`make`/`g++`. Strict `=1` only — any other value falls through to the rebuild.
 
 ### MCP Setup
 
@@ -117,13 +114,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 ### Editor Support
 
-| Editor                | MCP | Skills | Hooks (auto-augment) | Support        |
-| --------------------- | --- | ------ | -------------------- | -------------- |
-| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse) | **Full** |
-| **Cursor**      | Yes | Yes    | Yes (postToolUse, [manual install](gitnexus-cursor-integration/README.md#hook-install)) | **Full** |
-| **Codex**       | Yes | Yes    | —                   | MCP + Skills   |
-| **Windsurf**    | Yes | —     | —                   | MCP            |
-| **OpenCode**    | Yes | Yes    | —                   | MCP + Skills   |
+| Editor          | MCP | Skills | Hooks (auto-augment)                                                                    | Support      |
+| --------------- | --- | ------ | --------------------------------------------------------------------------------------- | ------------ |
+| **Claude Code** | Yes | Yes    | Yes (PreToolUse + PostToolUse)                                                          | **Full**     |
+| **Cursor**      | Yes | Yes    | Yes (postToolUse, [manual install](gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
+| **Codex**       | Yes | Yes    | —                                                                                       | MCP + Skills |
+| **Windsurf**    | Yes | —      | —                                                                                       | MCP          |
+| **OpenCode**    | Yes | Yes    | —                                                                                       | MCP + Skills |
 
 > **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
 
@@ -131,10 +128,10 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 
 Built by the community — not officially maintained, but worth checking out.
 
-| Project | Author | Description |
-|---------|--------|-------------|
-| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus) | [@tintinweb](https://github.com/tintinweb) | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
-| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem) |
+| Project                                                                       | Author                                                 | Description                                                             |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| [pi-gitnexus](https://github.com/tintinweb/pi-gitnexus)                       | [@tintinweb](https://github.com/tintinweb)             | GitNexus plugin for [pi](https://pi.dev) — `pi install npm:pi-gitnexus` |
+| [gitnexus-stable-ops](https://github.com/ShunsukeHayashi/gitnexus-stable-ops) | [@ShunsukeHayashi](https://github.com/ShunsukeHayashi) | Stable ops & deployment workflows (Miyabi ecosystem)                    |
 
 > Have a project built on GitNexus? Open a PR to add it here!
 
@@ -197,7 +194,8 @@ args = ["-y", "gitnexus@latest", "mcp"]
 ```bash
 gitnexus setup                   # Configure MCP for your editors (one-time)
 gitnexus analyze [path]          # Index a repository (or update stale index)
-gitnexus analyze --force         # Force full re-index
+gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
+gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --skills        # Generate repo-specific skill files from detected communities
 gitnexus analyze --skip-embeddings  # Skip embedding generation (faster)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
@@ -205,6 +203,7 @@ gitnexus analyze --skip-git        # Index folders that are not Git repositories
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
+gitnexus analyze --workers <n>        # Parse worker pool size (default: cores-1, capped at 16; 0 = sequential)
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI connection
 gitnexus list                    # List all indexed repositories
@@ -229,6 +228,25 @@ gitnexus group status <name>     # Check staleness of repos in a group
 
 If `analyze` reports a worker parse timeout on a large or unusual repository, it keeps running and falls back safely. To give slow worker jobs more time, use `gitnexus analyze --worker-timeout 60` or set `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=60000`. For very large files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget.
 
+#### Environment variables
+
+Most `analyze` knobs are also CLI flags (`--workers`, `--worker-timeout`, `--max-file-size`, `--verbose`). Use the env-var form when you'd otherwise repeat the same flag every run, or when invoking GitNexus from a long-running host (MCP server, eval-server, CI shell) that already manages its own environment. CLI flags take precedence over env vars; env vars take precedence over built-in defaults.
+
+| Variable                               | Default                   | Effect                                                                                                                                                     | Tune when…                                                                                                                                  |
+| -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_WORKER_POOL_SIZE`            | `cores - 1`, capped at 16 | Parse worker pool size. `0` disables the pool (sequential fallback). Equivalent to `--workers <n>`.                                                        | Constrained containers (cgroup CPU limits), CI runners with explicit quotas, or debugging a worker-only crash via `0`.                      |
+| `GITNEXUS_PARSE_CHUNK_CONCURRENCY`     | `2`                       | Number of chunks whose file contents may be read into memory in parallel while the pool dispatches the current chunk. Worker dispatch itself stays serial. | Repos large enough to chunk (multi-MB total source) where disk I/O is a measurable fraction of analyze wall-clock.                          |
+| `GITNEXUS_VERBOSE`                     | unset                     | When `1`, enables verbose ingestion logs (skipped-file warnings, per-chunk throughput, parse-cache stats). Equivalent to `--verbose`.                      | Debugging an analyze that "completed" but seems to have missed files; tuning `--workers` / chunk concurrency against observable throughput. |
+| `GITNEXUS_MAX_FILE_SIZE`               | `512` (KB)                | Walker skip threshold in KB. Hard cap is `32768` (tree-sitter buffer ceiling). Equivalent to `--max-file-size <kb>`.                                       | Indexing repos with intentionally-large source files (generated parsers, vendored bundles) that should still be parsed.                     |
+| `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` | `30000`                   | Worker idle timeout in milliseconds before retry/fallback. Equivalent to `--worker-timeout <seconds>` × 1000.                                              | Slow-parsing files (large minified JS, deeply-nested TS types) that legitimately need more than 30s.                                        |
+| `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES`  | `8388608` (8 MB)          | Per-job byte budget the pool will send to a worker in one `postMessage`.                                                                                   | Very large individual files; mostly diagnostic — bumping past 8 MB risks structured-clone memory pressure.                                  |
+| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`        | `3`                       | Max replacement spawns per worker slot before the slot is dropped from the active rotation. Bounds respawn loops on a chronically-crashing slot.           | Hosts where a flaky worker should retry more (raise) or fail-fast (lower) before the slot is dropped.                                       |
+| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`    | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Combined with `timeoutBackoffFactor`, prevents exponentially-growing retries from stalling for hours. | Slow files that legitimately need long total retry windows; lower to fail-fast on stalls.                                                    |
+| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`| `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, every subsequent dispatch rejects until a fresh pool is created.       | Hosts where a SIGSEGV-prone native grammar should trip the breaker sooner; CI runners that should fail loudly.                              |
+| `GITNEXUS_CHUNK_BYTE_BUDGET`           | `2097152` (2 MB)          | Chunk boundary used for cache-key composition and dispatch. Smaller = finer-grained cache hits but more dispatch overhead.                                 | Tuning incremental-analyze cache behavior on monorepos.                                                                                     |
+| `GITNEXUS_NO_GITIGNORE`                | unset                     | When set, skips `.gitignore` parsing. `.gitnexusignore` is still honored.                                                                                  | Indexing a repo whose `.gitignore` excludes files you actually want indexed (e.g., generated code committed for cross-repo lookup).         |
+| `GITNEXUS_SKIP_OPTIONAL_GRAMMARS`      | unset                     | When `=1` strictly, skips vendored grammar materialize/build for `tree-sitter-dart`, `tree-sitter-proto`, and `tree-sitter-swift` at install time.        | Installing on a host without a C++ toolchain or where Swift prebuilds don't match; you're willing to skip Dart/Proto/Swift parsing.         |
+
 #### Publishing to understand-quickly (opt-in)
 
 [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly) is a public registry of code-knowledge graphs that lists `gitnexus@1` as a first-class format. After registering your repo once (`npx @understand-quickly/cli add` or the [wizard](https://looptech-ai.github.io/understand-quickly/add.html)), `gitnexus publish` fires a single `repository_dispatch` event so the registry resyncs your entry on demand instead of waiting for the nightly job.
@@ -239,27 +257,27 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G
 
 **16 tools** exposed via MCP (11 per-repo + 5 group):
 
-| Tool               | What It Does                                                      | `repo` Param |
-| ------------------ | ----------------------------------------------------------------- | -------------- |
-| `list_repos`     | Discover all indexed repositories                                 | —             |
-| `query`          | Process-grouped hybrid search (BM25 + semantic + RRF)             | Optional       |
-| `context`        | 360-degree symbol view — categorized refs, process participation | Optional       |
-| `impact`         | Blast radius analysis with depth grouping and confidence          | Optional       |
-| `detect_changes` | Git-diff impact — maps changed lines to affected processes       | Optional       |
-| `rename`         | Multi-file coordinated rename with graph + text search            | Optional       |
-| `cypher`         | Raw Cypher graph queries                                          | Optional       |
-| `group_list`     | List configured repository groups                                 | —             |
-| `group_sync`     | Extract contracts and match across repos/services                 | —             |
-| `group_contracts`| Inspect extracted contracts and cross-links                       | —             |
-| `group_query`    | Search execution flows across all repos in a group                | —             |
-| `group_status`   | Check staleness of repos in a group                               | —             |
+| Tool              | What It Does                                                     | `repo` Param |
+| ----------------- | ---------------------------------------------------------------- | ------------ |
+| `list_repos`      | Discover all indexed repositories                                | —            |
+| `query`           | Process-grouped hybrid search (BM25 + semantic + RRF)            | Optional     |
+| `context`         | 360-degree symbol view — categorized refs, process participation | Optional     |
+| `impact`          | Blast radius analysis with depth grouping and confidence         | Optional     |
+| `detect_changes`  | Git-diff impact — maps changed lines to affected processes       | Optional     |
+| `rename`          | Multi-file coordinated rename with graph + text search           | Optional     |
+| `cypher`          | Raw Cypher graph queries                                         | Optional     |
+| `group_list`      | List configured repository groups                                | —            |
+| `group_sync`      | Extract contracts and match across repos/services                | —            |
+| `group_contracts` | Inspect extracted contracts and cross-links                      | —            |
+| `group_query`     | Search execution flows across all repos in a group               | —            |
+| `group_status`    | Check staleness of repos in a group                              | —            |
 
 > When only one repo is indexed, the `repo` parameter is optional. With multiple repos, specify which one: `query({query: "auth", repo: "my-app"})`.
 
 **Resources** for instant context:
 
-| Resource                                  | Purpose                                              |
-| ----------------------------------------- | ---------------------------------------------------- |
+| Resource                                | Purpose                                              |
+| --------------------------------------- | ---------------------------------------------------- |
 | `gitnexus://repos`                      | List all indexed repositories (read this first)      |
 | `gitnexus://repo/{name}/context`        | Codebase stats, staleness check, and available tools |
 | `gitnexus://repo/{name}/clusters`       | All functional clusters with cohesion scores         |
@@ -270,9 +288,9 @@ It is opt-in and a no-op without `UNDERSTAND_QUICKLY_TOKEN` — a fine-grained G
 
 **2 MCP prompts** for guided workflows:
 
-| Prompt            | What It Does                                                              |
-| ----------------- | ------------------------------------------------------------------------- |
-| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level       |
+| Prompt          | What It Does                                                              |
+| --------------- | ------------------------------------------------------------------------- |
+| `detect_impact` | Pre-commit change analysis — scope, affected processes, risk level        |
 | `generate_map`  | Architecture documentation from the knowledge graph with mermaid diagrams |
 
 **4 agent skills** installed to `.claude/skills/` automatically:
@@ -359,10 +377,10 @@ npx gitnexus@latest serve
 
 The official Docker setup ships **two signed images** orchestrated by `docker-compose.yaml`. Each image is published to both **GitHub Container Registry** (GHCR) and **Docker Hub** — same build, same digest, same Cosign signature — so pick whichever registry you prefer:
 
-| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror                           |
-| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------- |
-| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`                  |
-| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest`              |
+| Purpose                                                                | GHCR (default in `docker-compose.yaml`)       | Docker Hub mirror              |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------ |
+| CLI / `gitnexus serve` backend (HTTP API on port `4747`, MCP, indexer) | `ghcr.io/abhigyanpatwari/gitnexus:latest`     | `akonlabs/gitnexus:latest`     |
+| Static web UI (port `4173`)                                            | `ghcr.io/abhigyanpatwari/gitnexus-web:latest` | `akonlabs/gitnexus-web:latest` |
 
 > **Heads-up — image rename.** Earlier releases published the web UI under
 > `ghcr.io/abhigyanpatwari/gitnexus`. Starting with the introduction of the
@@ -578,22 +596,22 @@ GitNexus builds a complete knowledge graph of your codebase through a multi-phas
 
 ### Supported Languages
 
-| Language | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
-|----------|---------|----------------|---------|----------|-----------------|---------------------|--------|------------|-------------|
-| TypeScript | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| JavaScript | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ |
-| Python | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Java | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| Kotlin | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| C# | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Go | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Rust | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| PHP | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ |
-| Ruby | ✓ | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ |
-| Swift | — | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| C | — | — | ✓ | — | ✓ | ✓ | — | ✓ | ✓ |
-| C++ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
-| Dart | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ |
+| Language   | Imports | Named Bindings | Exports | Heritage | Type Annotations | Constructor Inference | Config | Frameworks | Entry Points |
+| ---------- | ------- | -------------- | ------- | -------- | ---------------- | --------------------- | ------ | ---------- | ------------ |
+| TypeScript | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| JavaScript | ✓       | ✓              | ✓       | ✓        | —                | ✓                     | ✓      | ✓          | ✓            |
+| Python     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Java       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Kotlin     | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| C#         | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Go         | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Rust       | ✓       | ✓              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| PHP        | ✓       | ✓              | ✓       | —        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| Ruby       | ✓       | —              | ✓       | ✓        | —                | ✓                     | —      | ✓          | ✓            |
+| Swift      | —       | —              | ✓       | ✓        | ✓                | ✓                     | ✓      | ✓          | ✓            |
+| C          | —       | —              | ✓       | —        | ✓                | ✓                     | —      | ✓          | ✓            |
+| C++        | —       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
+| Dart       | ✓       | —              | ✓       | ✓        | ✓                | ✓                     | —      | ✓          | ✓            |
 
 **Imports** — cross-file import resolution · **Named Bindings** — `import { X as Y }` / re-export tracking · **Exports** — public/exported symbol detection · **Heritage** — class inheritance, interfaces, mixins · **Type Annotations** — explicit type extraction for receiver resolution · **Constructor Inference** — infer receiver type from constructor calls (`self`/`this` resolution included for all languages) · **Config** — language toolchain config parsing (tsconfig, go.mod, etc.) · **Frameworks** — AST-based framework pattern detection · **Entry Points** — entry point scoring heuristics
 
@@ -725,9 +743,11 @@ gitnexus wiki --force
 
 
 # Increase the timeout or retries for large codebase or slow LLM providers
-gitnexus wiki --timeout <seconds> # Per-attempt LLM request timeout in seconds (default: 60) 
+gitnexus wiki --timeout <seconds> # LLM request timeout in seconds (default: disabled)
 gitnexus wiki --retries <n>      # Max LLM retry attempts per request (default: 3)
 
+# Change the language generation for wiki
+gitnexus wiki --lang <lang>  # Output language for generated documentation (e.g. english, chinese, spanish, japanese)
 ```
 
 The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph.
@@ -736,16 +756,16 @@ The wiki generator reads the indexed graph structure, groups files into modules
 
 ## Tech Stack
 
-| Layer                     | CLI                                   | Web                                     |
-| ------------------------- | ------------------------------------- | --------------------------------------- |
+| Layer               | CLI                                   | Web                                     |
+| ------------------- | ------------------------------------- | --------------------------------------- |
 | **Runtime**         | Node.js (native)                      | Browser (WASM)                          |
 | **Parsing**         | Tree-sitter native bindings           | Tree-sitter WASM                        |
-| **Database**        | LadybugDB native                         | LadybugDB WASM                             |
+| **Database**        | LadybugDB native                      | LadybugDB WASM                          |
 | **Embeddings**      | HuggingFace transformers.js (GPU/CPU) | transformers.js (WebGPU/WASM)           |
 | **Search**          | BM25 + semantic + RRF                 | BM25 + semantic + RRF                   |
 | **Agent Interface** | MCP (stdio)                           | LangChain ReAct agent                   |
-| **Visualization**   | —                                    | Sigma.js + Graphology (WebGL)           |
-| **Frontend**        | —                                    | React 18, TypeScript, Vite, Tailwind v4 |
+| **Visualization**   | —                                     | Sigma.js + Graphology (WebGL)           |
+| **Frontend**        | —                                     | React 18, TypeScript, Vite, Tailwind v4 |
 | **Clustering**      | Graphology                            | Graphology                              |
 | **Concurrency**     | Worker threads + async                | Web Workers + Comlink                   |
 
@@ -761,12 +781,12 @@ The wiki generator reads the indexed graph structure, groups files into modules
 
 ### Recently Completed
 
-- [X] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
-- [X] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
-- [X] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
-- [X] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
-- [X] Community Detection, Process Detection, Confidence Scoring
-- [X] Hybrid Search, Vector Index
+- [x] Constructor-Inferred Type Resolution, `self`/`this` Receiver Mapping
+- [x] Wiki Generation, Multi-File Rename, Git-Diff Impact Analysis
+- [x] Process-Grouped Search, 360-Degree Context, Claude Code Hooks
+- [x] Multi-Repo MCP, Zero-Config Setup, 14 Language Support
+- [x] Community Detection, Process Detection, Confidence Scoring
+- [x] Hybrid Search, Vector Index
 
 ---
 

eval/README.md

@@ -162,8 +162,8 @@ Each mode has a `system_{mode}.jinja` + `instance_{mode}.jinja` pair. The agent
 
 ```
 Agent → bash command → /usr/local/bin/gitnexus-query
-  → curl localhost:4848/tool/query     (fast path: eval-server, ~100ms)
-  → npx gitnexus query                 (fallback: cold CLI, ~5-10s)
+  → curl http://127.0.0.1:4848/tool/query   (fast path: eval-server, ~100ms)
+  → npx gitnexus query                       (fallback: cold CLI, ~5-10s)
 ```
 
 Each tool script in `/usr/local/bin/` is standalone — no sourcing, no env inheritance needed. This is critical because mini-swe-agent runs every command via `subprocess.run` in a fresh subshell.
@@ -176,6 +176,61 @@ The eval-server is a lightweight HTTP daemon that:
 - Includes next-step hints to guide tool chaining (query → context → impact → fix)
 - Auto-shuts down after idle timeout
 
+**CLI flags:**
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--port <port>` | `4848` | Port to listen on |
+| `--host <host>` | `127.0.0.1` | Bind address — use `0.0.0.0` for cross-container access |
+| `--idle-timeout <seconds>` | `0` (disabled) | Auto-shutdown after N seconds of inactivity |
+
+**READY signal:**
+
+When the server is ready, it writes to stdout:
+
+```
+# IPv4
+GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848
+
+# IPv6 (bracketed to avoid colon ambiguity)
+GITNEXUS_EVAL_SERVER_READY:[::1]:4848
+```
+
+Parse the port as the last colon-segment (`split(':').pop()`) — not `split(':')[1]`, which breaks for IPv6 and for non-loopback IPv4 hosts added in this release.
+
+### Custom port and host
+
+`run_eval.py` does not expose `--port` or `--host` as CLI flags. Configure them in your mode YAML under the `environment:` key:
+
+```yaml
+# configs/modes/native_augment.yaml (or whichever mode you're running)
+environment:
+  eval_server_port: 4849         # change if 4848 is already in use on the host
+  eval_server_host: "0.0.0.0"   # bind all interfaces — needed for cross-container setups
+```
+
+Defaults are `port: 4848` and `host: 127.0.0.1` (loopback only). Use `0.0.0.0` only when the agent container needs to reach the eval-server from a separate network namespace. The health probe and tool scripts connect via the configured bind host (defaulting to `127.0.0.1`), which is reachable for both loopback and all-interface binds.
+
+`"localhost"` is also a valid `eval_server_host` value. The OS resolves it at bind time — typically `127.0.0.1` on dual-stack or IPv4-only systems, and `::1` on IPv6-only systems. The exact result depends on your `/etc/hosts` and `gai.conf`. The READY signal will reflect the actual bound address (e.g. `GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848` or `GITNEXUS_EVAL_SERVER_READY:[::1]:4848`), not the literal string `localhost`. Use this when you want the server to bind to whichever loopback address the OS prefers rather than forcing IPv4.
+
+**Running eval-server directly in Docker / Docker Compose:**
+
+```bash
+# Bind to all interfaces so sibling containers can reach it
+gitnexus eval-server --host 0.0.0.0 --port 4848
+
+# Then probe from a sibling container via its service hostname
+curl http://eval-container:4848/health
+```
+
+If you need a non-default port (e.g. to avoid conflicts), pass `--port <port>` alongside `--host`. The READY signal will reflect both:
+
+```
+GITNEXUS_EVAL_SERVER_READY:0.0.0.0:5000
+```
+
+Parse the port as the last colon-segment (`split(':').pop()`) — safe for both IPv4 and bracketed IPv6 forms.
+
 ### Index caching
 
 SWE-bench repos repeat (Django has 200+ instances at different commits). The harness caches GitNexus indexes per `(repo, commit)` hash in `~/.gitnexus-eval-cache/` to avoid redundant re-indexing.

eval/environments/gitnexus_docker.py

@@ -39,6 +39,7 @@ logger = logging.getLogger("gitnexus_docker")
 
 DEFAULT_CACHE_DIR = Path.home() / ".gitnexus-eval-cache"
 EVAL_SERVER_PORT = 4848
+EVAL_SERVER_HOST = "127.0.0.1"
 
 
 class GitNexusDockerEnvironment(DockerEnvironment):
@@ -62,6 +63,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         skip_embeddings: bool = True,
         gitnexus_timeout: int = 120,
         eval_server_port: int = EVAL_SERVER_PORT,
+        eval_server_host: str = EVAL_SERVER_HOST,
         **kwargs,
     ):
         super().__init__(**kwargs)
@@ -70,6 +72,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         self.skip_embeddings = skip_embeddings
         self.gitnexus_timeout = gitnexus_timeout
         self.eval_server_port = eval_server_port
+        self.eval_server_host = eval_server_host
         self.index_time: float = 0.0
         self._gitnexus_ready = False
 
@@ -165,22 +168,29 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
     def _start_eval_server(self):
         """Start the GitNexus eval-server daemon in the background."""
-        logger.info(f"Starting eval-server on port {self.eval_server_port}...")
+        logger.info(
+            f"Starting eval-server on {self.eval_server_host}:{self.eval_server_port}..."
+        )
 
         self.execute({
             "command": (
                 f"nohup npx gitnexus eval-server --port {self.eval_server_port} "
+                f"--host {self.eval_server_host} "
                 f"--idle-timeout 600 "
                 f"> /tmp/gitnexus-eval-server.log 2>&1 &"
             ),
             "timeout": 5,
         })
 
+        # Use 127.0.0.1 for the health probe — reachable whether server binds
+        # loopback or all interfaces (0.0.0.0), avoiding DNS resolution issues.
+        health_host = "127.0.0.1"
+
         # Wait for the server to be ready (up to ~15s for KuzuDB init)
         for i in range(EVAL_SERVER_HEALTH_RETRIES):
             time.sleep(EVAL_SERVER_HEALTH_INTERVAL_SECONDS)
             health = self.execute({
-                "command": f"curl -sf http://127.0.0.1:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
+                "command": f"curl -sf http://{health_host}:{self.eval_server_port}/health 2>/dev/null || echo 'NOT_READY'",
                 "timeout": EVAL_SERVER_HEALTH_TIMEOUT_SECONDS,
             })
             output = health.get("output", "").strip()
@@ -201,7 +211,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         )
 
     @staticmethod
-    def _render_tool_script(spec: ToolScriptSpec, port: str) -> str:
+    def _render_tool_script(spec: ToolScriptSpec, port: str, host: str = EVAL_SERVER_HOST) -> str:
         """
         Render a standalone bash script for a GitNexus tool.
 
@@ -212,6 +222,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
         if spec.endpoint:
             lines.append(f'PORT="${{GITNEXUS_EVAL_PORT:-{port}}}"')
+            lines.append(f'HOST="${{GITNEXUS_EVAL_HOST:-{host}}}"')
 
         if spec.header:
             lines.append(spec.header.strip())
@@ -221,7 +232,7 @@ class GitNexusDockerEnvironment(DockerEnvironment):
 
         if spec.endpoint:
             lines.append(
-                f'result=$(curl -sf -X POST "http://127.0.0.1:${{PORT}}{spec.endpoint}" '
+                f'result=$(curl -sf -X POST "http://${{HOST}}:${{PORT}}{spec.endpoint}" '
                 '-H "Content-Type: application/json" -d "$payload" 2>/dev/null)'
             )
             lines.append('if [ $? -eq 0 ] && [ -n "$result" ]; then echo "$result"; exit 0; fi')
@@ -244,9 +255,10 @@ class GitNexusDockerEnvironment(DockerEnvironment):
         Uses heredocs with quoted delimiter to avoid all quoting/escaping issues.
         """
         port = str(self.eval_server_port)
+        host = self.eval_server_host
 
         for spec in TOOL_SPECS.values():
-            script_content = self._render_tool_script(spec, port).strip()
+            script_content = self._render_tool_script(spec, port, host).strip()
             # Use heredoc with quoted delimiter — prevents all variable expansion and quoting issues
             self.execute({
                 "command": (
@@ -387,5 +399,6 @@ class GitNexusDockerEnvironment(DockerEnvironment):
             "index_time_seconds": round(self.index_time, 2),
             "skip_embeddings": self.skip_embeddings,
             "eval_server_port": self.eval_server_port,
+            "eval_server_host": self.eval_server_host,
         }
         return base

eval/uv.lock

@@ -760,11 +760,11 @@ wheels = [
 
 [[package]]
 name = "idna"
-version = "3.11"
+version = "3.15"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz", hash = "sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc", size = 199245, upload-time = "2026-05-12T22:45:57.011Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/23/408243171aa9aaba178d3e2559159c24c1171a641aa83b67bdd3394ead8e/idna-3.15-py3-none-any.whl", hash = "sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8", size = 72340, upload-time = "2026-05-12T22:45:55.733Z" },
 ]
 
 [[package]]

gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md

@@ -56,15 +56,15 @@ Generates repository documentation from the knowledge graph using an LLM. Requir
 
 | Flag | Effect |
 |------|--------|
-| `--force` | Force full regeneration |
+| `--force` | Force full regeneration, also required to re-gerenate an existing wiki in a different language |
 | `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
 | `--base-url <url>` | LLM API base URL |
 | `--api-key <key>` | LLM API key |
 | `--concurrency <n>` | Parallel LLM calls (default: 3) |
 | `--gist` | Publish wiki as a public GitHub Gist |
-| `--timeout <seconds>` | Per-attempt LLM request timeout in seconds (default: 60) |
+| `--timeout <seconds>` | LLM request timeout in seconds (default: disabled) |
 | `--retries <n>` | Max LLM retry attempts per request (default: 3) |
-
+| `--lang <lang>`  | Output language for generated documentation (e.g. english, chinese, spanish, japanese)|
 ### list — Show all indexed repos
 
 ```bash

gitnexus-shared/src/index.ts

@@ -26,7 +26,7 @@ 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 { ParameterTypeClass, SymbolDefinition } from './scope-resolution/symbol-definition.js';
 export type {
   ScopeId,
   DefId,
@@ -127,8 +127,10 @@ export { CLASS_KINDS, METHOD_KINDS, FIELD_KINDS } from './scope-resolution/regis
 export type {
   RegistryContext,
   RegistryProviders,
+  OwnedMembersByOwnerLookup,
   OwnerScopedContributor,
   ArityVerdict,
+  ConstraintContext,
 } from './scope-resolution/registries/context.js';
 
 // Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)

gitnexus-shared/src/scope-resolution/reference-site.ts

@@ -21,6 +21,7 @@
  * (defined in `./types.ts`).
  */
 
+import type { ParameterTypeClass } from './symbol-definition.js';
 import type { Range, ScopeId } from './types.js';
 
 /**
@@ -79,4 +80,11 @@ export interface ReferenceSite {
    * (C#: `42` → `'int'`, `"alice"` → `'string'`).
    */
   readonly argumentTypes?: readonly string[];
+  /**
+   * Optional per-argument type-shape sidecar for languages that need
+   * cv/ref/pointer distinctions during constraint filtering. This is
+   * intentionally separate from `argumentTypes`, which stays normalized
+   * for existing overload narrowing and conversion-rank logic.
+   */
+  readonly argumentTypeClasses?: readonly ParameterTypeClass[];
 }

gitnexus-shared/src/scope-resolution/registries/context.ts

@@ -13,7 +13,7 @@
  */
 
 import type { NodeLabel } from '../../graph/types.js';
-import type { SymbolDefinition } from '../symbol-definition.js';
+import type { ParameterTypeClass, 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';
@@ -30,10 +30,50 @@ export interface RegistryProviders {
    * when absent, every candidate receives `'unknown'` (neutral signal).
    */
   arityCompatibility?(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
+
+  /**
+   * Language-specific constraint compatibility between a callsite and a
+   * candidate `def`. Mirrors `arityCompatibility` and shares its three-valued
+   * verdict shape; the third value `'unknown'` MUST keep the candidate
+   * (monotonicity: adding a predicate can only narrow correctly, never
+   * produce a wrong edge). Consulted by `narrowOverloadCandidates` after
+   * arity + type filters when a candidate carries `templateConstraints`.
+   *
+   * Optional; when absent the constraint filter is a pass-through. Languages
+   * with no constrained-overload semantics leave this undefined.
+   */
+  constraintCompatibility?(
+    callsite: Callsite,
+    def: SymbolDefinition,
+    ctx: ConstraintContext,
+  ): ArityVerdict;
 }
 
 export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
 
+/**
+ * Context threaded into `constraintCompatibility`. Kept minimal in the
+ * Tier-A scope (only `argumentTypes`, riding here until a separate
+ * `Callsite`-widening refactor moves them onto the call site directly).
+ * Future Tier-B graph-aware predicates (`is_base_of_v`, etc.) will widen
+ * this interface with `lookupTypeByName` and similar helpers.
+ */
+export interface ConstraintContext {
+  /**
+   * Per-slot argument types at the call site, normalized per the language
+   * adapter. Empty string means unknown. Same convention as
+   * `narrowOverloadCandidates`' `argTypes` parameter.
+   */
+  readonly argumentTypes?: readonly string[];
+  /**
+   * Optional shape-preserving sidecar aligned with `argumentTypes`.
+   * Unknown or unsupported slots should be omitted by producers or
+   * marked with `indirection: 'unknown'`; consumers must preserve the
+   * monotonic fallback and return 'unknown' instead of guessing.
+   */
+  readonly argumentTypeClasses?: readonly ParameterTypeClass[];
+}
+
 // ─── Owner-scoped contributor (concrete shape for `RegistryContributor`) ────
 
 /**
@@ -60,6 +100,19 @@ export interface OwnerScopedContributor {
   byName(name: string): readonly SymbolDefinition[];
 }
 
+/**
+ * Required owner-keyed lookup hook for Step 2 receiver/MRO member walks.
+ * Production callers wire this to the SemanticModel's authoritative
+ * method/field/nested-type registries so each `(ownerDefId, memberName)`
+ * probe is O(1). Implementations MUST return `[]` on an indexed miss —
+ * Step 2 treats `[]` as authoritative and does not consult `defs` for a
+ * fallback scan.
+ */
+export type OwnedMembersByOwnerLookup = (
+  ownerDefId: DefId,
+  memberName: string,
+) => readonly SymbolDefinition[];
+
 // ─── Top-level context threaded through every lookup ───────────────────────
 
 export interface RegistryContext {
@@ -67,6 +120,7 @@ export interface RegistryContext {
   readonly defs: DefIndex;
   readonly qualifiedNames: QualifiedNameIndex;
   readonly moduleScopes: ModuleScopeIndex;
+  readonly ownedMembersByOwner: OwnedMembersByOwnerLookup;
   /**
    * Method-dispatch index; required for method/field registries that
    * honor `useReceiverTypeBinding`. Omit for class-only lookups.

gitnexus-shared/src/scope-resolution/registries/lookup-core.ts

@@ -27,8 +27,10 @@
  *   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
+ *   through an optional `RegistryContext.ownedMembersByOwner` hook when
+ *   supplied (`undefined` → fall back to `defs.byId`; `[]` → indexed
+ *   miss), otherwise via the compatibility fallback scan over
+ *   `defs.byId`; each hit records a raw signal with the owner's
  *   MRO depth.
  *
  * **Step 3 — Owner-scoped contributor.** When
@@ -263,13 +265,14 @@ function walkReceiverTypeBinding(
   // 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]!;
+  let mroDepth = 0;
+  for (const currentOwnerId of walk) {
     const members = collectOwnedMembers(currentOwnerId, name, ctx);
     for (const def of members) {
       if (!acceptedKinds.has(def.type)) continue;
       recordTypeBindingHit(perCandidate, def, mroDepth, ownerDefId);
     }
+    mroDepth++;
   }
 }
 
@@ -333,23 +336,7 @@ function collectOwnedMembers(
   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);
+  return ctx.ownedMembersByOwner(ownerDefId, memberName);
 }
 
 function recordTypeBindingHit(

gitnexus-shared/src/scope-resolution/symbol-definition.ts

@@ -11,6 +11,17 @@
 
 import type { NodeLabel } from '../graph/types.js';
 
+export interface ParameterTypeClass {
+  /** Normalized base type, matching the coarse `parameterTypes` vocabulary when known. */
+  base: string;
+  /** Top-level cv signal preserved from the original C++ parameter spelling. */
+  cv: 'none' | 'const' | 'volatile' | 'const volatile' | 'unknown';
+  /** Coarse value/reference/pointer shape. */
+  indirection: 'value' | 'lvalue-ref' | 'rvalue-ref' | 'pointer' | 'unknown';
+  /** Number of pointer markers when indirection is `pointer`; otherwise 0. */
+  pointerDepth: number;
+}
+
 export interface SymbolDefinition {
   nodeId: string;
   filePath: string;
@@ -26,12 +37,22 @@ export interface SymbolDefinition {
   /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
    *  Populated when parameter types are resolvable from AST (any typed language). */
   parameterTypes?: string[];
+  /** Additive per-parameter type shape sidecar for languages that need cv/ref/pointer distinctions.
+   *  Does not participate in graph node identity unless a resolver explicitly opts in. */
+  parameterTypeClasses?: ParameterTypeClass[];
   /** 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;
   /** Generic/template specialization arguments for class-like symbols (e.g. ['User'], ['T*']). */
   templateArguments?: string[];
+  /** Per-language constraint payload for template / generic overloads
+   *  (e.g. C++ `enable_if_t<P, T>` predicate trees, C++20 `requires` clauses).
+   *  Opaque to shared code — the producing language adapter owns the shape
+   *  and is the only consumer. Read via the optional
+   *  `ScopeResolver.constraintCompatibility` hook during overload narrowing.
+   *  Absent for symbols that have no constraints (the common case). */
+  templateConstraints?: unknown;
   /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
   ownerId?: string;
 }

gitnexus-web/package.json

@@ -18,7 +18,6 @@
     "test:e2e:report": "playwright show-report"
   },
   "dependencies": {
-    "gitnexus-shared": "file:../gitnexus-shared",
     "@langchain/anthropic": "^1.3.29",
     "@langchain/core": "^1.1.44",
     "@langchain/google-genai": "^2.1.30",
@@ -26,10 +25,11 @@
     "@langchain/ollama": "^1.2.6",
     "@langchain/openai": "^1.4.5",
     "@sigma/edge-curve": "^3.1.0",
-    "@tailwindcss/vite": "^4.2.4",
+    "@tailwindcss/vite": "^4.3.0",
     "axios": "^1.16.0",
     "d3": "^7.9.0",
-    "dompurify": "^3.4.2",
+    "dompurify": "^3.4.3",
+    "gitnexus-shared": "file:../gitnexus-shared",
     "graphology": "^0.26.0",
     "graphology-indices": "^0.17.0",
     "graphology-layout-force": "^0.2.4",
@@ -45,13 +45,13 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.6",
     "react-markdown": "^10.1.0",
-    "react-syntax-highlighter": "^16.1.0",
+    "react-syntax-highlighter": "^16.1.1",
     "react-zoom-pan-pinch": "^4.0.3",
     "remark-gfm": "^4.0.1",
     "sigma": "^3.0.2",
     "tailwindcss": "^4.2.4",
     "uuid": "^14.0.0",
-    "zod": "^3.25.76"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@babel/types": "^7.29.0",
@@ -64,7 +64,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "@vercel/node": "^5.5.16",
+    "@vercel/node": "^5.8.2",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.1.5",
     "jsdom": "^29.1.1",
@@ -73,5 +73,18 @@
     "vite": "^8.0.11",
     "vitest": "^4.1.5",
     "wait-on": "^9.0.5"
+  },
+  "overrides": {
+    "@vercel/static-config": {
+      "ajv": "8.18.0"
+    },
+    "@vercel/node": {
+      "path-to-regexp": "6.3.0",
+      "undici": "6.24.0"
+    },
+    "@vercel/python-analysis": {
+      "minimatch": "10.2.3",
+      "smol-toml": "1.6.1"
+    }
   }
 }

gitnexus-web/src/components/RepoAnalyzer.tsx

@@ -9,6 +9,7 @@
 import { useState, useRef, useEffect, useId } from 'react';
 import {
   Github,
+  Gitlab,
   FolderOpen,
   Loader2,
   Check,
@@ -26,15 +27,20 @@ import { AnalyzeProgress } from './AnalyzeProgress';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
-type InputMode = 'github' | 'local';
+type InputMode = 'github' | 'gitlab' | 'local';
 
 const GITHUB_RE = /^https?:\/\/(www\.)?github\.com\/[^/\s]+\/[^/\s]+/i;
+const GITLAB_RE = /^https?:\/\/[^/\s]+\/[^/\s]+\/[^/\s]+(\/.*)?$/i;
 const IS_WINDOWS = navigator.userAgent.toLowerCase().includes('win');
 
 function isValidGithubUrl(value: string): boolean {
   return GITHUB_RE.test(value.trim());
 }
 
+function isValidGitlabUrl(value: string): boolean {
+  return GITLAB_RE.test(value.trim());
+}
+
 // ── Mode tabs ────────────────────────────────────────────────────────────────
 
 function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode) => void }) {
@@ -53,6 +59,19 @@ function ModeTabs({ mode, onChange }: { mode: InputMode; onChange: (m: InputMode
         <Github className="h-3 w-3" />
         GitHub URL
       </button>
+      <button
+        role="tab"
+        aria-selected={mode === 'gitlab'}
+        onClick={() => onChange('gitlab')}
+        className={`flex flex-1 cursor-pointer items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-all duration-150 ${
+          mode === 'gitlab'
+            ? 'bg-accent text-white shadow-sm'
+            : 'text-text-muted hover:text-text-secondary'
+        } `}
+      >
+        <Gitlab className="h-3 w-3" />
+        GitLab URL
+      </button>
       <button
         role="tab"
         aria-selected={mode === 'local'}
@@ -138,6 +157,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
   const folderInputRef = useRef<HTMLInputElement>(null);
   const [mode, setMode] = useState<InputMode>('github');
   const [githubUrl, setGithubUrl] = useState('');
+  const [gitlabUrl, setGitlabUrl] = useState('');
   const [localPath, setLocalPath] = useState('');
   const [phase, setPhase] = useState<InternalPhase>('input');
   const [validationError, setValidationError] = useState<string | null>(null);
@@ -162,6 +182,7 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
   const handleModeChange = (m: InputMode) => {
     setMode(m);
     setGithubUrl('');
+    setGitlabUrl('');
     setLocalPath('');
     setValidationError(null);
   };
@@ -175,13 +196,19 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
   const canSubmit =
     mode === 'github'
       ? isValidGithubUrl(githubUrl) && (phase === 'input' || phase === 'error')
-      : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');
+      : mode === 'gitlab'
+        ? isValidGitlabUrl(gitlabUrl) && (phase === 'input' || phase === 'error')
+        : localPath.trim().length > 1 && (phase === 'input' || phase === 'error');
 
   const handleAnalyze = async () => {
     if (mode === 'github' && !isValidGithubUrl(githubUrl)) {
       setValidationError('Please enter a valid GitHub repository URL.');
       return;
     }
+    if (mode === 'gitlab' && !isValidGitlabUrl(gitlabUrl)) {
+      setValidationError('Please enter a valid GitLab repository URL.');
+      return;
+    }
     if (mode === 'local' && localPath.trim().length < 2) {
       setValidationError('Please enter a folder path.');
       return;
@@ -191,12 +218,22 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
     setPhase('starting');
 
     try {
-      const request = mode === 'github' ? { url: githubUrl.trim() } : { path: localPath.trim() };
+      const request =
+        mode === 'github'
+          ? { url: githubUrl.trim() }
+          : mode === 'gitlab'
+            ? { url: gitlabUrl.trim() }
+            : { path: localPath.trim() };
       const { jobId } = await startAnalyze(request);
       jobIdRef.current = jobId;
       setPhase('analyzing');
 
-      const nameSource = mode === 'github' ? githubUrl.trim() : localPath.trim();
+      const nameSource =
+        mode === 'github'
+          ? githubUrl.trim()
+          : mode === 'gitlab'
+            ? gitlabUrl.trim()
+            : localPath.trim();
       const controller = streamAnalyzeProgress(
         jobId,
         (p) => setProgress(p),
@@ -297,6 +334,61 @@ export const RepoAnalyzer = ({ variant, onComplete, onCancel }: RepoAnalyzerProp
         </div>
       )}
 
+      {/* GitLab URL input */}
+      {showInput && mode === 'gitlab' && (
+        <div className="space-y-2">
+          <label
+            htmlFor={inputId}
+            className="block text-xs font-medium tracking-wider text-text-secondary uppercase"
+          >
+            GitLab Repository URL
+          </label>
+          <div
+            className={`flex items-center gap-3 rounded-xl border bg-void px-4 py-3.5 transition-all duration-200 ${
+              validationError && phase === 'error'
+                ? 'border-red-500/50'
+                : isValidGitlabUrl(gitlabUrl)
+                  ? 'border-accent/50 shadow-[0_0_0_3px_rgba(124,58,237,0.08)]'
+                  : 'border-border-default focus-within:border-accent/40'
+            } `}
+          >
+            <Gitlab className="h-4 w-4 shrink-0 text-text-muted" />
+            <input
+              id={inputId}
+              type="url"
+              value={gitlabUrl}
+              onChange={(e) => {
+                setGitlabUrl(e.target.value);
+                if (validationError) setValidationError(null);
+              }}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' && canSubmit && !isLoading) {
+                  e.preventDefault();
+                  handleAnalyze();
+                }
+              }}
+              disabled={isLoading}
+              placeholder="https://gitlab.com/owner/repo"
+              autoComplete="url"
+              spellCheck={false}
+              className="flex-1 border-none bg-transparent font-mono text-sm text-text-primary outline-none placeholder:text-text-muted disabled:opacity-50"
+            />
+            {gitlabUrl.length > 10 && (
+              <div className="shrink-0">
+                {isValidGitlabUrl(gitlabUrl) ? (
+                  <Check className="h-3.5 w-3.5 text-emerald-400" />
+                ) : (
+                  <AlertCircle className="h-3.5 w-3.5 text-text-muted" />
+                )}
+              </div>
+            )}
+          </div>
+          <p className="text-xs text-text-muted">
+            Supports GitLab.com and self-hosted GitLab instances.
+          </p>
+        </div>
+      )}
+
       {/* Local folder input */}
       {showInput && mode === 'local' && (
         <div className="space-y-2">

gitnexus-web/src/lib/lucide-icons.tsx

@@ -123,6 +123,67 @@ export {
  * defaults to `currentColor`, so Tailwind `text-*` utilities work the same as
  * with any other icon in this module.
  */
+/**
+ * GitLab tanuki mark — SVG path data from simple-icons (CC0-1.0).
+ *
+ * GitLab's logo (the tanuki/fox-head) is a registered trademark of GitLab Inc.
+ * We use it here only to indicate GitLab source-repo integration.
+ *
+ * API-compatible with `lucide-react` icons (`LucideProps`).
+ */
+export const Gitlab = forwardRef<SVGSVGElement, LucideProps>(function Gitlab(
+  {
+    size = 24,
+    color = 'currentColor',
+    className,
+    strokeWidth: _strokeWidth,
+    absoluteStrokeWidth: _absoluteStrokeWidth,
+    ...rest
+  },
+  ref,
+) {
+  const numericSize = typeof size === 'string' ? Number.parseFloat(size) : size;
+  const useSmallVariant = Number.isFinite(numericSize) && (numericSize as number) <= 16;
+
+  if (useSmallVariant) {
+    return (
+      <svg
+        ref={ref}
+        xmlns="http://www.w3.org/2000/svg"
+        width={size}
+        height={size}
+        viewBox="0 0 16 16"
+        fill={color}
+        className={className}
+        {...rest}
+      >
+        <path d="M8 15.282l1.855-5.717H6.145L8 15.282z" />
+        <path d="M8 15.282L6.145 9.565H2.333L8 15.282z" />
+        <path d="M2.333 9.565l-.944-2.942c-.09-.267.067-.553.333-.553h3.153L2.333 9.565z" />
+        <path d="M4.875 6.07L6.145 9.565H2.333l2.542-3.495z" />
+        <path d="M13.667 9.565l.944-2.942c.09-.267-.067-.553-.333-.553h-3.153l2.542 3.495z" />
+        <path d="M11.125 6.07L9.855 9.565h3.812l-2.542-3.495z" />
+        <path d="M8 15.282l1.855-5.717H6.145L8 15.282z" />
+      </svg>
+    );
+  }
+
+  return (
+    <svg
+      ref={ref}
+      xmlns="http://www.w3.org/2000/svg"
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill={color}
+      className={className}
+      {...rest}
+    >
+      <path d="m23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z" />
+    </svg>
+  );
+});
+
 export const Github = forwardRef<SVGSVGElement, LucideProps>(function Github(
   {
     size = 24,

gitnexus-web/vercel.json

@@ -1,3 +1,3 @@
 {
-  "installCommand": "cd ../gitnexus-shared && npm install && npm run build && cd ../gitnexus-web && npm install"
+  "installCommand": "cd ../gitnexus-shared && npm install && npm run build && cd ../gitnexus-web && npm ci --include=dev"
 }

gitnexus/.claude/settings.local.json

@@ -1,5 +1,18 @@
 {
   "permissions": {
-    "allow": ["mcp__plugin_claude-mem_mcp-search__get_observations"]
-  }
+    "allow": [
+      "mcp__plugin_claude-mem_mcp-search__get_observations",
+      "Skill(gitnexus-exploring)",
+      "Bash(npx gitnexus *)",
+      "mcp__obsidian-memory__search_nodes",
+      "mcp__obsidian-memory__add_observations",
+      "WebSearch",
+      "WebFetch(domain:cppreference.net)",
+      "Bash(xargs grep -l \"templateArguments\\\\|parameterTypes\")",
+      "Bash(gh issue *)",
+      "Bash(gh pr *)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": ["gitnexus"]
 }

gitnexus/README.md

@@ -151,7 +151,8 @@ Your AI agent gets these tools automatically:
 ```bash
 gitnexus setup                   # Configure MCP for your editors (one-time)
 gitnexus analyze [path]          # Index a repository (or update stale index)
-gitnexus analyze --force         # Force full re-index
+gitnexus analyze --repair-fts    # Fast path: rebuild/verify only FTS indexes on existing index data
+gitnexus analyze --force         # Full rebuild: re-parse + graph rebuild + FTS rebuild
 gitnexus analyze --embeddings    # Enable embedding generation (slower, better search)
 gitnexus analyze --skip-agents-md  # Preserve custom AGENTS.md/CLAUDE.md gitnexus section edits
 gitnexus analyze --verbose       # Log skipped files when parsers are unavailable
@@ -358,6 +359,16 @@ npx gitnexus analyze
 
 For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
 
+### Worker pool resilience tuning
+
+Three env vars expose the pool's resilience layers (respawn budget, cumulative-timeout cap, circuit breaker). Defaults are tuned for typical repos; bump them when an analyze legitimately needs more retries, or lower them to fail-fast on a known-bad shape.
+
+| Variable                                          | Default                   | Effect                                                                                                                            |
+| ------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`            | `3`                       | Max replacement spawns per slot before the slot is dropped from the active rotation.                                              |
+| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`        | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Bounds exponentially-growing retry waits.                              |
+| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`    | `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, dispatches require a fresh pool.            |
+
 ## Privacy
 
 - All processing happens locally on your machine

gitnexus/bench/parse-throughput.md

@@ -0,0 +1,175 @@
+# Parse-throughput benchmark (scaffold)
+
+> **Status: methodology + harness scaffold, no measurement data yet.**
+> The Latest measurement table below contains `_TBD_` placeholders.
+> This file ships intentionally without numbers — populating it
+> requires a dedicated bench-pass against the U6 fixture (and ideally
+> a real-world TS-root-scale repo) on consistent hardware, which is
+> tracked as future work rather than gated on PR #1693's merge.
+> Until the table is populated, the load-bearing perf-regression
+> protection lives in `gitnexus/test/integration/parse-impl-large-fixture.test.ts`
+> (U6, 30 s wall-clock budget via `Promise.race`).
+
+Tracks `runChunkedParseAndResolve` wall-clock + peak heap on a synthetic
+fixture so PR #1693's "analyze no longer hangs on TS-root-shaped loads"
+claim is measurable, not just asserted by smoke tests. The harness
+recipe below is deliberately small enough to re-run in a few minutes
+when the bench-pass is undertaken.
+
+---
+
+## Methodology
+
+### Fixture
+
+Synthetic TypeScript repo, _not_ a clone of microsoft/TypeScript. CI cost
+of cloning real-world repos is prohibitive; the synthetic shape exercises
+the same pipeline paths (chunking, deferred extraction, cross-chunk
+imports + heritage) without the disk-I/O overhead. Larger numbers can be
+manually captured against real repos and cross-referenced here, but the
+authoritative regression-tracking shape is the synthetic fixture so runs
+are reproducible across hardware.
+
+The fixture matches the structure pinned by
+`gitnexus/test/integration/parse-impl-large-fixture.test.ts` (U6):
+
+- 15 small modules (`mod0.ts` … `mod14.ts`), one exported function each.
+- 1 dense `complex.ts` with 30 functions + 1 class + 1 interface.
+- 1 `index.ts` re-exporting every symbol from every module.
+
+`GITNEXUS_CHUNK_BYTE_BUDGET=64` forces multi-chunk parsing on this small
+fixture — without that override the whole thing fits in one chunk and
+the deferred-extraction path is not exercised end-to-end.
+
+### What to measure
+
+| Metric                      | How                                                                              |
+| --------------------------- | -------------------------------------------------------------------------------- |
+| Wall-clock total            | `Date.now()` delta around `runChunkedParseAndResolve`                            |
+| Peak heap                   | Sample `process.memoryUsage().heapUsed` every 50 ms during the run; keep the max |
+| Chunks observed             | Count distinct `Parsing chunk X/Y` progress messages                             |
+| `getStats()` final snapshot | Quarantined paths, dropped slots, breaker state                                  |
+
+### Hardware shape (record alongside each measurement)
+
+- OS + version
+- CPU model + logical core count
+- RAM
+- Node version
+- gitnexus commit SHA (so the snapshot is anchored to a tree, not "main")
+
+---
+
+## Harness recipe
+
+The U6 test (`test/integration/parse-impl-large-fixture.test.ts`) is the
+checked-in mini-benchmark — it exercises the same fixture and bounds the
+wall-clock at 30 s via `Promise.race`. To produce a richer snapshot for
+this doc, run it under instrumentation:
+
+```bash
+# From the gitnexus/ subdir:
+cd gitnexus
+# Single-threaded baseline (sequential fallback):
+npx vitest run test/integration/parse-impl-large-fixture.test.ts --reporter=verbose
+
+# Worker-pool path (requires built dist/ — pre-built by `npm run build`):
+npm run build && \
+  GITNEXUS_WORKER_POOL_SIZE=4 \
+  GITNEXUS_PARSE_CHUNK_CONCURRENCY=2 \
+  GITNEXUS_VERBOSE=1 \
+  npx vitest run test/integration/parse-impl-large-fixture.test.ts --reporter=verbose
+```
+
+For peak-heap sampling, wrap the dispatch call in a Node script that
+polls `process.memoryUsage()`. A future helper at
+`gitnexus/bench/scripts/parse-throughput.ts` would automate this — the
+plan's stretch goal. Until that lands, capture peak heap manually via:
+
+```bash
+node --inspect=0 \
+  --require ./scripts/heap-sampler.js \
+  ./node_modules/.bin/vitest run test/integration/parse-impl-large-fixture.test.ts
+```
+
+---
+
+## Latest measurement
+
+> _No measurement data has been collected yet — this file is the
+> methodology + harness scaffold. The single recorded data point is the
+> U6 wall-clock smoke baseline below; the worker-pool rows are
+> placeholders for future bench-pass output._
+
+The U6 integration test (`gitnexus/test/integration/parse-impl-large-fixture.test.ts`)
+was observed completing the synthetic fixture in **~6 seconds** under
+the sequential path (`skipWorkers: true`) on the development machine,
+well under the 30 s `Promise.race` wall-clock budget. That number is a
+smoke baseline only — recorded here for reference, not as a regression
+target.
+
+| Path                                       | files/s | wall-clock           | peak heap | chunks | quarantined |
+| ------------------------------------------ | ------- | -------------------- | --------- | ------ | ----------- |
+| Sequential (`skipWorkers: true`, U6 smoke) | _TBD_   | ~6 s _(observation)_ | _TBD_     | 17     | 0           |
+| Worker pool, `--workers 4`, concurrency 2  | _TBD_   | _TBD_                | _TBD_     | _TBD_  | 0           |
+| Worker pool, `--workers 1`, concurrency 1  | _TBD_   | _TBD_                | _TBD_     | _TBD_  | 0           |
+
+**Hardware:** _TBD — record OS, CPU, RAM, Node version, gitnexus SHA at
+the time of the bench-pass that populates the table above._
+
+---
+
+## Operator-tuning quick reference
+
+Cross-links to the env vars documented in the [README](../../README.md#environment-variables).
+Use this section as a starting point when the benchmark numbers above
+suggest a tuning opportunity for your hardware shape.
+
+- **CPU-bound, big repo, lots of cores:** raise `GITNEXUS_WORKER_POOL_SIZE`
+  past the default cap of 16. The 16-worker cap exists because past that
+  point main-thread merge / extraction dominates; if you've measurably
+  ruled that out, the env var lifts the cap explicitly. (See
+  `worker-pool.ts` `DEFAULT_POOL_SIZE_CAP`.)
+- **Slow files (large minified JS, deep TS types):** raise
+  `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS` past 30 000 ms. The cumulative
+  budget is 5× this value (U10 pins this) so a 60 s idle timeout permits
+  300 s of total retry-and-split wall-clock before quarantining the file.
+- **Constrained container (cgroup CPU limit):** the pool now uses
+  `os.availableParallelism()` (U3 H2), which honors cgroup limits — no
+  manual `GITNEXUS_WORKER_POOL_SIZE` override needed unless the auto-
+  resolved value is too aggressive for your I/O budget.
+- **Long-running host (eval-server, MCP daemon) running back-to-back
+  analyzes:** `--workers` is now threaded through `AnalyzeOptions`
+  (U2 B2), so per-invocation sizing is honored without `process.env`
+  state leaking across calls. `GITNEXUS_VERBOSE` is similarly snapshot/
+  restore-bracketed.
+
+---
+
+## What this benchmark does NOT measure
+
+- **Real-repo performance.** The synthetic fixture is sized for CI; it
+  doesn't exercise the cumulative-load shape (50k files, occasional
+  pathological file) that drove the original PR #1693 hang report. Real-
+  repo numbers should be captured ad-hoc against the user's target repo
+  and cross-referenced here only as supplementary evidence.
+- **Worker-pool resilience under real crashes.** That's verified by the
+  `worker-pool.test.ts` integration tests (real `process.exit`, real
+  `error` events, real protocol violations) and the unit suite. The
+  benchmark cares about throughput on the happy path.
+- **IPC repack throughput.** Phase 3 of the PR #1693 plan introduces a
+  transferList + binary wire-format IPC repack (U16-U17). Once that
+  lands, an `IPC repack` row should be added to the "Latest measurement"
+  table above with before/after numbers on the same hardware.
+
+---
+
+## Related artifacts
+
+- Plan: `docs/plans/2026-05-20-001-feat-pr1693-resilience-hardening-and-ipc-repack-plan.md`
+- Integration test (mini-benchmark with wall-clock guard): `gitnexus/test/integration/parse-impl-large-fixture.test.ts` (U6)
+- Operator env-var reference: `README.md` → Environment variables
+- Resilience layer tests: `gitnexus/test/unit/worker-pool-resilience.test.ts`,
+  `worker-pool-cumulative-timeout.test.ts`,
+  `worker-pool-windows-quarantine.test.ts`,
+  `worker-pool-slot-generation.test.ts`

gitnexus/package.json

@@ -48,7 +48,7 @@
     "test:integration": "vitest run test/integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "postinstall": "node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs",
+    "postinstall": "node scripts/materialize-vendor-grammars.cjs && node scripts/build-tree-sitter-dart.cjs && node scripts/build-tree-sitter-proto.cjs && node scripts/build-tree-sitter-swift.cjs",
     "prepare": "node scripts/build.js",
     "prepack": "node scripts/build.js"
   },
@@ -60,7 +60,7 @@
     "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
     "cors": "^2.8.5",
-    "express": "^4.19.2",
+    "express": "^5.2.1",
     "express-rate-limit": "^8.4.1",
     "glob": "^13.0.6",
     "graphology": "^0.26.0",
@@ -92,15 +92,12 @@
   "optionalDependencies": {
     "node-addon-api": "^8.0.0",
     "node-gyp-build": "^4.8.0",
-    "tree-sitter-dart": "file:./vendor/tree-sitter-dart",
-    "tree-sitter-kotlin": "^0.3.8",
-    "tree-sitter-proto": "file:./vendor/tree-sitter-proto",
-    "tree-sitter-swift": "file:./vendor/tree-sitter-swift"
+    "tree-sitter-kotlin": "^0.3.8"
   },
   "devDependencies": {
     "@types/cli-progress": "^3.11.6",
     "@types/cors": "^2.8.17",
-    "@types/express": "^4.17.21",
+    "@types/express": "^5.0.6",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.6.0",
     "@types/uuid": "^11.0.0",

gitnexus/scripts/build-tree-sitter-dart.cjs

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+/**
+ * Build tree-sitter-dart native binding in node_modules/ after materialize-vendor-grammars.cjs.
+ * Vendored source lives in vendor/ only; see #836 and #1728.
+ */
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');

gitnexus/scripts/build-tree-sitter-proto.cjs

@@ -4,7 +4,7 @@
  *
  * Why this script exists:
  *   tree-sitter-proto is vendored under gitnexus/vendor/tree-sitter-proto/
- *   and declared as a `file:` optionalDependency. Previously, the vendored
+ *   and copied into node_modules/ by materialize-vendor-grammars.cjs. Previously, the vendored
  *   package had its own `dependencies` and `install` script, which caused
  *   npm to create `vendor/tree-sitter-proto/node_modules/` and
  *   `vendor/tree-sitter-proto/build/` during install. Those directories
@@ -20,9 +20,8 @@
  *   gitnexus's own optionalDependencies, and moved native compilation here.
  *
  * What this does:
- *   Runs `npx node-gyp rebuild` inside `node_modules/tree-sitter-proto/`
- *   (which npm creates as a copy of vendor/tree-sitter-proto/ when
- *   resolving the file: dep). Build output lands in
+ *   Runs `npx node-gyp rebuild` inside `node_modules/tree-sitter-proto/`.
+ *   Build output lands in
  *   `node_modules/tree-sitter-proto/build/Release/tree_sitter_proto_binding.node`
  *   — under npm-managed territory, safe on upgrade.
  *

gitnexus/scripts/build-tree-sitter-swift.cjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Probe tree-sitter-swift prebuild availability at install time.
+ *
+ * The vendored package ships platform prebuilds; node-gyp-build selects the
+ * correct binary at require time. This script calls node-gyp-build once
+ * against the materialized package so a missing-prebuild failure surfaces
+ * as an install-time warning (with the rest of the gitnexus install
+ * succeeding) rather than as a runtime error the first time Swift parsing
+ * is requested. The result is discarded — it does not copy, register, or
+ * mutate anything; the runtime require() path in parser-loader does the
+ * actual load. Running this probe here instead of an npm `install` script
+ * on the vendored package preserves the #836 hygiene (no scripts.install
+ * inside vendor/).
+ */
+const fs = require('fs');
+const path = require('path');
+
+if (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn('[tree-sitter-swift] Skipping prebuild probe (GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1).');
+  process.exit(0);
+}
+
+const swiftDir = path.join(__dirname, '..', 'node_modules', 'tree-sitter-swift');
+
+try {
+  if (!fs.existsSync(path.join(swiftDir, 'bindings', 'node', 'index.js'))) {
+    process.exit(0);
+  }
+
+  const nodeGypBuild = require('node-gyp-build');
+  nodeGypBuild(swiftDir);
+} catch (err) {
+  console.warn('[tree-sitter-swift] Prebuild probe failed:', err.message);
+  console.warn(
+    '[tree-sitter-swift] Swift parsing will be unavailable. Non-Swift functionality is unaffected.',
+  );
+  process.exit(0);
+}

gitnexus/scripts/build.js

@@ -18,6 +18,22 @@ const ROOT = path.resolve(__dirname, '..');
 const SHARED_ROOT = path.resolve(ROOT, '..', 'gitnexus-shared');
 const DIST = path.join(ROOT, 'dist');
 const SHARED_DEST = path.join(DIST, '_shared');
+const DEFAULT_BUILD_TIMEOUT_MS = 300_000;
+
+function getBuildTimeoutMs() {
+  const raw = process.env.GITNEXUS_BUILD_TIMEOUT_MS;
+  if (raw === undefined || raw.trim() === '') return DEFAULT_BUILD_TIMEOUT_MS;
+
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+
+  console.warn(
+    `[build] ignoring invalid GITNEXUS_BUILD_TIMEOUT_MS=${JSON.stringify(raw)}; using ${DEFAULT_BUILD_TIMEOUT_MS}ms`,
+  );
+  return DEFAULT_BUILD_TIMEOUT_MS;
+}
+
+const BUILD_TIMEOUT_MS = getBuildTimeoutMs();
 
 // ── 1. Build gitnexus-shared ───────────────────────────────────────
 console.log('[build] compiling gitnexus-shared…');
@@ -25,11 +41,11 @@ const tscCmd =
   process.platform === 'win32'
     ? path.join('node_modules', '.bin', 'tsc.cmd')
     : path.join('node_modules', '.bin', 'tsc');
-execSync(tscCmd, { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 });
+execSync(tscCmd, { cwd: SHARED_ROOT, stdio: 'inherit', timeout: BUILD_TIMEOUT_MS });
 
 // ── 2. Build gitnexus ──────────────────────────────────────────────
 console.log('[build] compiling gitnexus…');
-execSync(tscCmd, { cwd: ROOT, stdio: 'inherit', timeout: 120_000 });
+execSync(tscCmd, { cwd: ROOT, stdio: 'inherit', timeout: BUILD_TIMEOUT_MS });
 
 // ── 3. Copy shared dist ────────────────────────────────────────────
 console.log('[build] copying shared module into dist/_shared…');
@@ -82,9 +98,9 @@ if (fs.existsSync(path.join(WEB_ROOT, 'package.json'))) {
   console.log('[build] building gitnexus-web…');
   if (!fs.existsSync(path.join(WEB_ROOT, 'node_modules'))) {
     console.log('[build] installing gitnexus-web dependencies…');
-    execSync('npm ci', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+    execSync('npm ci', { cwd: WEB_ROOT, stdio: 'inherit', timeout: BUILD_TIMEOUT_MS });
   }
-  execSync('npm run build', { cwd: WEB_ROOT, stdio: 'inherit', timeout: 120_000 });
+  execSync('npm run build', { cwd: WEB_ROOT, stdio: 'inherit', timeout: BUILD_TIMEOUT_MS });
 
   // Copy dist → gitnexus/web/ (shipped in the npm package)
   fs.rmSync(WEB_DEST, { recursive: true, force: true });

gitnexus/scripts/materialize-vendor-grammars.cjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Copy vendored tree-sitter grammars into node_modules/ using real files (fs.cpSync).
+ *
+ * Published gitnexus used to declare these as optionalDependencies with
+ * `file:./vendor/...`, which makes npm symlink/junction vendor → node_modules on
+ * install. Windows without Developer Mode often fails with EPERM (#1728).
+ *
+ * Vendor trees stay read-only in gitnexus/vendor/; build artifacts must only
+ * land under node_modules/ (see #836).
+ */
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const VENDORED_GRAMMARS = ['tree-sitter-dart', 'tree-sitter-proto', 'tree-sitter-swift'];
+
+if (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS === '1') {
+  console.warn(
+    '[gitnexus] Skipping vendored grammar materialize (GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1). Dart/Proto/Swift parsing will be unavailable.',
+  );
+  process.exit(0);
+}
+
+for (const name of VENDORED_GRAMMARS) {
+  const src = path.join(ROOT, 'vendor', name);
+  const dest = path.join(ROOT, 'node_modules', name);
+
+  if (!fs.existsSync(src)) {
+    console.warn(`[gitnexus] vendor/${name} missing; skipping materialize.`);
+    continue;
+  }
+
+  // Sequence: copy src → partial; rename dest → backup; rename partial → dest;
+  // remove backup. If any step fails, restore from backup so a previously-
+  // materialized grammar is never lost. Targets the #1728 EPERM scenario plus
+  // narrower failure modes (Windows AV scanner racing on rename, EBUSY mid-swap).
+  const partial = `${dest}.materialize-tmp`;
+  const backup = `${dest}.materialize-bak`;
+  try {
+    fs.mkdirSync(path.join(ROOT, 'node_modules'), { recursive: true });
+    fs.rmSync(partial, { recursive: true, force: true });
+    fs.rmSync(backup, { recursive: true, force: true });
+    fs.cpSync(src, partial, { recursive: true, verbatim: true });
+    if (fs.existsSync(dest)) {
+      fs.renameSync(dest, backup);
+    }
+    try {
+      fs.renameSync(partial, dest);
+    } catch (renameErr) {
+      // Best-effort rollback: restore the previous dest from backup.
+      if (fs.existsSync(backup)) {
+        try {
+          fs.renameSync(backup, dest);
+        } catch {
+          // If rollback also fails, the prior backup directory still exists on
+          // disk — the catch block below surfaces both errors via the warning.
+        }
+      }
+      throw renameErr;
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+  } catch (err) {
+    // Fail-soft: a single locked/inaccessible file (common on Windows) must not
+    // abort the whole gitnexus install. Matches build-tree-sitter-*.cjs pattern.
+    fs.rmSync(partial, { recursive: true, force: true });
+    console.warn(`[gitnexus] Could not materialize vendor/${name}: ${err.message}`);
+    console.warn(
+      `[gitnexus] ${name} parsing will be unavailable. Other functionality is unaffected.`,
+    );
+  }
+}

gitnexus/src/cli/analyze.ts

@@ -9,10 +9,11 @@
  */
 
 import path from 'path';
-import { execFileSync } from 'child_process';
+import { spawn } from 'child_process';
 import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { closeLbug } from '../core/lbug/lbug-adapter.js';
+import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../core/lbug/lbug-config.js';
 import {
   getStoragePaths,
   getGlobalRegistryPath,
@@ -36,6 +37,7 @@ import { isHfDownloadFailure } from '../core/embeddings/hf-env.js';
 // previous behaviour silently swallowed stack traces and made #1169
 // indistinguishable from a no-op success on Windows.
 const realStderrWrite = process.stderr.write.bind(process.stderr);
+const realStdoutWrite = process.stdout.write.bind(process.stdout);
 
 const writeFatalToStderr = (label: string, err: unknown): void => {
   const isErr = err instanceof Error;
@@ -67,14 +69,354 @@ const installFatalHandlers = (): void => {
   });
 };
 
-const HEAP_MB = 8192;
-const HEAP_FLAG = `--max-old-space-size=${HEAP_MB}`;
+const HEAP_MB = 16384;
+const TEST_RESPAWN_HEAP_MB = Number(process.env.GITNEXUS_TEST_RESPAWN_HEAP_MB);
+const RESPAWN_HEAP_MB =
+  Number.isFinite(TEST_RESPAWN_HEAP_MB) && TEST_RESPAWN_HEAP_MB > 0
+    ? Math.floor(TEST_RESPAWN_HEAP_MB)
+    : HEAP_MB;
+const HEAP_FLAG = `--max-old-space-size=${RESPAWN_HEAP_MB}`;
 /** Increase default stack size (KB) to prevent stack overflow on deep class hierarchies. */
 const STACK_KB = 4096;
 const STACK_FLAG = `--stack-size=${STACK_KB}`;
+const RESPAWN_OUTPUT_TAIL_CHARS = 1024 * 1024;
+const RESPAWN_PROGRESS_ENV = 'GITNEXUS_RESPAWN_PROGRESS_TTY';
 
-/** Re-exec the process with an 8GB heap and larger stack if we're currently below that. */
-function ensureHeap(): boolean {
+interface CliProgressTerminal {
+  cursorSave(): void;
+  cursorRestore(): void;
+  cursor(enabled: boolean): void;
+  lineWrapping(enabled: boolean): void;
+  cursorTo(x?: number | null, y?: number | null): void;
+  cursorRelative(dx?: number | null, dy?: number | null): void;
+  cursorRelativeReset(): void;
+  clearRight(): void;
+  clearLine(): void;
+  clearBottom(): void;
+  newline(): void;
+  write(s: string, rawWrite?: boolean): void;
+  isTTY(): boolean;
+  getWidth(): number;
+}
+
+const terminalColumns = (): number => {
+  const parsed = Number(process.env.COLUMNS);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 80;
+};
+
+const ANSI_ESCAPE_PATTERN =
+  /\x1B(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|[PX^_][\s\S]*?\x1B\\|[78]|[@-Z\\-_])/y;
+
+interface IntlSegmenterLike {
+  segment(input: string): Iterable<{ segment: string }>;
+}
+
+type IntlWithOptionalSegmenter = typeof Intl & {
+  Segmenter?: new (
+    locales?: string | string[],
+    options?: { granularity?: 'grapheme' },
+  ) => IntlSegmenterLike;
+};
+
+const splitGraphemes = (text: string): string[] => {
+  const Segmenter = (Intl as IntlWithOptionalSegmenter).Segmenter;
+  if (Segmenter) {
+    return Array.from(
+      new Segmenter(undefined, { granularity: 'grapheme' }).segment(text),
+      (s) => s.segment,
+    );
+  }
+  return Array.from(text);
+};
+
+const isZeroWidthCodePoint = (codePoint: number): boolean =>
+  codePoint === 0x200d ||
+  (codePoint >= 0x0300 && codePoint <= 0x036f) ||
+  (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+  (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+  (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+  (codePoint >= 0xfe00 && codePoint <= 0xfe0f) ||
+  (codePoint >= 0xfe20 && codePoint <= 0xfe2f);
+
+const isWideCodePoint = (codePoint: number): boolean =>
+  codePoint >= 0x1100 &&
+  (codePoint <= 0x115f ||
+    codePoint === 0x2329 ||
+    codePoint === 0x232a ||
+    (codePoint >= 0x2e80 && codePoint <= 0xa4cf && codePoint !== 0x303f) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+    (codePoint >= 0xff00 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1f300 && codePoint <= 0x1faff) ||
+    (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+
+const visibleColumns = (text: string): number => {
+  let columns = 0;
+  for (const char of Array.from(text)) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === undefined || isZeroWidthCodePoint(codePoint)) continue;
+    columns += isWideCodePoint(codePoint) ? 2 : 1;
+  }
+  return columns;
+};
+
+const readAnsiEscapeAt = (text: string, index: number): string | undefined => {
+  ANSI_ESCAPE_PATTERN.lastIndex = index;
+  return ANSI_ESCAPE_PATTERN.exec(text)?.[0];
+};
+
+const truncateAnsiToColumns = (text: string, maxColumns: number): string => {
+  if (!Number.isFinite(maxColumns) || maxColumns <= 0) return '';
+
+  let output = '';
+  let columns = 0;
+  let index = 0;
+
+  while (index < text.length) {
+    const escape = readAnsiEscapeAt(text, index);
+    if (escape) {
+      output += escape;
+      index += escape.length;
+      continue;
+    }
+
+    const nextEscapeIndex = text.indexOf('\x1B', index);
+    const plainEnd = nextEscapeIndex === -1 ? text.length : nextEscapeIndex;
+    const plainText = text.slice(index, plainEnd);
+
+    for (const segment of splitGraphemes(plainText)) {
+      const width = visibleColumns(segment);
+      if (width > 0 && columns + width > maxColumns) return output;
+      output += segment;
+      columns += width;
+    }
+
+    index = plainEnd;
+  }
+
+  return output;
+};
+
+const createAnsiPipeTerminal = (stream: NodeJS.WriteStream): CliProgressTerminal => {
+  let linewrap = true;
+  let dy = 0;
+  const write = (s: string): void => {
+    stream.write(s);
+  };
+  const moveVertical = (delta: number): void => {
+    if (delta > 0) write(`\x1B[${delta}B`);
+    else if (delta < 0) write(`\x1B[${Math.abs(delta)}A`);
+  };
+
+  return {
+    cursorSave: () => write('\x1B7'),
+    cursorRestore: () => write('\x1B8'),
+    cursor: (enabled) => write(enabled ? '\x1B[?25h' : '\x1B[?25l'),
+    lineWrapping: (enabled) => {
+      linewrap = enabled;
+      write(enabled ? '\x1B[?7h' : '\x1B[?7l');
+    },
+    cursorTo: (x = null, y = null) => {
+      if (typeof y === 'number' && typeof x === 'number') {
+        write(`\x1B[${y + 1};${x + 1}H`);
+        return;
+      }
+      if (typeof x === 'number') {
+        write(x === 0 ? '\r' : `\x1B[${x + 1}G`);
+      }
+    },
+    cursorRelative: (dx = null, nextDy = null) => {
+      if (typeof dx === 'number' && dx !== 0) {
+        write(dx > 0 ? `\x1B[${dx}C` : `\x1B[${Math.abs(dx)}D`);
+      }
+      if (typeof nextDy === 'number' && nextDy !== 0) {
+        dy += nextDy;
+        moveVertical(nextDy);
+      }
+    },
+    cursorRelativeReset: () => {
+      moveVertical(-dy);
+      write('\r');
+      dy = 0;
+    },
+    clearRight: () => write('\x1B[0K'),
+    clearLine: () => write('\x1B[2K'),
+    clearBottom: () => write('\x1B[0J'),
+    newline: () => {
+      write('\n');
+      dy++;
+    },
+    write: (s, rawWrite = false) => {
+      const width = terminalColumns();
+      write(linewrap && rawWrite === false ? truncateAnsiToColumns(s, width) : s);
+    },
+    isTTY: () => true,
+    getWidth: terminalColumns,
+  };
+};
+
+const shouldBridgeRespawnProgressTty = (): boolean =>
+  process.stderr.isTTY === true || process.stdout.isTTY === true;
+
+interface RespawnExit {
+  status?: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout?: string;
+  stderr?: string;
+  message?: string;
+}
+
+const appendOutputTail = (tail: string, chunk: unknown): string => {
+  const text = Buffer.isBuffer(chunk)
+    ? chunk.toString('utf8')
+    : typeof chunk === 'string'
+      ? chunk
+      : String(chunk ?? '');
+  if (!text) return tail;
+  const next = tail + text;
+  return next.length > RESPAWN_OUTPUT_TAIL_CHARS ? next.slice(-RESPAWN_OUTPUT_TAIL_CHARS) : next;
+};
+
+/**
+ * Run the respawned analyzer while teeing child output through to the parent
+ * and keeping a bounded tail for crash classification.
+ *
+ * `execFileSync(..., { stdio: 'inherit' })` preserved live progress but hid
+ * stderr/stdout from the parent on abnormal exits. That made every
+ * SIGABRT/status-134 child look like an output-less V8 heap OOM, even when the
+ * terminal had already shown a native crash such as
+ * `libc++abi: ... Napi::Error`. Piped streams plus an explicit tee keeps the UX
+ * and gives `childProcessLikelyOom` the evidence it needs.
+ */
+const runRespawnedAnalyze = (
+  args: readonly string[],
+  env: NodeJS.ProcessEnv,
+): Promise<RespawnExit> =>
+  new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (exit: RespawnExit): void => {
+      if (settled) return;
+      settled = true;
+      resolve(exit);
+    };
+
+    const child = spawn(process.execPath, [...args], {
+      stdio: ['inherit', 'pipe', 'pipe'],
+      env,
+    });
+
+    child.stdout?.on('data', (chunk) => {
+      stdout = appendOutputTail(stdout, chunk);
+      realStdoutWrite(chunk);
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderr = appendOutputTail(stderr, chunk);
+      realStderrWrite(chunk);
+    });
+    child.on('error', (err) => {
+      finish({
+        status: 1,
+        signal: null,
+        stdout,
+        stderr,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    });
+    child.on('close', (status, signal) => {
+      finish({
+        status,
+        signal,
+        stdout,
+        stderr,
+        message: `Command failed: ${process.execPath} ${args.join(' ')}`,
+      });
+    });
+  });
+
+/**
+ * Heuristic for "child re-exec likely died from V8 OOM".
+ *
+ * Platform-independent detection is best-effort: V8/Node usually emit stable
+ * heap-exhaustion phrases in stderr/message across Linux/macOS/Windows (for
+ * example "JavaScript heap out of memory" or "Reached heap limit"). When the
+ * child produced no output at all, we still treat status 134/SIGABRT as likely
+ * heap OOM. If stderr/stdout contains a native crash diagnostic, the output
+ * evidence wins and we do not print heap guidance.
+ */
+const childProcessLikelyOom = (err: unknown): boolean => {
+  if (!err || typeof err !== 'object') return false;
+  const e = err as {
+    status?: unknown;
+    signal?: unknown;
+    stderr?: unknown;
+    stdout?: unknown;
+    message?: unknown;
+  };
+
+  const hasHeapOomSignature = (v: unknown): boolean => {
+    const text = (
+      Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : ''
+    ).toLowerCase();
+    if (!text) return false;
+    return (
+      text.includes('javascript heap out of memory') ||
+      text.includes('reached heap limit') ||
+      text.includes('allocation failed - javascript heap out of memory') ||
+      text.includes('fatalprocessoutofmemory')
+    );
+  };
+
+  const fields = [e.message, e.stderr, e.stdout];
+  if (fields.some((v) => hasHeapOomSignature(v))) return true;
+
+  const hasAnyChildOutput = [e.stderr, e.stdout].some(
+    (v) => (Buffer.isBuffer(v) && v.length > 0) || (typeof v === 'string' && v.length > 0),
+  );
+  if (hasAnyChildOutput) return false;
+
+  return e.status === 134 || e.signal === 'SIGABRT';
+};
+
+const childProcessLikelyNativeAbort = (err: unknown): boolean => {
+  if (!err || typeof err !== 'object') return false;
+  const e = err as {
+    stderr?: unknown;
+    stdout?: unknown;
+    message?: unknown;
+  };
+  const hasNativeAbortSignature = (v: unknown): boolean => {
+    const text = (
+      Buffer.isBuffer(v) ? v.toString('utf8') : typeof v === 'string' ? v : ''
+    ).toLowerCase();
+    if (!text) return false;
+    return (
+      text.includes('napi::error') ||
+      text.includes('libc++abi: terminating') ||
+      text.includes('abort trap') ||
+      text.includes('native stack') ||
+      text.includes('native worker') ||
+      text.includes('native binding')
+    );
+  };
+
+  return [e.message, e.stderr, e.stdout].some((v) => hasNativeAbortSignature(v));
+};
+
+const forceHeapOOMForTestIfEnabled = (): void => {
+  if (process.env.GITNEXUS_TEST_FORCE_HEAP_OOM !== '1') return;
+  // Allocate JS strings (not Buffers) so pressure lands on V8 heap itself.
+  // Buffers can allocate off-heap, which makes OOM triggering less reliable.
+  const chunks: string[] = [];
+  for (;;) chunks.push('x'.repeat(1024 * 1024));
+};
+
+/** Re-exec the process with a 16GB heap and larger stack if we're currently below that. */
+async function ensureHeap(): Promise<boolean> {
   const nodeOpts = process.env.NODE_OPTIONS || '';
   if (nodeOpts.includes('--max-old-space-size')) return false;
 
@@ -86,19 +428,79 @@ function ensureHeap(): boolean {
   const cliFlags = [HEAP_FLAG];
   if (!nodeOpts.includes('--stack-size')) cliFlags.push(STACK_FLAG);
 
-  try {
-    execFileSync(process.execPath, [...cliFlags, ...process.argv.slice(1)], {
-      stdio: 'inherit',
-      env: { ...process.env, NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim() },
-    });
-  } catch (e: any) {
-    process.exitCode = e.status ?? 1;
+  const childArgs = [...cliFlags, ...process.argv.slice(1)];
+  const childEnv = {
+    ...process.env,
+    NODE_OPTIONS: `${nodeOpts} ${HEAP_FLAG}`.trim(),
+  };
+  if (shouldBridgeRespawnProgressTty()) childEnv[RESPAWN_PROGRESS_ENV] = '1';
+  const childExit = await runRespawnedAnalyze(childArgs, childEnv);
+  if (childExit.status !== 0 || childExit.signal) {
+    if (childProcessLikelyOom(childExit)) {
+      cliError(
+        `  Analysis likely ran out of memory.\n` +
+          `  Retry with a larger heap if your machine allows it:\n` +
+          `    NODE_OPTIONS="--max-old-space-size=24576" gitnexus analyze [your-args]\n` +
+          `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
+          `  If this persists, it may be a native crash unrelated to heap size.\n`,
+        { recoveryHint: 'heap-oom-respawn' },
+      );
+    } else if (childProcessLikelyNativeAbort(childExit)) {
+      cliError(
+        `  Analysis aborted in a native worker or native binding path.\n` +
+          `  Try one of these recovery paths:\n` +
+          `    gitnexus analyze --workers 0\n` +
+          `    npm uninstall -g gitnexus && npm install -g gitnexus@latest\n` +
+          `    Use Node 22 LTS if you are on a newer non-LTS runtime.\n`,
+        { recoveryHint: 'native-worker-abort' },
+      );
+    }
+    const status =
+      typeof childExit.status === 'number' && childExit.status !== 0 ? childExit.status : 1;
+    process.exitCode = status;
   }
   return true;
 }
 
+/**
+ * GITNEXUS_* env vars that `analyzeCommand` writes for backward-compatible
+ * downstream consumption. Snapshotted at function entry and restored in the
+ * finally block so that programmatic callers (tests, long-running hosts)
+ * don't see leaked state across invocations. `GITNEXUS_WORKER_POOL_SIZE` is
+ * NOT in this list: that knob is threaded through `runFullAnalysis` options
+ * (see `workerPoolSize` plumbing) so the CLI never has to mutate `process.env`
+ * for it in the first place.
+ */
+const ANALYZE_CLI_ENV_KEYS = [
+  'GITNEXUS_VERBOSE',
+  'GITNEXUS_MAX_FILE_SIZE',
+  'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
+  'GITNEXUS_EMBEDDING_THREADS',
+  'GITNEXUS_EMBEDDING_BATCH_SIZE',
+  'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+  'GITNEXUS_EMBEDDING_DEVICE',
+  'GITNEXUS_ANALYZE_PROGRESS_ACTIVE',
+] as const;
+
+type AnalyzeEnvSnapshot = Record<(typeof ANALYZE_CLI_ENV_KEYS)[number], string | undefined>;
+
+const snapshotAnalyzeEnv = (): AnalyzeEnvSnapshot => {
+  const snap = {} as AnalyzeEnvSnapshot;
+  for (const k of ANALYZE_CLI_ENV_KEYS) snap[k] = process.env[k];
+  return snap;
+};
+
+const restoreAnalyzeEnv = (snap: AnalyzeEnvSnapshot): void => {
+  for (const k of ANALYZE_CLI_ENV_KEYS) {
+    const v = snap[k];
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+};
+
 export interface AnalyzeOptions {
   force?: boolean;
+  repairFts?: boolean;
   /**
    * Embedding generation toggle. Commander parses `--embeddings [limit]` as:
    *   - `undefined` when the flag is omitted
@@ -158,6 +560,8 @@ export interface AnalyzeOptions {
   maxFileSize?: string;
   /** Override worker sub-batch idle timeout in seconds. */
   workerTimeout?: string;
+  /** Parse worker pool size; 0 disables workers (sequential fallback). */
+  workers?: string;
   embeddingThreads?: string;
   embeddingBatchSize?: string;
   embeddingSubBatchSize?: string;
@@ -183,13 +587,30 @@ export const shouldGenerateCommunitySkillFiles = (
 ): boolean => Boolean(options?.skills && pipelineResult && !options?.indexOnly);
 
 export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOptions) => {
-  if (ensureHeap()) return;
+  if (await ensureHeap()) return;
+  forceHeapOOMForTestIfEnabled();
 
   // Install fatal handlers immediately after re-exec resolution so any
   // async error that escapes the try/catch below (#1169) surfaces with
   // a stack trace and a non-zero exit code instead of a silent exit 0.
   installFatalHandlers();
 
+  // Snapshot the GITNEXUS_* env vars that the impl writes for downstream
+  // consumption, so they don't leak across `analyzeCommand` invocations in
+  // programmatic callers (tests, long-running hosts). `process.exit(0)` on
+  // the success path bypasses `finally` — intentional: when the process is
+  // exiting, restoration is moot. For early-return paths (validation
+  // errors) and the alreadyUpToDate fast path the finally restores the
+  // pre-call values.
+  const envSnap = snapshotAnalyzeEnv();
+  try {
+    await analyzeCommandImpl(inputPath, options);
+  } finally {
+    restoreAnalyzeEnv(envSnap);
+  }
+};
+
+const analyzeCommandImpl = async (inputPath?: string, options?: AnalyzeOptions): Promise<void> => {
   if (options?.verbose) {
     process.env.GITNEXUS_VERBOSE = '1';
   }
@@ -210,6 +631,26 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     );
   }
 
+  // `--workers` is threaded through `runFullAnalysis` options → PipelineOptions
+  // → createWorkerPool, intentionally bypassing the GITNEXUS_WORKER_POOL_SIZE
+  // env channel so this CLI surface never mutates `process.env` for pool size.
+  // Tests can therefore re-invoke analyzeCommand with different --workers
+  // values back-to-back and observe the value they passed, not whatever the
+  // previous call leaked.
+  let workerPoolSize: number | undefined;
+  if (options?.workers !== undefined) {
+    const parsedWorkers = Number(options.workers);
+    if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
+      cliError(
+        '  --workers must be a non-negative integer. ' +
+          'Pass 0 to disable the worker pool (sequential fallback).\n',
+      );
+      process.exitCode = 1;
+      return;
+    }
+    workerPoolSize = parsedWorkers;
+  }
+
   // Parse `--embeddings [limit]`: `true` → default cap, string → numeric cap
   // (0 disables the cap entirely). Validated up here so failures match the
   // sibling-validation pattern (exit before bar.start() — otherwise
@@ -275,6 +716,15 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     process.env.GITNEXUS_EMBEDDING_DEVICE = options.embeddingDevice;
   }
 
+  if (options?.repairFts && options?.force) {
+    cliError(
+      '  Cannot combine `--repair-fts` with `--force`. ' +
+        'Use `--repair-fts` for fast FTS-only repair, or `--force` for a full rebuild.\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   console.log('\n  GitNexus Analyzer\n');
 
   // `--index-only` is the stronger contract — it suppresses every form of file
@@ -360,19 +810,25 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   }
 
   // ── CLI progress bar setup ─────────────────────────────────────────
-  const bar = new cliProgress.SingleBar(
-    {
-      format: '  {bar} {percentage}% | {phase}',
-      barCompleteChar: '\u2588',
-      barIncompleteChar: '\u2591',
-      hideCursor: true,
-      barGlue: '',
-      autopadding: true,
-      clearOnComplete: false,
-      stopOnComplete: false,
-    },
-    cliProgress.Presets.shades_grey,
-  );
+  const barOptions: cliProgress.Options & { terminal?: CliProgressTerminal } = {
+    format: '  {bar} {percentage}% | {phase}',
+    barCompleteChar: '\u2588',
+    barIncompleteChar: '\u2591',
+    hideCursor: true,
+    barGlue: '',
+    autopadding: true,
+    clearOnComplete: false,
+    stopOnComplete: false,
+  };
+  if (process.env[RESPAWN_PROGRESS_ENV] === '1' && process.stderr.isTTY !== true) {
+    // Heap respawn pipes stderr so the parent can classify native/OOM crashes.
+    // The parent was a real TTY when it opted into this env var, so forward
+    // ANSI cursor controls through the pipe instead of cli-progress' non-TTY
+    // newline mode. That keeps one-line redraw UX while retaining stderr tail
+    // capture for diagnostics.
+    barOptions.terminal = createAnsiPipeTerminal(process.stderr);
+  }
+  const bar = new cliProgress.SingleBar(barOptions, cliProgress.Presets.shades_grey);
 
   bar.start(100, 0, { phase: 'Initializing...' });
 
@@ -406,7 +862,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   const origError = console.error.bind(console);
   let barCurrentValue = 0;
-  const barLog = (...args: any[]) => {
+  const barLog = (...args: unknown[]) => {
     process.stdout.write('\x1b[2K\r');
     origLog(args.map((a) => (typeof a === 'string' ? a : String(a))).join(' '));
     bar.update(barCurrentValue);
@@ -416,6 +872,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
   console.warn = barLog;
   // eslint-disable-next-line no-console -- intentional console-routing for progress bar UX
   console.error = barLog;
+  process.env.GITNEXUS_ANALYZE_PROGRESS_ACTIVE = '1';
 
   // Track elapsed time per phase
   let lastPhaseLabel = 'Initializing...';
@@ -453,9 +910,11 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
         // needs a fresh pipelineResult. Has no bearing on the registry
         // collision guard (see allowDuplicateName below).
         force: options?.force || options?.skills,
+        repairFts: options?.repairFts,
         embeddings: embeddingsEnabled,
         embeddingsNodeLimit,
         dropEmbeddings: options?.dropEmbeddings,
+        verbose: options?.verbose,
         skipGit: options?.skipGit,
         skipAgentsMd,
         skipSkills,
@@ -471,6 +930,10 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
         // 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,
+        // Worker pool size threaded from --workers, replacing the previous
+        // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
+        // env / auto-formula fallback inside the pipeline.
+        workerPoolSize,
       },
       {
         onProgress: (_phase, percent, message) => {
@@ -500,6 +963,19 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       return;
     }
 
+    if (result.ftsRepairedOnly) {
+      clearInterval(elapsedTimer);
+      process.removeListener('SIGINT', sigintHandler);
+      console.log = origLog;
+      // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+      console.warn = origWarn;
+      // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
+      console.error = origError;
+      bar.stop();
+      console.log('  FTS indexes repaired successfully\n');
+      return;
+    }
+
     // Post-finalize invariant (#1169): runFullAnalysis nominally writes
     // meta.json and registers the repo, but on Windows it has been
     // observed to return successfully with neither artifact present
@@ -595,7 +1071,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     }
 
     console.log('');
-  } catch (err: any) {
+  } catch (err: unknown) {
     clearInterval(elapsedTimer);
     process.removeListener('SIGINT', sigintHandler);
     console.log = origLog;
@@ -605,7 +1081,7 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
     console.error = origError;
     bar.stop();
 
-    const msg = err.message || String(err);
+    const msg = err instanceof Error ? err.message : String(err);
 
     // Registry name-collision from --name (#829) — surface as an
     // actionable error rather than a generic stack-trace.
@@ -638,6 +1114,20 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption
       return;
     }
 
+    // WAL corruption — the index file is unreadable. Give a clear recovery
+    // path without a confusing stack trace (the native error message alone
+    // is enough signal).
+    if (isWalCorruptionError(err) || msg.includes('LadybugDB WAL corruption')) {
+      cliError(
+        `  The GitNexus index has a corrupted WAL file.\n` +
+          `  This usually happens when a previous analysis was interrupted mid-write.\n` +
+          `  ${WAL_RECOVERY_SUGGESTION}\n`,
+        { recoveryHint: 'wal-corruption' },
+      );
+      process.exitCode = 1;
+      return;
+    }
+
     // HF download failure — show clean guidance without the raw stack trace.
     // Checked before writeFatalToStderr so the user sees one focused message
     // rather than a stack-trace dump followed by a second remediation block.

gitnexus/src/cli/eval-server.ts

@@ -14,9 +14,14 @@
  *   Agent bash cmd → curl localhost:PORT/tool/query → eval-server → LocalBackend → format → text
  *
  * Usage:
- *   gitnexus eval-server                    # default port 4848
- *   gitnexus eval-server --port 4848        # explicit port
- *   gitnexus eval-server --idle-timeout 300 # auto-shutdown after 300s idle
+ *   gitnexus eval-server                        # default port 4848, binds 127.0.0.1
+ *   gitnexus eval-server --port 4848            # explicit port
+ *   gitnexus eval-server --host 0.0.0.0         # reachable from other VMs / containers
+ *   gitnexus eval-server --idle-timeout 300     # auto-shutdown after 300s idle
+ *
+ * READY signal format: GITNEXUS_EVAL_SERVER_READY:<host>:<port>
+ *   IPv4: GITNEXUS_EVAL_SERVER_READY:127.0.0.1:4848
+ *   IPv6: GITNEXUS_EVAL_SERVER_READY:[::1]:4848
  *
  * API:
  *   POST /tool/:name   — Call a tool. Body is JSON arguments. Returns formatted text.
@@ -25,16 +30,30 @@
  */
 
 import http from 'http';
+import { isIPv4, isIPv6 } from 'node:net';
 import { writeSync } from 'node:fs';
 import { LocalBackend } from '../mcp/local/local-backend.js';
 import { logger } from '../core/logger.js';
-import { cliInfo, cliWarn } from './cli-message.js';
+import { cliInfo, cliWarn, cliError } from './cli-message.js';
 
 export interface EvalServerOptions {
   port?: string;
+  host?: string;
   idleTimeout?: string;
 }
 
+/**
+ * Validate the --host value. Accepts IPv4, IPv6, or "localhost".
+ * Returns the host string unchanged, or null if invalid.
+ * "localhost" is passed through so the OS resolves it to the correct loopback
+ * address (127.0.0.1 or ::1) at bind time rather than forcing IPv4.
+ */
+export function validateHost(raw: string): string | null {
+  if (raw === 'localhost') return raw;
+  if (isIPv4(raw) || isIPv6(raw)) return raw;
+  return null;
+}
+
 // ─── Text Formatters ──────────────────────────────────────────────────
 // Convert structured JSON results into compact, LLM-friendly text.
 // Design: minimize tokens, maximize actionability.
@@ -330,6 +349,22 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
   const port = parseInt(options?.port || '4848');
   const idleTimeoutSec = parseInt(options?.idleTimeout || '0');
 
+  const rawHost = options?.host ?? '127.0.0.1';
+  const host = validateHost(rawHost);
+  if (!host) {
+    cliError(
+      `Invalid --host value "${rawHost}":\n` +
+        `  Must be an IP address or "localhost".\n\n` +
+        `  Examples:\n` +
+        `    gitnexus eval-server --host 127.0.0.1    (loopback only, default)\n` +
+        `    gitnexus eval-server --host 0.0.0.0      (all network interfaces)\n` +
+        `    gitnexus eval-server --host 192.168.1.5  (specific interface)\n` +
+        `    gitnexus eval-server --host localhost     (OS-resolved loopback)\n`,
+      { flag: '--host', value: rawHost },
+    );
+    process.exit(1);
+  }
+
   const backend = new LocalBackend();
   const ok = await backend.init();
 
@@ -426,12 +461,72 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
     }
   });
 
-  server.listen(port, '127.0.0.1', () => {
+  server.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EADDRINUSE') {
+      cliError(
+        `\nGitNexus eval-server failed to start:\n` +
+          `  Port ${port} is already in use.\n\n` +
+          `  Either:\n` +
+          `    1. Stop the process already using port ${port}\n` +
+          `    2. Use a different port: gitnexus eval-server --port 4849\n`,
+        { code: err.code, port, host },
+      );
+    } else if (err.code === 'EADDRNOTAVAIL') {
+      // "localhost" may resolve to ::1 on IPv6-only systems; treat it as
+      // potentially IPv6 so the user gets the right diagnostic hint.
+      const isIPv6Host = isIPv6(host) || host === 'localhost';
+      cliError(
+        `\nGitNexus eval-server failed to start:\n` +
+          `  Address ${host} is not available on this machine.\n\n` +
+          (isIPv6Host
+            ? `  Address ${host} resolved but is not reachable — IPv6 may be disabled, or the loopback interface may be unavailable.\n` +
+              `  Docker containers and many CI environments disable IPv6 by default.\n\n`
+            : `  The --host value must be an IP assigned to a local network interface.\n` +
+              `  Run \`ip addr\` (Linux) or \`ipconfig\` (Windows) to list available addresses.\n\n`) +
+          `  Common fixes:\n` +
+          `    gitnexus eval-server --host 127.0.0.1  (loopback, this machine only)\n` +
+          `    gitnexus eval-server --host 0.0.0.0    (all interfaces, reachable from other VMs)\n`,
+        { code: err.code, port, host },
+      );
+    } else if (err.code === 'EACCES') {
+      cliError(
+        `\nGitNexus eval-server failed to start:\n` +
+          `  Permission denied binding to port ${port}.\n\n` +
+          `  Ports below 1024 require elevated privileges.\n` +
+          `  Use a port above 1024: gitnexus eval-server --port 4848\n`,
+        { code: err.code, port, host },
+      );
+    } else {
+      cliError(`\nGitNexus eval-server failed to start:\n  ${err.message}\n`, {
+        code: err.code,
+        port,
+        host,
+      });
+    }
+    process.exit(1);
+  });
+
+  server.listen(port, host, () => {
     // Plain-text banner for the human watching stderr; structured record
     // for log aggregation (split into two so the user sees a real banner
     // not `{"level":30,"msg":"...","port":4747,"endpoints":[...]}`).
+    // Use server.address() so the banner and READY signal reflect what the OS
+    // actually bound to, not the input host string. This matters when "localhost"
+    // is passed: the OS may resolve it to ::1 on some systems.
+    const addr = server.address();
+    // server.listen callback only fires after a successful TCP bind, so
+    // server.address() is guaranteed to return an AddressInfo object here.
+    if (typeof addr !== 'object' || addr === null) {
+      cliError(
+        `\nGitNexus eval-server: unexpected server.address() value after bind: ${JSON.stringify(addr)}\n`,
+      );
+      process.exit(1);
+    }
+    const boundPort = addr.port;
+    const boundAddress = addr.address;
+    const displayHost = boundAddress.includes(':') ? `[${boundAddress}]` : boundAddress;
     const bannerLines = [
-      `GitNexus eval-server: listening on http://127.0.0.1:${port}`,
+      `GitNexus eval-server: listening on http://${displayHost}:${boundPort}`,
       `  POST /tool/query    — search execution flows`,
       `  POST /tool/context  — 360-degree symbol view`,
       `  POST /tool/impact   — blast radius analysis`,
@@ -443,8 +538,8 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
       bannerLines.push(`  Auto-shutdown after ${idleTimeoutSec}s idle`);
     }
     cliInfo(bannerLines.join('\n'), {
-      port,
-      host: '127.0.0.1',
+      port: boundPort,
+      host,
       idleTimeoutSec: idleTimeoutSec > 0 ? idleTimeoutSec : undefined,
       endpoints: [
         'POST /tool/query',
@@ -457,7 +552,7 @@ export async function evalServerCommand(options?: EvalServerOptions): Promise<vo
     });
     try {
       // Use fd 1 directly — LadybugDB captures process.stdout (#324)
-      writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${port}\n`);
+      writeSync(1, `GITNEXUS_EVAL_SERVER_READY:${displayHost}:${boundPort}\n`);
     } catch {
       // stdout may not be available (e.g., broken pipe)
     }

gitnexus/src/cli/index.ts

@@ -23,6 +23,7 @@ program
   .command('analyze [path]')
   .description('Index a repository (full analysis)')
   .option('-f, --force', 'Force full re-index even if up to date')
+  .option('--repair-fts', 'Repair/rebuild search FTS indexes without full re-analysis')
   .option(
     '--embeddings [limit]',
     'Enable embedding generation for semantic search (off by default). ' +
@@ -70,6 +71,10 @@ program
     '--worker-timeout <seconds>',
     'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
   )
+  .option(
+    '--workers <n>',
+    'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).',
+  )
   .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
   .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
   .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
@@ -81,6 +86,11 @@ program
       '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
       '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
       '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
+      '  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n' +
+      '  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n' +
+      '  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n' +
+      '  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n' +
+      '  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n' +
       '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
       '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
       '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +
@@ -161,11 +171,15 @@ program
   )
   .option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)')
   .option('--concurrency <n>', 'Parallel LLM calls (default: 3)', '3')
-  .option('--timeout <seconds>', 'Per-attempt LLM request timeout in seconds (default: 60)')
+  .option('--timeout <seconds>', 'LLM request timeout in seconds (default: disabled)')
   .option('--retries <n>', 'Max LLM retry attempts per request (default: 3)')
   .option('--gist', 'Publish wiki as a public GitHub Gist after generation')
   .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)')
   .option('--review', 'Stop after grouping to review module structure before generating pages')
+  .option(
+    '--lang <lang>',
+    'Output language for generated documentation (e.g. english, chinese, spanish, japanese)',
+  )
   .action(createLazyAction(() => import('./wiki.js'), 'wikiCommand'));
 
 program
@@ -237,6 +251,10 @@ program
   .command('eval-server')
   .description('Start lightweight HTTP server for fast tool calls during evaluation')
   .option('-p, --port <port>', 'Port number', '4848')
+  .option(
+    '--host <host>',
+    'Bind address (default: 127.0.0.1, use 0.0.0.0 to expose to all interfaces)',
+  )
   .option('--idle-timeout <seconds>', 'Auto-shutdown after N seconds idle (0 = disabled)', '0')
   .action(createLazyAction(() => import('./eval-server.js'), 'evalServerCommand'));
 

gitnexus/src/cli/optional-grammars.ts

@@ -1,15 +1,18 @@
 /**
  * Optional grammar availability check.
  *
- * tree-sitter-dart and tree-sitter-proto are optionalDependencies that
- * require a `node-gyp rebuild` at install time. The build can be skipped
- * via GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or it can
- * silently soft-fail when the C++ toolchain is missing.
+ * tree-sitter-dart, tree-sitter-proto, and tree-sitter-swift are vendored
+ * under vendor/ and materialized into node_modules/ at postinstall. Dart
+ * and Proto are built from source with node-gyp; Swift ships platform
+ * prebuilds activated via node-gyp-build. All three can be skipped via
+ * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
+ * soft-fail when the toolchain is missing (Dart/Proto) or no prebuild
+ * matches the host platform (Swift).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
- * stderr line per missing grammar so users learn why .dart/.proto support
- * is unavailable instead of silently getting a degraded index.
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift
+ * support is unavailable instead of silently getting a degraded index.
  */
 
 import { createRequire } from 'module';
@@ -29,6 +32,7 @@ interface OptionalGrammar {
 const OPTIONAL_GRAMMARS: OptionalGrammar[] = [
   { name: 'tree-sitter-dart', pkg: 'tree-sitter-dart', extensions: ['.dart'] },
   { name: 'tree-sitter-proto', pkg: 'tree-sitter-proto', extensions: ['.proto'] },
+  { name: 'tree-sitter-swift', pkg: 'tree-sitter-swift', extensions: ['.swift'] },
 ];
 
 export interface MissingGrammar {
@@ -40,8 +44,8 @@ export interface MissingGrammar {
  * Returns the list of optional grammars whose native binding cannot be
  * loaded. Actually `require()`s the package — `require.resolve` would
  * locate the entry path even when the `.node` binding is absent (the
- * `file:` package directory is installed regardless of postinstall
- * outcome), giving false negatives for the exact users we want to warn:
+ * package directory exists without a working `.node` binding), giving false
+ * negatives for the exact users we want to warn:
  * those who installed with `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` or whose
  * native rebuild soft-failed for missing toolchain.
  *

gitnexus/src/cli/serve.ts

@@ -1,6 +1,7 @@
 import { createServer } from '../server/api.js';
 import { logger, flushLoggerSync } from '../core/logger.js';
 import { cliError } from './cli-message.js';
+import { isWalCorruptionError, WAL_RECOVERY_SUGGESTION } from '../core/lbug/lbug-config.js';
 
 // Catch anything that would cause a silent exit. Pino v10's default
 // destination is `sync: false` (SonicBoom buffered) — call
@@ -34,7 +35,13 @@ export const serveCommand = async (options?: { port?: string; host?: string }) =
   try {
     await createServer(port, host);
   } catch (err: any) {
-    if (err.code === 'EADDRINUSE') {
+    if (isWalCorruptionError(err)) {
+      cliError(
+        `\nGitNexus server could not start: the index has a corrupted WAL file.\n` +
+          `  ${WAL_RECOVERY_SUGGESTION}\n`,
+        { recoveryHint: 'wal-corruption' },
+      );
+    } else if (err.code === 'EADDRINUSE') {
       cliError(
         `\nFailed to start GitNexus server:\n` +
           `  ${err.message || err}\n\n` +

gitnexus/src/cli/setup.ts

@@ -61,11 +61,13 @@ function resolveGitnexusBin(): string | null {
       .filter(Boolean);
 
     if (isWin) {
-      // On Windows, `where` returns multiple entries (e.g. the POSIX shell
-      // script AND the .cmd/.bat wrapper). Prefer the wrapper because
-      // child_process.spawn() cannot execute a shell script directly.
+      // On Windows, npm global installs can surface multiple launchers for the
+      // same package (e.g. a POSIX shell shim plus .cmd/.bat wrappers). Claude
+      // and the other MCP hosts need a directly spawnable command path, so only
+      // accept the Windows wrapper. If it is missing, fall back to the slower
+      // npx entry instead of persisting a non-spawnable shim path.
       const cmdLine = lines.find((l) => /\.(cmd|bat)$/i.test(l));
-      return cmdLine || lines[0] || null;
+      return cmdLine || null;
     }
 
     return lines[0] || null;

gitnexus/src/cli/wiki.ts

@@ -35,6 +35,24 @@ export interface WikiCommandOptions {
   review?: boolean;
   timeout?: string;
   retries?: string;
+  lang?: string;
+}
+
+function parsePositiveIntegerOption(
+  value: string | undefined,
+  flag: string,
+  multiplier = 1,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (!/^[1-9]\d*$/.test(trimmed)) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  const parsed = parseInt(trimmed, 10);
+  if (parsed > Math.floor(Number.MAX_SAFE_INTEGER / multiplier)) {
+    throw new Error(`${flag} is too large`);
+  }
+  return parsed;
 }
 
 /**
@@ -89,6 +107,24 @@ function prompt(question: string, hide = false): Promise<string> {
 }
 
 export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptions) => {
+  // Snapshot GITNEXUS_VERBOSE at entry — wikiCommand mutates it (the impl
+  // below) so cursor-client (process.env-driven) sees the right value during
+  // this run. Restored in finally so back-to-back wiki calls in long-running
+  // hosts don't leak verbose state from one invocation to the next. Pairs
+  // with the same snapshot/restore pattern in `analyzeCommand`.
+  const originalVerbose = process.env.GITNEXUS_VERBOSE;
+  try {
+    await wikiCommandImpl(inputPath, options);
+  } finally {
+    if (originalVerbose === undefined) {
+      delete process.env.GITNEXUS_VERBOSE;
+    } else {
+      process.env.GITNEXUS_VERBOSE = originalVerbose;
+    }
+  }
+};
+
+const wikiCommandImpl = async (inputPath?: string, options?: WikiCommandOptions): Promise<void> => {
   // Set verbose mode globally for cursor-client to pick up
   if (options?.verbose) {
     process.env.GITNEXUS_VERBOSE = '1';
@@ -127,6 +163,17 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
     return;
   }
 
+  let timeoutSeconds: number | undefined;
+  let retries: number | undefined;
+  try {
+    timeoutSeconds = parsePositiveIntegerOption(options?.timeout, '--timeout', 1000);
+    retries = parsePositiveIntegerOption(options?.retries, '--retries');
+  } catch (error) {
+    console.log(`  Error: ${(error as Error).message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   // ── Resolve LLM config (with interactive fallback) ─────────────────
   // Save any CLI overrides immediately
   if (
@@ -350,13 +397,11 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
   }
 
   // ── Apply per-run overrides not saved to config ────────────────────
-  if (options?.timeout) {
-    const secs = parseInt(options.timeout, 10);
-    if (!isNaN(secs) && secs > 0) llmConfig.requestTimeoutMs = secs * 1000;
+  if (timeoutSeconds !== undefined) {
+    llmConfig.requestTimeoutMs = timeoutSeconds * 1000;
   }
-  if (options?.retries) {
-    const n = parseInt(options.retries, 10);
-    if (!isNaN(n) && n > 0) llmConfig.maxAttempts = n;
+  if (retries !== undefined) {
+    llmConfig.maxAttempts = retries;
   }
 
   // ── Setup progress bar with elapsed timer ──────────────────────────
@@ -395,6 +440,7 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
     force: options?.force,
     concurrency: options?.concurrency ? parseInt(options.concurrency, 10) : undefined,
     reviewOnly: options?.review,
+    lang: options?.lang,
   };
 
   const generator = new WikiGenerator(
@@ -563,6 +609,8 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio
 
     if (err.message?.includes('No source files')) {
       console.log(`\n  ${err.message}\n`);
+    } else if (err.message?.includes('LLM request timed out after')) {
+      console.log(`\n  Timeout: ${err.message}\n`);
     } else if (err.message?.includes('content filter')) {
       // Content filter block — actionable message
       console.log(`\n  Content Filter: ${err.message}\n`);

gitnexus/src/core/group/extractors/http-patterns/python.ts

@@ -13,7 +13,12 @@ import type { HttpDetection, HttpLanguagePlugin } from './types.js';
  *   - FastAPI `@app.get("/path")` provider decorators
  *   - `requests.get/post/...("url")` consumer calls
  *   - Generic `requests.request("METHOD", "url")` consumer calls
- *   - `httpx.AsyncClient` instances calling `.get/.post/...("url")`
+ *   - `httpx.AsyncClient` instances calling `.get/.post/...("url")`, including
+ *     aliased imports such as `import httpx as hx`,
+ *     `from httpx import AsyncClient`, and
+ *     `from httpx import AsyncClient as HttpxAsyncClient`.
+ *     Locally rebound names (e.g. `AsyncClient = mock_factory()` inside a
+ *     function) are excluded to avoid false-positive consumer contracts.
  */
 
 const FASTAPI_VERBS: Record<string, string> = {
@@ -80,12 +85,50 @@ const REQUESTS_GENERIC_PATTERNS = compilePatterns({
 } satisfies LanguagePatterns<Record<string, never>>);
 
 // ─── Consumer: httpx.AsyncClient assignments ────────────────────────
-// NOTE: This targeted detector only tracks explicit `httpx.AsyncClient(...)`
-// construction. Direct imports (`from httpx import AsyncClient`) and module
-// aliases (`import httpx as hx`) and annotated assignments (`client: httpx.AsyncClient = ...`)
-// are intentionally left for a follow-up. Module-scope clients are only matched
+// Module-scope clients are only matched
 // at module scope; calls inside functions require a function/class-local tracked
 // client to avoid false positives from same-name local variables.
+const HTTPX_MODULE_IMPORT_PATTERNS = compilePatterns({
+  name: 'python-httpx-module-imports',
+  language: Python,
+  patterns: [
+    {
+      meta: {},
+      query: `
+        (import_statement
+          name: (aliased_import
+            name: (dotted_name (identifier) @module)
+            alias: (identifier) @alias))
+      `,
+    },
+  ],
+} satisfies LanguagePatterns<Record<string, never>>);
+
+const HTTPX_ASYNC_CLIENT_IMPORT_PATTERNS = compilePatterns({
+  name: 'python-httpx-async-client-imports',
+  language: Python,
+  patterns: [
+    {
+      meta: {},
+      query: `
+        (import_from_statement
+          module_name: (dotted_name (identifier) @module)
+          name: (dotted_name (identifier) @client_class))
+      `,
+    },
+    {
+      meta: {},
+      query: `
+        (import_from_statement
+          module_name: (dotted_name (identifier) @module)
+          name: (aliased_import
+            name: (dotted_name (identifier) @client_class)
+            alias: (identifier) @alias))
+      `,
+    },
+  ],
+} satisfies LanguagePatterns<Record<string, never>>);
+
 const HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS = compilePatterns({
   name: 'python-httpx-async-client-assign',
   language: Python,
@@ -97,8 +140,24 @@ const HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS = compilePatterns({
           left: (_) @client
           right: (call
             function: (attribute
-              object: (identifier) @module (#eq? @module "httpx")
-              attribute: (identifier) @client_class (#eq? @client_class "AsyncClient"))))
+              object: (identifier) @module
+              attribute: (identifier) @client_class)))
+      `,
+    },
+  ],
+} satisfies LanguagePatterns<Record<string, never>>);
+
+const HTTPX_ASYNC_CLIENT_DIRECT_ASSIGN_PATTERNS = compilePatterns({
+  name: 'python-httpx-async-client-direct-assign',
+  language: Python,
+  patterns: [
+    {
+      meta: {},
+      query: `
+        (assignment
+          left: (_) @client
+          right: (call
+            function: (identifier) @client_class))
       `,
     },
   ],
@@ -115,8 +174,24 @@ const HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS = compilePatterns({
         (as_pattern
           (call
             function: (attribute
-              object: (identifier) @module (#eq? @module "httpx")
-              attribute: (identifier) @client_class (#eq? @client_class "AsyncClient")))
+              object: (identifier) @module
+              attribute: (identifier) @client_class))
+          (as_pattern_target (identifier) @client))
+      `,
+    },
+  ],
+} satisfies LanguagePatterns<Record<string, never>>);
+
+const HTTPX_ASYNC_CLIENT_DIRECT_WITH_ALIAS_PATTERNS = compilePatterns({
+  name: 'python-httpx-async-client-direct-with-alias',
+  language: Python,
+  patterns: [
+    {
+      meta: {},
+      query: `
+        (as_pattern
+          (call
+            function: (identifier) @client_class)
           (as_pattern_target (identifier) @client))
       `,
     },
@@ -150,17 +225,137 @@ function trackedClientScopeKey(clientNode: Parser.SyntaxNode): string {
 }
 
 function callScopeKeys(clientNode: Parser.SyntaxNode): string[] {
-  const keys = new Set<string>();
-  const preferClass = clientNode.text.includes('.');
-  const nearestScope = getScopeKey(clientNode.parent, preferClass);
+  return [getScopeKey(clientNode.parent, clientNode.text.includes('.'))];
+}
 
-  keys.add(nearestScope);
+// Returns the scope key that a rebind of an imported alias would shadow under
+// Python LEGB rules, or `null` when the rebind does not shadow anything that
+// could produce a false-positive consumer detection.
+//   - Rebind inside a function/method → that function's scope.
+//   - Rebind at module top level → 'module' (shadows the whole file).
+//   - Rebind in a class body without an enclosing function → null. Python
+//     class attributes do not shadow bare-name lookups inside methods (methods
+//     see the module binding, not the class attribute), so we must not poison
+//     them.
+function shadowScopeKey(node: Parser.SyntaxNode | null): string | null {
+  let current = node;
+  let passedThroughClass = false;
+  while (current) {
+    if (current.type === 'function_definition') {
+      // Reuse getScopeKey's key format so the two helpers cannot drift apart.
+      return getScopeKey(current);
+    }
+    if (current.type === 'class_definition') {
+      passedThroughClass = true;
+    }
+    current = current.parent;
+  }
+  return passedThroughClass ? null : 'module';
+}
 
-  return [...keys];
+function collectHttpxImportAliases(tree: Parser.Tree): {
+  moduleAliases: Set<string>;
+  asyncClientAliases: Set<string>;
+} {
+  const moduleAliases = new Set<string>(['httpx']);
+  const asyncClientAliases = new Set<string>();
+
+  // The @module capture is a single identifier inside a `dotted_name`, so for
+  // `import package.httpx as hx` the pattern would match the inner `httpx`
+  // segment. Check the full `dotted_name` text via `parent` to anchor the match.
+  for (const match of runCompiledPatterns(HTTPX_MODULE_IMPORT_PATTERNS, tree)) {
+    const moduleNode = match.captures.module;
+    const aliasNode = match.captures.alias;
+    if (moduleNode?.parent?.text === 'httpx' && aliasNode) moduleAliases.add(aliasNode.text);
+  }
+
+  for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_IMPORT_PATTERNS, tree)) {
+    const moduleNode = match.captures.module;
+    const classNode = match.captures.client_class;
+    if (moduleNode?.parent?.text !== 'httpx' || classNode?.text !== 'AsyncClient') continue;
+    asyncClientAliases.add(match.captures.alias?.text ?? classNode.text);
+  }
+
+  return { moduleAliases, asyncClientAliases };
+}
+
+// Tracks local rebindings (`AsyncClient = ...`, `hx = ...`) that shadow an
+// imported alias. We treat the whole enclosing scope (module, class, or
+// function) as shadowed for that alias name, so subsequent constructions in
+// that scope are not falsely detected as httpx consumers. Covers bare-identifier
+// targets and the common tuple / list destructuring shapes.
+const ALIAS_SHADOW_PATTERNS = compilePatterns({
+  name: 'python-httpx-alias-shadow',
+  language: Python,
+  patterns: [
+    {
+      meta: {},
+      query: `(assignment left: (identifier) @name)`,
+    },
+    {
+      meta: {},
+      query: `(assignment left: (pattern_list (identifier) @name))`,
+    },
+    {
+      meta: {},
+      query: `(assignment left: (tuple_pattern (identifier) @name))`,
+    },
+    {
+      meta: {},
+      query: `(assignment left: (list_pattern (identifier) @name))`,
+    },
+  ],
+} satisfies LanguagePatterns<Record<string, never>>);
+
+function collectAliasShadowScopes(
+  tree: Parser.Tree,
+  aliases: Set<string>,
+): Map<string, Set<string>> {
+  const shadowed = new Map<string, Set<string>>();
+  if (aliases.size === 0) return shadowed;
+
+  for (const match of runCompiledPatterns(ALIAS_SHADOW_PATTERNS, tree)) {
+    const nameNode = match.captures.name;
+    if (!nameNode || !aliases.has(nameNode.text)) continue;
+    const scopeKey = shadowScopeKey(nameNode.parent);
+    if (scopeKey === null) continue;
+    const set = shadowed.get(nameNode.text) ?? new Set<string>();
+    set.add(scopeKey);
+    shadowed.set(nameNode.text, set);
+  }
+
+  return shadowed;
+}
+
+function isAliasShadowed(
+  shadowed: Map<string, Set<string>>,
+  aliasName: string,
+  node: Parser.SyntaxNode,
+): boolean {
+  const scopes = shadowed.get(aliasName);
+  if (!scopes || scopes.size === 0) return false;
+  let current: Parser.SyntaxNode | null = node.parent;
+  while (current) {
+    if (current.type === 'function_definition') {
+      // Reuse getScopeKey's key format so the two helpers cannot drift apart.
+      if (scopes.has(getScopeKey(current))) return true;
+    }
+    current = current.parent;
+  }
+  // A module-level rebind shadows the alias for the entire file.
+  return scopes.has('module');
 }
 
 function collectHttpxAsyncClients(tree: Parser.Tree): Map<string, Set<string>> {
   const clients = new Map<string, Set<string>>();
+  const { moduleAliases, asyncClientAliases } = collectHttpxImportAliases(tree);
+  // Module aliases (`hx`) and AsyncClient aliases (`AsyncClient`,
+  // `HttpxAsyncClient`) share disjoint name spaces, so one shadow map keyed by
+  // alias name serves both lookups and we only walk the tree for rebinds once.
+  const shadowed = collectAliasShadowScopes(
+    tree,
+    new Set([...moduleAliases, ...asyncClientAliases]),
+  );
 
   const addClient = (clientNode: Parser.SyntaxNode | undefined) => {
     if (!clientNode) return;
@@ -172,10 +367,34 @@ function collectHttpxAsyncClients(tree: Parser.Tree): Map<string, Set<string>> {
   };
 
   for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_ASSIGN_PATTERNS, tree)) {
+    const moduleNode = match.captures.module;
+    const classNode = match.captures.client_class;
+    if (!moduleNode || !classNode) continue;
+    if (!moduleAliases.has(moduleNode.text) || classNode.text !== 'AsyncClient') continue;
+    if (isAliasShadowed(shadowed, moduleNode.text, moduleNode)) continue;
+    addClient(match.captures.client);
+  }
+
+  for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_DIRECT_ASSIGN_PATTERNS, tree)) {
+    const classNode = match.captures.client_class;
+    if (!classNode || !asyncClientAliases.has(classNode.text)) continue;
+    if (isAliasShadowed(shadowed, classNode.text, classNode)) continue;
     addClient(match.captures.client);
   }
 
   for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_WITH_ALIAS_PATTERNS, tree)) {
+    const moduleNode = match.captures.module;
+    const classNode = match.captures.client_class;
+    if (!moduleNode || !classNode) continue;
+    if (!moduleAliases.has(moduleNode.text) || classNode.text !== 'AsyncClient') continue;
+    if (isAliasShadowed(shadowed, moduleNode.text, moduleNode)) continue;
+    addClient(match.captures.client);
+  }
+
+  for (const match of runCompiledPatterns(HTTPX_ASYNC_CLIENT_DIRECT_WITH_ALIAS_PATTERNS, tree)) {
+    const classNode = match.captures.client_class;
+    if (!classNode || !asyncClientAliases.has(classNode.text)) continue;
+    if (isAliasShadowed(shadowed, classNode.text, classNode)) continue;
     addClient(match.captures.client);
   }
 

gitnexus/src/core/group/extractors/http-route-extractor.ts

@@ -18,12 +18,14 @@ import { getPluginForFile, HTTP_SCAN_GLOB, type HttpDetection } from './http-pat
  *    the preferred path because the graph has richer symbol metadata
  *    (real uids, class/method structure, etc.).
  *
- * 2. **Source-scan fallback (Strategy B)** — parse files directly with
- *    the per-language plugin registry in `./http-patterns/`. Used when
- *    the graph has no routes/fetches for this repo (e.g. a repo that
- *    hasn't been indexed yet, or whose indexer doesn't know the
- *    framework). Each plugin owns its tree-sitter grammar and query
- *    sources — this orchestrator imports NO grammars or query strings.
+ * 2. **Source-scan supplement (Strategy B)** — parse files directly with
+ *    the per-language plugin registry in `./http-patterns/`. Used to
+ *    fill gaps when graph extraction only covers part of a polyglot repo
+ *    (e.g. Java graph routes plus Go source-scan routes). Graph entries
+ *    remain authoritative for duplicate contract IDs because they carry
+ *    richer symbol metadata. Each plugin owns its tree-sitter grammar
+ *    and query sources — this orchestrator imports NO grammars or query
+ *    strings.
  *
  * Adding a new language for Strategy B is a one-file edit in
  * `http-patterns/index.ts`: register a new `HttpLanguagePlugin` and
@@ -194,17 +196,19 @@ export class HttpRouteExtractor implements ContractExtractor {
 
     const graphProviders =
       dbExecutor != null ? await this.extractProvidersGraph(dbExecutor, getDetections) : [];
-    const providers =
-      graphProviders.length > 0
-        ? graphProviders
-        : this.extractProvidersSourceScan(await getScannedFiles(), getDetections);
+    // Source scan always runs to capture routes in languages/files not covered
+    // by graph edges; the glob and per-file parse results are cached above.
+    const providers = this.mergeGraphAndSourceContracts(
+      graphProviders,
+      this.extractProvidersSourceScan(await getScannedFiles(), getDetections),
+    );
 
     const graphConsumers =
       dbExecutor != null ? await this.extractConsumersGraph(dbExecutor, getDetections) : [];
-    const consumers =
-      graphConsumers.length > 0
-        ? graphConsumers
-        : this.extractConsumersSourceScan(await getScannedFiles(), getDetections);
+    const consumers = this.mergeGraphAndSourceContracts(
+      graphConsumers,
+      this.extractConsumersSourceScan(await getScannedFiles(), getDetections),
+    );
 
     return [...providers, ...consumers];
   }
@@ -473,4 +477,18 @@ export class HttpRouteExtractor implements ContractExtractor {
     }
     return out;
   }
+
+  private mergeGraphAndSourceContracts(
+    graphContracts: ExtractedContract[],
+    sourceContracts: ExtractedContract[],
+  ): ExtractedContract[] {
+    const seenContractIds = new Set(graphContracts.map((c) => c.contractId));
+    const out = [...graphContracts];
+    for (const contract of sourceContracts) {
+      if (seenContractIds.has(contract.contractId)) continue;
+      seenContractIds.add(contract.contractId);
+      out.push(contract);
+    }
+    return out;
+  }
 }

gitnexus/src/core/ingestion/filesystem-walker.ts

@@ -23,6 +23,21 @@ export interface FilePath {
 }
 
 const READ_CONCURRENCY = 32;
+const ANALYZE_PROGRESS_ACTIVE_ENV = 'GITNEXUS_ANALYZE_PROGRESS_ACTIVE';
+
+const warnLargeFileSkip = (message: string): void => {
+  if (process.env[ANALYZE_PROGRESS_ACTIVE_ENV] === '1') {
+    // analyze.ts routes console.warn through the progress bar logger while
+    // the bar is active. Emitting the operator-facing large-file notice there
+    // avoids raw pino NDJSON corrupting the one-line progress display in the
+    // heap-respawn child, whose stderr is intentionally piped for crash
+    // classification.
+    // eslint-disable-next-line no-console -- intentionally routed by analyze progress UI
+    console.warn(message);
+    return;
+  }
+  logger.warn(message);
+};
 
 /**
  * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
@@ -74,12 +89,35 @@ export const walkRepositoryPaths = async (
 
   if (skippedLarge > 0) {
     const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
+    const isOverrideUnset = !process.env.GITNEXUS_MAX_FILE_SIZE;
     const suffix = isDefault ? ', likely generated/vendored' : '';
-    logger.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
-    if (isVerboseIngestionEnabled()) {
-      for (const p of skippedLargePaths) {
-        logger.warn(`  - ${p}`);
-      }
+    warnLargeFileSkip(
+      `  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`,
+    );
+
+    // Always show at least the first few paths so users can diagnose why
+    // edges are missing from a specific file (issue #1659). The full list is
+    // gated behind GITNEXUS_VERBOSE=1 to avoid flooding output on repos with
+    // many generated/vendored blobs. Sort before slicing so the preview is
+    // stable across runs (fs.stat callbacks race within each batch).
+    skippedLargePaths.sort();
+    const SKIPPED_PREVIEW_CAP = 5;
+    const showAll = isVerboseIngestionEnabled() || skippedLargePaths.length <= SKIPPED_PREVIEW_CAP;
+    const preview = showAll ? skippedLargePaths : skippedLargePaths.slice(0, SKIPPED_PREVIEW_CAP);
+    for (const p of preview) {
+      warnLargeFileSkip(`  - ${p}`);
+    }
+    if (!showAll) {
+      const remaining = skippedLargePaths.length - SKIPPED_PREVIEW_CAP;
+      warnLargeFileSkip(`  ...and ${remaining} more (set GITNEXUS_VERBOSE=1 to list them all)`);
+    }
+    // Only hint about the env var when the user has not set it at all. An
+    // explicit GITNEXUS_MAX_FILE_SIZE=512 happens to resolve to the same
+    // bytes as the default but the operator clearly already knows the knob.
+    if (isDefault && isOverrideUnset) {
+      warnLargeFileSkip(
+        `  Set GITNEXUS_MAX_FILE_SIZE=<KB> to include files above the default cap.`,
+      );
     }
   }
 

gitnexus/src/core/ingestion/language-provider.ts

@@ -210,6 +210,37 @@ interface LanguageProviderConfig {
     ancestorNode: SyntaxNode,
   ) => { funcName: string; label: NodeLabel } | null;
 
+  // ── Template constraint extraction (SFINAE / `requires`) ────────────
+  /**
+   * Extract a per-language template-constraint payload for a templated
+   * function / method definition. Used by `parsing-processor` to
+   * disambiguate same-name same-arity overloads whose distinguishing
+   * signal is their template constraints rather than their parameter
+   * types — the canonical C++ SFINAE case (issue #1579):
+   *
+   *   template<class T, std::enable_if_t<is_integral_v<T>, int> = 0>
+   *   void process(T);   // overload A
+   *
+   *   template<class T, std::enable_if_t<is_floating_point_v<T>, int> = 0>
+   *   void process(T);   // overload B
+   *
+   * Both overloads' `parameterTypes` collapse to `['T']`, so without a
+   * constraint fingerprint in the graph node ID they merge into one
+   * Function node and the resolver only ever sees one candidate to
+   * narrow. The hook's return value is stamped onto the node's ID via
+   * `templateConstraintsIdTag()` AND stored on the node's
+   * `templateConstraints` property so `resolveDefGraphId` can look up
+   * the right overload by re-hashing the def's constraints at resolve
+   * time.
+   *
+   * Returns the opaque payload (any JSON-serializable shape — the
+   * producing adapter owns it; shared code MUST NOT inspect) or
+   * `undefined` when no constraints exist / the node isn't a templated
+   * function. Languages without SFINAE / concept semantics leave this
+   * undefined and the disambiguation is a pass-through.
+   */
+  readonly extractTemplateConstraints?: (definitionNode: SyntaxNode) => unknown;
+
   // ── Labels ────────────────────────────────────────────────────────
   /** Override the default node label for definition.function captures.
    *  Return null to skip (C/C++ duplicate), a different label to reclassify

gitnexus/src/core/ingestion/languages/c-cpp.ts

@@ -64,6 +64,7 @@ import {
   cppImportOwningScope,
   cppReceiverBinding,
 } from './cpp/index.js';
+import { extractCppTemplateConstraints } from './cpp/constraint-extractor.js';
 
 const C_BUILT_INS: ReadonlySet<string> = new Set([
   'printf',
@@ -463,6 +464,7 @@ export const cppProvider = defineLanguage({
   heritageExtractor: createHeritageExtractor(SupportedLanguages.CPlusPlus),
   labelOverride: cppLabelOverride,
   builtInNames: C_BUILT_INS,
+  extractTemplateConstraints: extractCppTemplateConstraintsForProvider,
 
   // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
   emitScopeCaptures: emitCppScopeCaptures,
@@ -474,3 +476,46 @@ export const cppProvider = defineLanguage({
   arityCompatibility: cppArityCompatibility,
   // mergeBindings + resolveImportTarget live on ScopeResolver (see cpp/scope-resolver.ts).
 });
+
+/**
+ * LanguageProvider hook: walk from a function definition node up to its
+ * enclosing `template_declaration` and extract the SFINAE / `requires`-
+ * clause constraint payload. Used by `parsing-processor` to fingerprint
+ * the graph node ID so two SFINAE overloads with identical
+ * `parameterTypes` get distinct nodes (issue #1579).
+ *
+ * Returns `undefined` for non-templated functions and for templated
+ * functions whose constraints the extractor can't model — both cases
+ * result in no constraint suffix on the node ID.
+ */
+function extractCppTemplateConstraintsForProvider(definitionNode: SyntaxNode): unknown {
+  // Walk up to the enclosing template_declaration. Bound the walk so we
+  // can't accidentally land on a far-ancestor template_declaration that
+  // wraps an unrelated function.
+  let cur: SyntaxNode | null = definitionNode.parent;
+  let hops = 8;
+  let templateDecl: SyntaxNode | null = null;
+  while (cur !== null && hops-- > 0) {
+    if (cur.type === 'template_declaration') {
+      templateDecl = cur;
+      break;
+    }
+    if (cur.type === 'translation_unit') break;
+    cur = cur.parent;
+  }
+  if (templateDecl === null) return undefined;
+
+  // Find the function_declarator inside the function definition so the
+  // extractor can map template params to function-argument indices.
+  let declarator: SyntaxNode | null = definitionNode.childForFieldName('declarator');
+  let walk = 8;
+  while (declarator !== null && walk-- > 0) {
+    if (declarator.type === 'function_declarator') break;
+    if (declarator.type === 'pointer_declarator' || declarator.type === 'reference_declarator') {
+      declarator = declarator.childForFieldName('declarator');
+      continue;
+    }
+    break;
+  }
+  return extractCppTemplateConstraints(templateDecl, declarator);
+}

gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts

@@ -1,9 +1,11 @@
 import type { SyntaxNode } from '../../utils/ast-helpers.js';
+import type { ParameterTypeClass } from 'gitnexus-shared';
 
 export interface CppArityInfo {
   parameterCount?: number;
   requiredParameterCount?: number;
   parameterTypes?: string[];
+  parameterTypeClasses?: ParameterTypeClass[];
 }
 
 /**
@@ -73,26 +75,35 @@ export function computeCppDeclarationArity(node: SyntaxNode): CppArityInfo {
   const totalNonVariadic = requiredCount + optionalCount;
 
   const types: string[] = [];
+  const typeClasses: ParameterTypeClass[] = [];
   for (const p of params) {
     if (p.type === 'variadic_parameter') {
       types.push('...');
+      typeClasses.push(unknownTypeClass('...'));
     } else if (p.type === 'variadic_parameter_declaration') {
       // Parameter pack: treated as variadic
       types.push('...');
+      typeClasses.push(unknownTypeClass('...'));
     } else {
       const typeNode = p.childForFieldName('type');
-      types.push(normalizeCppParamType(typeNode?.text ?? 'unknown'));
+      const rawType = typeNode?.text ?? 'unknown';
+      types.push(normalizeCppParamType(rawType));
+      typeClasses.push(
+        classifyCppParameterType(rawType, p.childForFieldName('declarator')?.text, p.text),
+      );
     }
   }
   // Append '...' for C-style variadic if not already in types
   if (hasEllipsis && !types.includes('...')) {
     types.push('...');
+    typeClasses.push(unknownTypeClass('...'));
   }
 
   return {
     parameterCount: isVariadic ? undefined : totalNonVariadic,
     requiredParameterCount: requiredCount,
     parameterTypes: types,
+    parameterTypeClasses: typeClasses,
   };
 }
 
@@ -120,8 +131,14 @@ export function computeCppCallArity(node: SyntaxNode): number {
  * so that `narrowOverloadCandidates` can match against literal-inferred
  * argument types (e.g. `inferCppLiteralType` returns `'string'` for
  * string literals, not `'std::string'`).
+ *
+ * This intentionally remains coarse and graph-ID-stable: cv-qualifiers,
+ * reference markers, and pointer markers are stripped here. C++ callers
+ * that need those distinctions should read `parameterTypeClasses`, which
+ * is an additive sidecar and does not participate in overload node ID
+ * hashing.
  */
-function normalizeCppParamType(raw: string): string {
+export function normalizeCppParamType(raw: string): string {
   let t = raw.trim();
   // Strip const, volatile, etc.
   t = t.replace(/\b(const|volatile|restrict|mutable|constexpr)\b/g, '').trim();
@@ -158,6 +175,52 @@ function normalizeCppParamType(raw: string): string {
   return STD_MAP[t] ?? t;
 }
 
+export function classifyCppParameterType(
+  rawType: string,
+  declaratorText?: string,
+  fullParameterText?: string,
+): ParameterTypeClass {
+  const source = fullParameterText ?? `${rawType} ${declaratorText ?? ''}`.trim();
+  if (rawType === 'unknown') return unknownTypeClass('unknown');
+
+  const hasConst = /\bconst\b/.test(source);
+  const hasVolatile = /\bvolatile\b/.test(source);
+  const cv: ParameterTypeClass['cv'] =
+    hasConst && hasVolatile
+      ? 'const volatile'
+      : hasConst
+        ? 'const'
+        : hasVolatile
+          ? 'volatile'
+          : 'none';
+
+  const pointerDepth = (source.match(/\*/g) ?? []).length;
+  const indirection: ParameterTypeClass['indirection'] =
+    pointerDepth > 0
+      ? 'pointer'
+      : /&&/.test(source)
+        ? 'rvalue-ref'
+        : /&/.test(source)
+          ? 'lvalue-ref'
+          : 'value';
+
+  return {
+    base: normalizeCppParamType(rawType),
+    cv,
+    indirection,
+    pointerDepth,
+  };
+}
+
+function unknownTypeClass(base: string): ParameterTypeClass {
+  return {
+    base,
+    cv: 'unknown',
+    indirection: 'unknown',
+    pointerDepth: 0,
+  };
+}
+
 function findFuncDeclarator(node: SyntaxNode): SyntaxNode | null {
   let decl = node.childForFieldName('declarator');
   if (decl === null) {

gitnexus/src/core/ingestion/languages/cpp/arity.ts

@@ -8,7 +8,10 @@ import type { Callsite, SymbolDefinition } from 'gitnexus-shared';
  *   - Default parameters (requiredParameterCount < parameterCount)
  *   - Variadic functions (C-style `...`)
  *   - Parameter packs (V1: treated as variadic)
- *   - Templates (V1: generic-ignored, arity check on non-template params)
+ *   - Templates: arity check on non-template params; SFINAE / `requires`
+ *     constraints are filtered separately via `constraintCompatibility`
+ *     (see `constraint-filter.ts` and issue #1579). Type-argument generic
+ *     substitution (`List<T>` ≡ `List<U>`) remains out of V1 scope.
  *
  * Verdict:
  *   - 'compatible':    callsite.arity fits within [required, total] range

gitnexus/src/core/ingestion/languages/cpp/captures.ts

@@ -1,4 +1,4 @@
-import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import type { Capture, CaptureMatch, ParameterTypeClass } from 'gitnexus-shared';
 import {
   findNodeAtRange,
   nodeToCapture,
@@ -9,11 +9,16 @@ import { getCppParser, getCppScopeQuery } from './query.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
 import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 import { splitCppInclude, splitCppUsingDecl } from './import-decomposer.js';
-import { computeCppDeclarationArity, computeCppCallArity } from './arity-metadata.js';
+import {
+  classifyCppParameterType,
+  computeCppDeclarationArity,
+  computeCppCallArity,
+} from './arity-metadata.js';
 import { markCppAnonymousNamespaceRange, markFileLocal } from './file-local-linkage.js';
 import { markCppDependentBase } from './two-phase-lookup.js';
 import { markCppAdlSiteArgs, markCppAdlSiteNoAdl, type CppAdlArgInfo } from './adl.js';
 import { markCppInlineNamespaceRange } from './inline-namespaces.js';
+import { extractCppTemplateConstraints } from './constraint-extractor.js';
 
 export function emitCppScopeCaptures(
   sourceText: string,
@@ -114,6 +119,13 @@ export function emitCppScopeCaptures(
             JSON.stringify(arity.parameterTypes),
           );
         }
+        if (arity.parameterTypeClasses !== undefined) {
+          grouped['@declaration.parameter-type-classes'] = syntheticCapture(
+            '@declaration.parameter-type-classes',
+            fnNode,
+            JSON.stringify(arity.parameterTypeClasses),
+          );
+        }
 
         // Detect static storage class (file-local linkage)
         if (hasStaticStorageClass(fnNode)) {
@@ -130,6 +142,24 @@ export function emitCppScopeCaptures(
             markFileLocal(filePath, nameText);
           }
         }
+
+        // SFINAE / `requires`-clause aware constraints for overload
+        // narrowing (issue #1579). Walk from the enclosing
+        // `template_declaration` — not the inner `function_definition` —
+        // so inline method templates (`template<...> class C { template<...> void f(); }`)
+        // pick up the correct outer constraint scope.
+        const templateDecl = findEnclosingTemplateDeclaration(fnNode);
+        if (templateDecl !== null) {
+          const funcDeclarator = findFunctionDeclarator(fnNode);
+          const constraints = extractCppTemplateConstraints(templateDecl, funcDeclarator);
+          if (constraints !== undefined) {
+            grouped['@declaration.template-constraints'] = syntheticCapture(
+              '@declaration.template-constraints',
+              fnNode,
+              JSON.stringify(constraints),
+            );
+          }
+        }
       }
     }
 
@@ -191,6 +221,14 @@ export function emitCppScopeCaptures(
             JSON.stringify(argTypes),
           );
         }
+        const argTypeClasses = inferCppCallArgTypeClasses(cNode);
+        if (argTypeClasses !== undefined && argTypeClasses.length > 0) {
+          grouped['@reference.parameter-type-classes'] = syntheticCapture(
+            '@reference.parameter-type-classes',
+            cNode,
+            JSON.stringify(argTypeClasses),
+          );
+        }
       }
     }
 
@@ -552,6 +590,52 @@ function extractBaseLookupName(baseNode: SyntaxNode): string {
   return '';
 }
 
+/**
+ * Walk parent chain from a function_definition / declaration / field_declaration
+ * to find the enclosing `template_declaration`. Returns null when the function
+ * isn't templated. The walk only ascends through wrapper nodes the C++
+ * grammar inserts between `template_declaration` and the function — direct
+ * parent in the common case, two hops for member templates whose outer
+ * class is also templated (we return the INNERMOST template_declaration,
+ * which carries this function's own template parameters).
+ */
+function findEnclosingTemplateDeclaration(fnNode: SyntaxNode): SyntaxNode | null {
+  let cur: SyntaxNode | null = fnNode.parent;
+  // Cap the walk — `template_declaration` is typically the immediate parent
+  // or one wrapper away. Anything deeper is an inline-method-in-template
+  // shape and we still want the innermost templates_declaration whose body
+  // wraps `fnNode`.
+  let hops = 8;
+  while (cur !== null && hops-- > 0) {
+    if (cur.type === 'template_declaration') return cur;
+    // Don't ascend past structural boundaries that should reset template scope.
+    if (cur.type === 'translation_unit') return null;
+    cur = cur.parent;
+  }
+  return null;
+}
+
+/**
+ * Locate the `function_declarator` AST node within a function definition
+ * or declaration. Unwraps pointer/reference declarator wrappers. Returns
+ * null when no function_declarator is found (e.g. variable declaration
+ * mis-classified upstream).
+ */
+function findFunctionDeclarator(fnNode: SyntaxNode): SyntaxNode | null {
+  const direct = fnNode.childForFieldName('declarator');
+  let cur: SyntaxNode | null = direct;
+  let hops = 8;
+  while (cur !== null && hops-- > 0) {
+    if (cur.type === 'function_declarator') return cur;
+    if (cur.type === 'pointer_declarator' || cur.type === 'reference_declarator') {
+      cur = cur.childForFieldName('declarator');
+      continue;
+    }
+    break;
+  }
+  return findFirstDescendantOfType(fnNode, 'function_declarator');
+}
+
 /** Find the first direct child matching one of the given types. */
 function findChildOfType(node: SyntaxNode, types: readonly string[]): SyntaxNode | null {
   for (let i = 0; i < node.childCount; i++) {
@@ -611,6 +695,35 @@ function inferCppCallArgTypes(node: SyntaxNode): string[] | undefined {
   return types.length > 0 ? types : undefined;
 }
 
+function inferCppCallArgTypeClasses(node: SyntaxNode): ParameterTypeClass[] | undefined {
+  const argList = node.childForFieldName('arguments');
+  if (argList === null) return undefined;
+
+  const classes: ParameterTypeClass[] = [];
+  for (let i = 0; i < argList.childCount; i++) {
+    const child = argList.child(i);
+    if (child === null) continue;
+    if (child.type === ',' || child.type === '(' || child.type === ')') continue;
+    const litType = inferCppLiteralType(child);
+    if (litType !== '') {
+      classes.push(valueTypeClass(litType));
+    } else if (child.type === 'identifier') {
+      classes.push(lookupDeclaredTypeClassForIdentifier(child));
+    } else {
+      classes.push(unknownTypeClass('unknown'));
+    }
+  }
+  return classes.length > 0 ? classes : undefined;
+}
+
+function valueTypeClass(base: string): ParameterTypeClass {
+  return { base, cv: 'none', indirection: 'value', pointerDepth: 0 };
+}
+
+function unknownTypeClass(base: string): ParameterTypeClass {
+  return { base, cv: 'unknown', indirection: 'unknown', pointerDepth: 0 };
+}
+
 /**
  * Infer the canonical type name of a C++ literal AST node.
  * Returns empty string for non-literal / unknown nodes.
@@ -655,6 +768,15 @@ function inferCppLiteralType(node: SyntaxNode): string {
  *   - `int n = ...` → 'int'
  *   - `const int n = ...` → 'int'
  * Returns empty string if no declaration found or type is auto/placeholder.
+ *
+ * Limitation: only `declaration` siblings inside the enclosing
+ * `compound_statement` are inspected. Function parameters live in the
+ * `function_declarator`'s `parameter_list` and are NOT resolved here, so
+ *   `void run(int n) { process(n); }`
+ * infers `''` for `n` and the constraint filter falls through to
+ * `'unknown'` → ambiguity suppression → 0 CALLS edges. This is a
+ * "degrade not lie" gap (no wrong edges, just missing ones); extending
+ * the scan to `parameter_list` is tracked under #1579 as a follow-up.
  */
 function lookupDeclaredTypeForIdentifier(identNode: SyntaxNode): string {
   const varName = identNode.text;
@@ -669,6 +791,9 @@ function lookupDeclaredTypeForIdentifier(identNode: SyntaxNode): string {
   }
   if (scope === null) return '';
 
+  const paramType = lookupFunctionParameterType(scope, varName);
+  if (paramType !== '') return paramType;
+
   // Scan declarations in the scope for a matching variable name
   for (let i = 0; i < scope.childCount; i++) {
     const stmt = scope.child(i);
@@ -682,18 +807,118 @@ function lookupDeclaredTypeForIdentifier(identNode: SyntaxNode): string {
     // Check init_declarator children for the variable name
     const declarator = stmt.childForFieldName('declarator');
     if (declarator === null) continue;
-    if (declarator.type === 'init_declarator') {
-      const nameChild = declarator.childForFieldName('declarator');
-      if (nameChild !== null && nameChild.text === varName) {
-        return normalizeCppTypeText(typeNode.text);
-      }
-    } else if (declarator.text === varName) {
+    const nameChild = declaredNameNode(declarator);
+    if (nameChild !== null && extractDeclaratorLeafName(nameChild) === varName) {
       return normalizeCppTypeText(typeNode.text);
     }
   }
   return '';
 }
 
+function lookupDeclaredTypeClassForIdentifier(identNode: SyntaxNode): ParameterTypeClass {
+  const varName = identNode.text;
+  let scope: SyntaxNode | null = identNode.parent;
+  while (
+    scope !== null &&
+    scope.type !== 'compound_statement' &&
+    scope.type !== 'translation_unit'
+  ) {
+    scope = scope.parent;
+  }
+  if (scope === null) return unknownTypeClass('unknown');
+
+  const paramTypeClass = lookupFunctionParameterTypeClass(scope, varName, identNode);
+  if (paramTypeClass !== undefined) return paramTypeClass;
+
+  for (let i = 0; i < scope.childCount; i++) {
+    const stmt = scope.child(i);
+    if (stmt === null || stmt.type !== 'declaration') continue;
+
+    const typeNode = stmt.childForFieldName('type');
+    if (typeNode === null) continue;
+    if (typeNode.type === 'placeholder_type_specifier') continue;
+
+    const declarator = stmt.childForFieldName('declarator');
+    if (declarator === null) continue;
+    const nameChild = declaredNameNode(declarator);
+    if (nameChild === null || extractDeclaratorLeafName(nameChild) !== varName) continue;
+
+    const typeClass = classifyCppParameterType(
+      typeNode.text,
+      nameChild.text,
+      stmt.text.replace(/;\s*$/, ''),
+    );
+    if (isKnownEnumName(identNode, typeClass.base)) {
+      return { ...typeClass, base: `enum:${typeClass.base}` };
+    }
+    return typeClass;
+  }
+  return unknownTypeClass('unknown');
+}
+
+function lookupFunctionParameterType(scope: SyntaxNode, varName: string): string {
+  const param = findEnclosingFunctionParameter(scope, varName);
+  if (param === null) return '';
+  const typeNode = param.childForFieldName('type');
+  if (typeNode === null) return '';
+  return normalizeCppTypeText(typeNode.text);
+}
+
+function lookupFunctionParameterTypeClass(
+  scope: SyntaxNode,
+  varName: string,
+  identNode: SyntaxNode,
+): ParameterTypeClass | undefined {
+  const param = findEnclosingFunctionParameter(scope, varName);
+  if (param === null) return undefined;
+  const typeNode = param.childForFieldName('type');
+  if (typeNode === null) return undefined;
+  const declarator = param.childForFieldName('declarator');
+  if (declarator === null) return undefined;
+  const typeClass = classifyCppParameterType(typeNode.text, declarator.text, param.text);
+  if (isKnownEnumName(identNode, typeClass.base)) {
+    return { ...typeClass, base: `enum:${typeClass.base}` };
+  }
+  return typeClass;
+}
+
+function findEnclosingFunctionParameter(scope: SyntaxNode, varName: string): SyntaxNode | null {
+  let node: SyntaxNode | null = scope.parent;
+  while (node !== null) {
+    if (node.type === 'function_definition' || node.type === 'function_declarator') {
+      const fnDecl =
+        node.type === 'function_declarator'
+          ? node
+          : findFirstDescendantOfType(node, 'function_declarator');
+      const params = fnDecl?.childForFieldName('parameters') ?? null;
+      if (params !== null) {
+        for (let i = 0; i < params.namedChildCount; i++) {
+          const param = params.namedChild(i);
+          if (param === null || param.type !== 'parameter_declaration') continue;
+          const declarator = param.childForFieldName('declarator');
+          if (declarator !== null && extractDeclaratorLeafName(declarator) === varName) {
+            return param;
+          }
+        }
+      }
+      return null;
+    }
+    node = node.parent;
+  }
+  return null;
+}
+
+function declaredNameNode(declarator: SyntaxNode): SyntaxNode | null {
+  if (declarator.type !== 'init_declarator') return declarator;
+  for (let i = 0; i < declarator.namedChildCount; i++) {
+    const child = declarator.namedChild(i);
+    if (child === null) continue;
+    if (child.type === 'identifier') return child;
+    if (child.type.endsWith('_declarator')) return child;
+  }
+  return declarator.childForFieldName('declarator');
+}
+
 /** Normalize a type-specifier text for argument type matching.
  *  Strips qualifiers (const, volatile), namespace prefixes (std::),
  *  and pointer/reference markers. */
@@ -705,6 +930,25 @@ function normalizeCppTypeText(text: string): string {
   return t;
 }
 
+function isKnownEnumName(node: SyntaxNode, typeName: string): boolean {
+  if (typeName === '' || typeName === 'unknown') return false;
+  let root: SyntaxNode = node;
+  while (root.parent !== null) root = root.parent;
+  const stack: SyntaxNode[] = [root];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    if (cur.type === 'enum_specifier') {
+      const name = cur.childForFieldName('name');
+      if (name?.text === typeName) return true;
+    }
+    for (let i = 0; i < cur.childCount; i++) {
+      const child = cur.child(i);
+      if (child !== null) stack.push(child);
+    }
+  }
+  return false;
+}
+
 /**
  * Detect whether a `namespace_definition` AST node is inline.
  * Tree-sitter-cpp exposes the `inline` keyword as an anonymous child
@@ -1166,7 +1410,9 @@ function extractDeclaratorLeafName(node: SyntaxNode): string | null {
     const next =
       cur.childForFieldName('declarator') ??
       // parenthesized_declarator: single named child
-      (cur.type === 'parenthesized_declarator' ? cur.namedChild(0) : null);
+      (cur.type === 'parenthesized_declarator' || cur.type.endsWith('_declarator')
+        ? cur.namedChild(0)
+        : null);
     if (next === null) return null;
     cur = next;
   }

gitnexus/src/core/ingestion/languages/cpp/constraint-extractor.ts

@@ -0,0 +1,335 @@
+/**
+ * Extract C++ template constraint expressions for SFINAE-aware overload
+ * narrowing (issue #1579). Recognizes 3 AST shapes:
+ *
+ *   F1 — unqualified non-type template param default:
+ *        `template<class T, enable_if_t<P, int> = 0> void f(T);`
+ *   F2 — `std::`-qualified variant (canonical ticket form):
+ *        `template<class T, std::enable_if_t<P, int> = 0> void f(T);`
+ *   F4 — C++20 leading requires-clause:
+ *        `template<class T> requires P void f(T);`
+ *
+ * Deferred (return `{kind:'unknown'}`):
+ *   F3 — void-default `typename = enable_if_t<P>` (cppref labels this
+ *        `/* WRONG *\/` because adjacent overloads collapse to redeclarations)
+ *   F5 — trailing requires (`void f(T) requires P;`)
+ *   `requires_expression` blocks (`requires { typename T::U; }`)
+ *   `decltype(...)`, fold-expressions, user-defined `_v` aliases.
+ *
+ * The output payload is opaque to shared code — only
+ * `constraint-filter.ts` consumes it. See ISO `[temp.constr.normal]` /
+ * `<https://en.cppreference.com/w/cpp/language/constraints>` for the
+ * normalization the Kleene 3-valued evaluator implements.
+ */
+
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+
+export type ConstraintExpr =
+  | { readonly kind: 'atomic'; readonly name: string; readonly args: readonly string[] }
+  | { readonly kind: 'and'; readonly children: readonly ConstraintExpr[] }
+  | { readonly kind: 'or'; readonly children: readonly ConstraintExpr[] }
+  | { readonly kind: 'not'; readonly child: ConstraintExpr }
+  | { readonly kind: 'unknown' };
+
+export interface CppConstraintPayload {
+  /** Ordered template parameter names (type-params only — non-type defaults
+   *  carrying enable_if predicates are folded into `expr`). */
+  readonly templateParams: readonly string[];
+  /**
+   * Mapping from each template parameter name to the call-site argument
+   * index where its deduced type lives. Computed by scanning the function's
+   * parameter list for the first parameter whose type is the bare template
+   * parameter name (or template-typed by it). Missing entries → 'unknown'
+   * verdict at evaluation time.
+   */
+  readonly paramArgIndex: { readonly [paramName: string]: number };
+  /** Root constraint expression. When multiple constraints (multiple
+   *  enable_if defaults, requires clause, etc.) are present they are
+   *  implicitly conjoined under a top-level `and` node. */
+  readonly expr: ConstraintExpr;
+}
+
+/**
+ * Walk a `template_declaration` AST node and extract its constraint
+ * payload. Caller is responsible for passing the OUTER `template_declaration`
+ * — for class-member template functions, that means the enclosing
+ * template_declaration of the class OR of the method, whichever
+ * directly precedes the function definition.
+ *
+ * Returns `undefined` when the template_declaration declares no
+ * constraints worth tracking (no enable_if default, no requires clause).
+ * Returns a payload whose `expr.kind === 'unknown'` when constraints are
+ * present but the extractor cannot model them — monotonicity guarantees
+ * the filter keeps the candidate in that case.
+ */
+export function extractCppTemplateConstraints(
+  templateDecl: SyntaxNode,
+  funcDeclarator: SyntaxNode | null,
+): CppConstraintPayload | undefined {
+  const paramList = childOfType(templateDecl, 'template_parameter_list');
+  if (paramList === null) return undefined;
+
+  const templateParams: string[] = [];
+  const exprs: ConstraintExpr[] = [];
+
+  for (let i = 0; i < paramList.namedChildCount; i++) {
+    const param = paramList.namedChild(i);
+    if (param === null) continue;
+    if (
+      param.type === 'type_parameter_declaration' ||
+      param.type === 'optional_type_parameter_declaration' ||
+      param.type === 'variadic_type_parameter_declaration'
+    ) {
+      const id = firstDescendantOfType(param, 'type_identifier');
+      if (id !== null) templateParams.push(id.text);
+      continue;
+    }
+    // Non-type parameter — F1 / F2 default-value carries the enable_if
+    // predicate. Shape: `optional_parameter_declaration` with field
+    // `default_value`, whose value is a `template_type` named
+    // `enable_if_t` (F1) or a qualified version (F2).
+    if (param.type === 'optional_parameter_declaration') {
+      const defaultVal = param.childForFieldName('default_value');
+      const typeNode = param.childForFieldName('type');
+      const candidate = extractEnableIfPredicate(typeNode);
+      if (candidate !== undefined) {
+        exprs.push(candidate);
+      } else if (defaultVal !== null) {
+        // Default-value-as-predicate not yet supported. Bail conservatively.
+        exprs.push({ kind: 'unknown' });
+      }
+    }
+  }
+
+  // F4 — C++20 leading `requires` clause. Tree-sitter-cpp exposes it as a
+  // `requires_clause` child of `template_declaration` (sibling of the
+  // template_parameter_list).
+  const requiresClause = childOfType(templateDecl, 'requires_clause');
+  if (requiresClause !== null) {
+    const parsed = parseRequiresClause(requiresClause);
+    if (parsed !== undefined) exprs.push(parsed);
+  }
+
+  if (templateParams.length === 0 && exprs.length === 0) return undefined;
+
+  const paramArgIndex = buildParamArgIndex(templateParams, funcDeclarator);
+  const expr: ConstraintExpr =
+    exprs.length === 0
+      ? { kind: 'unknown' }
+      : exprs.length === 1
+        ? exprs[0]
+        : { kind: 'and', children: exprs };
+
+  return { templateParams, paramArgIndex, expr };
+}
+
+/**
+ * Inspect a non-type template parameter's declared type to see whether
+ * it's `enable_if_t<P, T>` (F1) or `std::enable_if_t<P, T>` (F2). When
+ * matched, extract the predicate `P` and return it as a `ConstraintExpr`.
+ *
+ * Returns undefined when the parameter's type is not enable_if (so the
+ * caller can decide whether to bail or ignore).
+ */
+function extractEnableIfPredicate(typeNode: SyntaxNode | null): ConstraintExpr | undefined {
+  if (typeNode === null) return undefined;
+  // Unwrap a type_descriptor wrapper (when present).
+  let t: SyntaxNode | null = typeNode;
+  if (t.type === 'type_descriptor') {
+    t = t.childForFieldName('type') ?? firstDescendantOfType(t, 'template_type');
+  }
+  // F2 shape: tree-sitter-cpp models `std::enable_if_t<...>` as
+  // `qualified_identifier` whose `name` field is the `template_type`.
+  // F1 shape (unqualified `enable_if_t<...>`) is `template_type` directly.
+  if (t !== null && t.type === 'qualified_identifier') {
+    const inner = t.childForFieldName('name') ?? firstDescendantOfType(t, 'template_type');
+    if (inner !== null && inner.type === 'template_type') {
+      t = inner;
+    }
+  }
+  if (t === null || t.type !== 'template_type') return undefined;
+
+  const nameNode = t.childForFieldName('name');
+  if (nameNode === null) return undefined;
+  const tail = stripQualifiedPrefix(nameNode.text);
+  if (tail !== 'enable_if_t' && tail !== 'enable_if') return undefined;
+
+  // Predicate is the first template argument of enable_if_t.
+  const argList = t.childForFieldName('arguments') ?? childOfType(t, 'template_argument_list');
+  if (argList === null) return { kind: 'unknown' };
+  for (let i = 0; i < argList.namedChildCount; i++) {
+    const arg = argList.namedChild(i);
+    if (arg === null) continue;
+    if (arg.type !== 'type_descriptor') continue;
+    const inner = arg.childForFieldName('type') ?? arg.namedChild(0);
+    if (inner === null) continue;
+    return parseAtomicOrBoolean(inner);
+  }
+  return { kind: 'unknown' };
+}
+
+/** Parse a requires-clause body. The body is a binary or unary expression
+ *  over atomic predicates (variable templates like `is_integral_v<T>`). */
+function parseRequiresClause(requiresClause: SyntaxNode): ConstraintExpr | undefined {
+  // tree-sitter-cpp exposes the expression as a named child or via a
+  // `constraint` field. Probe both.
+  let expr: SyntaxNode | null = requiresClause.childForFieldName('constraint');
+  if (expr === null) {
+    for (let i = 0; i < requiresClause.namedChildCount; i++) {
+      const c = requiresClause.namedChild(i);
+      if (c === null) continue;
+      // Skip the `requires` keyword token.
+      if (c.type === 'requires') continue;
+      expr = c;
+      break;
+    }
+  }
+  if (expr === null) return undefined;
+  return parseAtomicOrBoolean(expr);
+}
+
+/**
+ * Recursively parse a constraint sub-expression. Recognizes:
+ *   - `template_type` / `template_function` named `<predicate>_v` → atomic
+ *   - binary_expression with `&&` / `||` → conjunction / disjunction
+ *   - unary_expression with `!` → negation
+ *   - parenthesized_expression → unwrap
+ *   - anything else → `{kind:'unknown'}` (monotonicity-safe)
+ *
+ * `requires_expression` blocks intentionally fall through to 'unknown'
+ * — they need substitution semantics we don't model in V1.
+ */
+function parseAtomicOrBoolean(node: SyntaxNode): ConstraintExpr {
+  // Unwrap parentheses.
+  if (node.type === 'parenthesized_expression') {
+    const inner = node.namedChild(0);
+    return inner === null ? { kind: 'unknown' } : parseAtomicOrBoolean(inner);
+  }
+  // Boolean composition.
+  if (node.type === 'binary_expression') {
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    const opNode = node.childForFieldName('operator');
+    if (left !== null && right !== null && opNode !== null) {
+      const op = opNode.text;
+      const l = parseAtomicOrBoolean(left);
+      const r = parseAtomicOrBoolean(right);
+      if (op === '&&') return { kind: 'and', children: [l, r] };
+      if (op === '||') return { kind: 'or', children: [l, r] };
+    }
+    return { kind: 'unknown' };
+  }
+  if (node.type === 'unary_expression') {
+    const opNode = node.childForFieldName('operator') ?? node.namedChild(0);
+    const arg = node.childForFieldName('argument') ?? node.namedChild(1) ?? node.namedChild(0);
+    if (opNode !== null && opNode.text === '!' && arg !== null && arg !== opNode) {
+      return { kind: 'not', child: parseAtomicOrBoolean(arg) };
+    }
+    return { kind: 'unknown' };
+  }
+  // Atomic predicate — `template_type` is the typical shape for variable
+  // templates like `is_integral_v<T>`. Some grammar variants surface it as
+  // `template_function` or via a `qualified_identifier` wrapper.
+  if (node.type === 'template_type' || node.type === 'template_function') {
+    return parseAtomicTemplate(node);
+  }
+  if (node.type === 'qualified_identifier') {
+    // `std::is_integral_v<T>` shape (without template_type wrapping).
+    const inner = node.childForFieldName('name');
+    if (inner !== null && (inner.type === 'template_type' || inner.type === 'template_function')) {
+      return parseAtomicTemplate(inner);
+    }
+    return { kind: 'unknown' };
+  }
+  // `requires { typename T::U; }` blocks and decltype: out of V1 scope.
+  return { kind: 'unknown' };
+}
+
+function parseAtomicTemplate(t: SyntaxNode): ConstraintExpr {
+  const nameNode = t.childForFieldName('name');
+  if (nameNode === null) return { kind: 'unknown' };
+  const name = stripQualifiedPrefix(nameNode.text);
+  const argList = t.childForFieldName('arguments') ?? childOfType(t, 'template_argument_list');
+  const args: string[] = [];
+  if (argList !== null) {
+    for (let i = 0; i < argList.namedChildCount; i++) {
+      const arg = argList.namedChild(i);
+      if (arg === null) continue;
+      if (arg.type !== 'type_descriptor') continue;
+      const inner = arg.childForFieldName('type') ?? arg.namedChild(0);
+      if (inner === null) continue;
+      // For Tier-A predicates the args are bare template-parameter names
+      // (`T`, `U`). Anything more elaborate is bailed via 'unknown' at the
+      // top level if needed; here we just record the textual identifier.
+      const id =
+        inner.type === 'type_identifier' ? inner : firstDescendantOfType(inner, 'type_identifier');
+      args.push(id !== null ? id.text : inner.text);
+    }
+  }
+  return { kind: 'atomic', name, args };
+}
+
+/** Build a `paramName → call-site argument index` map by scanning the
+ *  function's parameter list for parameters typed by each template param. */
+function buildParamArgIndex(
+  templateParams: readonly string[],
+  funcDeclarator: SyntaxNode | null,
+): { [paramName: string]: number } {
+  const out: { [paramName: string]: number } = {};
+  if (funcDeclarator === null || templateParams.length === 0) return out;
+  const paramList = funcDeclarator.childForFieldName('parameters');
+  if (paramList === null) return out;
+
+  let argIdx = 0;
+  for (let i = 0; i < paramList.childCount; i++) {
+    const p = paramList.child(i);
+    if (p === null) continue;
+    if (
+      p.type !== 'parameter_declaration' &&
+      p.type !== 'optional_parameter_declaration' &&
+      p.type !== 'variadic_parameter_declaration'
+    ) {
+      continue;
+    }
+    const typeNode = p.childForFieldName('type');
+    if (typeNode !== null) {
+      const tname = bareTypeIdentifier(typeNode);
+      if (tname !== null && templateParams.includes(tname) && !(tname in out)) {
+        out[tname] = argIdx;
+      }
+    }
+    argIdx++;
+  }
+  return out;
+}
+
+function bareTypeIdentifier(typeNode: SyntaxNode): string | null {
+  if (typeNode.type === 'type_identifier') return typeNode.text;
+  // Allow `T const`, `T&`, `T*` shapes — the inner type_identifier still wins.
+  const id = firstDescendantOfType(typeNode, 'type_identifier');
+  return id !== null ? id.text : null;
+}
+
+function stripQualifiedPrefix(text: string): string {
+  const idx = text.lastIndexOf('::');
+  return idx >= 0 ? text.slice(idx + 2) : text;
+}
+
+function childOfType(node: SyntaxNode, type: string): SyntaxNode | null {
+  for (let i = 0; i < node.childCount; i++) {
+    const c = node.child(i);
+    if (c !== null && c.type === type) return c;
+  }
+  return null;
+}
+
+function firstDescendantOfType(node: SyntaxNode, type: string): SyntaxNode | null {
+  if (node.type === type) return node;
+  for (let i = 0; i < node.childCount; i++) {
+    const c = node.child(i);
+    if (c === null) continue;
+    const hit = firstDescendantOfType(c, type);
+    if (hit !== null) return hit;
+  }
+  return null;
+}

gitnexus/src/core/ingestion/languages/cpp/constraint-filter.ts

@@ -0,0 +1,261 @@
+/**
+ * Kleene 3-valued evaluator + curated 4-predicate registry +
+ * `cppConstraintCompatibility` hook export for SFINAE / `requires`-clause
+ * filtering (issue #1579).
+ *
+ * Semantics:
+ *   - `'incompatible'` → predicate provably fails for these argumentTypes
+ *     (ISO `[temp.constr.atomic]` "not satisfied")
+ *   - `'compatible'`   → predicate provably holds
+ *   - `'unknown'`      → cannot decide (missing arg-type info, predicate
+ *     not in registry, AST shape bailed during extraction). The shared
+ *     filter keeps the candidate on `'unknown'` — monotonicity guarantee.
+ *
+ * Kleene rules (extension of ISO's 2-valued short-circuit conjunction in
+ * `<https://en.cppreference.com/w/cpp/language/constraints>`):
+ *   AND: incompatible if any child incompatible; compatible iff all
+ *        children compatible; otherwise unknown.
+ *   OR:  compatible if any child compatible; incompatible iff all
+ *        children incompatible; otherwise unknown.
+ *   NOT: flip compatible↔incompatible; pass through unknown.
+ */
+
+import type {
+  ArityVerdict,
+  Callsite,
+  ConstraintContext,
+  ParameterTypeClass,
+  SymbolDefinition,
+} from 'gitnexus-shared';
+import { classifyType, type TypeClass } from './type-classifier.js';
+import type { ConstraintExpr, CppConstraintPayload } from './constraint-extractor.js';
+
+interface ConstraintArgClass {
+  readonly typeClass: TypeClass;
+  readonly shape?: ParameterTypeClass;
+}
+
+type AtomicEvaluator = (args: readonly ConstraintArgClass[]) => ArityVerdict;
+
+/**
+ * Curated Tier-A predicate registry. Predicates that depend on pointer,
+ * reference, or cv shape consult `ConstraintContext.argumentTypeClasses`.
+ * Missing or unsupported shape returns 'unknown' to preserve monotonicity.
+ */
+// ISO `<type_traits>` treats `bool`, `char`, and the signed/unsigned char
+// variants as integral types (§21.3.4 Table 48), so `is_integral_v<bool>`
+// and `is_integral_v<char>` must both yield `true`. We keep the `TypeClass`
+// enum precise (separate `'bool'` / `'char'` buckets) so that
+// `is_same_v<bool, int>` still resolves to `'incompatible'`; the integral-
+// family widening lives here in the predicate evaluators instead.
+function isIntegralClass(c: TypeClass | undefined): boolean {
+  return c === 'integral' || c === 'bool' || c === 'char';
+}
+
+const REGISTRY = new Map<string, AtomicEvaluator>([
+  [
+    'is_void_v',
+    (args) => unaryVerdict(args, (arg) => isPlainValue(arg) && arg.typeClass === 'void'),
+  ],
+  [
+    'is_integral_v',
+    (args) => unaryVerdict(args, (arg) => isPlainValue(arg) && isIntegralClass(arg.typeClass)),
+  ],
+  [
+    'is_floating_point_v',
+    (args) => unaryVerdict(args, (arg) => isPlainValue(arg) && arg.typeClass === 'floating'),
+  ],
+  [
+    'is_arithmetic_v',
+    (args) =>
+      unaryVerdict(
+        args,
+        (arg) =>
+          isPlainValue(arg) && (isIntegralClass(arg.typeClass) || arg.typeClass === 'floating'),
+      ),
+  ],
+  [
+    'is_enum_v',
+    (args) => unaryVerdict(args, (arg) => isPlainValue(arg) && arg.typeClass === 'enum'),
+  ],
+  [
+    'is_class_v',
+    (args) => unaryVerdict(args, (arg) => isPlainValue(arg) && arg.typeClass === 'class'),
+  ],
+  [
+    'is_pointer_v',
+    (args) =>
+      unaryShapeVerdict(args, (shape) => shape.indirection === 'pointer' && shape.pointerDepth > 0),
+  ],
+  [
+    'is_reference_v',
+    (args) =>
+      unaryShapeVerdict(
+        args,
+        (shape) => shape.indirection === 'lvalue-ref' || shape.indirection === 'rvalue-ref',
+      ),
+  ],
+  [
+    'is_const_v',
+    (args) =>
+      unaryShapeVerdict(args, (shape) => shape.cv === 'const' || shape.cv === 'const volatile', {
+        requireTopLevelCv: true,
+      }),
+  ],
+  [
+    'is_volatile_v',
+    (args) =>
+      unaryShapeVerdict(args, (shape) => shape.cv === 'volatile' || shape.cv === 'const volatile', {
+        requireTopLevelCv: true,
+      }),
+  ],
+  [
+    'is_same_v',
+    (args) => {
+      if (args.length < 2 || args[0].typeClass === 'unknown' || args[1].typeClass === 'unknown') {
+        return 'unknown';
+      }
+      return args[0].typeClass === args[1].typeClass ? 'compatible' : 'incompatible';
+    },
+  ],
+]);
+
+function unaryVerdict(
+  args: readonly ConstraintArgClass[],
+  predicate: (arg: ConstraintArgClass) => boolean,
+): ArityVerdict {
+  const arg = args[0];
+  if (arg === undefined || arg.typeClass === 'unknown') return 'unknown';
+  return predicate(arg) ? 'compatible' : 'incompatible';
+}
+
+function unaryShapeVerdict(
+  args: readonly ConstraintArgClass[],
+  predicate: (shape: ParameterTypeClass) => boolean,
+  options: { readonly requireTopLevelCv?: boolean } = {},
+): ArityVerdict {
+  const arg = args[0];
+  if (arg === undefined || arg.typeClass === 'unknown') return 'unknown';
+  const shape = arg.shape;
+  if (shape === undefined || shape.indirection === 'unknown' || shape.cv === 'unknown') {
+    return 'unknown';
+  }
+  if (options.requireTopLevelCv === true && shape.indirection === 'pointer') {
+    return 'unknown';
+  }
+  return predicate(shape) ? 'compatible' : 'incompatible';
+}
+
+function isPlainValue(arg: ConstraintArgClass): boolean {
+  const shape = arg.shape;
+  if (shape === undefined) return true;
+  return shape.indirection === 'value';
+}
+
+function classifyConstraintArg(
+  token: string | undefined,
+  shape?: ParameterTypeClass,
+): ConstraintArgClass {
+  if (shape !== undefined && shape.base.startsWith('enum:')) {
+    return { typeClass: 'enum', shape };
+  }
+  const typeClass = token === undefined || token === '' ? 'unknown' : classifyType(token);
+  return { typeClass, ...(shape !== undefined ? { shape } : {}) };
+}
+
+function tokenForArg(ctx: ConstraintContext, argIdx: number): string | undefined {
+  const shape = ctx.argumentTypeClasses?.[argIdx];
+  if (shape?.base.startsWith('enum:')) return shape.base;
+  return ctx.argumentTypes?.[argIdx];
+}
+
+function shapeForTemplateParam(
+  ctx: ConstraintContext,
+  paramName: string,
+  argIdx: number,
+  def?: SymbolDefinition,
+): ParameterTypeClass | undefined {
+  const argShape = ctx.argumentTypeClasses?.[argIdx];
+  if (argShape === undefined) return undefined;
+
+  const paramShape = def?.parameterTypeClasses?.[argIdx];
+  if (paramShape === undefined) return argShape;
+  if (paramShape.base === paramName && paramShape.indirection === 'value') return argShape;
+  return undefined;
+}
+
+/** Public surface — registered as `ScopeResolver.constraintCompatibility`. */
+export function cppConstraintCompatibility(
+  _callsite: Callsite,
+  def: SymbolDefinition,
+  ctx: ConstraintContext,
+): ArityVerdict {
+  const payload = def.templateConstraints as CppConstraintPayload | undefined;
+  if (payload === undefined) return 'unknown';
+  return evaluate(payload.expr, payload, ctx, def);
+}
+
+function evaluate(
+  expr: ConstraintExpr,
+  payload: CppConstraintPayload,
+  ctx: ConstraintContext,
+  def?: SymbolDefinition,
+): ArityVerdict {
+  switch (expr.kind) {
+    case 'unknown':
+      return 'unknown';
+    case 'atomic': {
+      const evaluator = REGISTRY.get(expr.name);
+      if (evaluator === undefined) return 'unknown';
+      const classes = expr.args.map((paramName) => {
+        const argIdx = payload.paramArgIndex[paramName];
+        if (argIdx === undefined) return { typeClass: 'unknown' as TypeClass };
+        return classifyConstraintArg(
+          tokenForArg(ctx, argIdx),
+          shapeForTemplateParam(ctx, paramName, argIdx, def),
+        );
+      });
+      return evaluator(classes);
+    }
+    case 'and': {
+      let result: ArityVerdict = 'compatible';
+      for (const child of expr.children) {
+        const v = evaluate(child, payload, ctx, def);
+        if (v === 'incompatible') return 'incompatible';
+        if (v === 'unknown') result = 'unknown';
+      }
+      return result;
+    }
+    case 'or': {
+      let result: ArityVerdict = 'incompatible';
+      for (const child of expr.children) {
+        const v = evaluate(child, payload, ctx, def);
+        if (v === 'compatible') return 'compatible';
+        if (v === 'unknown') result = 'unknown';
+      }
+      return result;
+    }
+    case 'not': {
+      const v = evaluate(expr.child, payload, ctx, def);
+      if (v === 'compatible') return 'incompatible';
+      if (v === 'incompatible') return 'compatible';
+      return 'unknown';
+    }
+  }
+}
+
+/** Exposed for unit tests — lets `cpp-constraint.test.ts` assert
+ *  `expect(getRegistrySize()).toBe(4)` without exporting the Map itself. */
+export function getRegistrySize(): number {
+  return REGISTRY.size;
+}
+
+/** Exposed for unit tests covering the Kleene 3-valued truth table
+ *  directly, without an AST round-trip. */
+export function evaluateForTest(
+  expr: ConstraintExpr,
+  payload: CppConstraintPayload,
+  ctx: ConstraintContext,
+): ArityVerdict {
+  return evaluate(expr, payload, ctx);
+}

gitnexus/src/core/ingestion/languages/cpp/conversion-rank.ts

@@ -1,32 +1,30 @@
 /**
- * C++ conversion-rank scoring for overload resolution (#1578).
+ * C++ conversion-rank scoring for overload resolution (#1578, #1637).
  *
- * Operates on **normalized** type strings (output of
- * `normalizeCppParamType` in `arity-metadata.ts`). After normalization:
- *   - int/long/short/unsigned → 'int'
- *   - float/double → 'double'
- *   - char → 'char', bool → 'bool'
- *
- * Because the normalizer collapses promotion pairs (int↔long,
- * float↔double) to the same string, those promotions are invisible at
- * this layer — they appear as exact matches (rank 0).
+ * Operates on normalized type strings (output of `normalizeCppParamType`
+ * in `arity-metadata.ts`) plus optional shape sidecars from #1630.
+ * Normalization intentionally collapses cv/ref/pointer spelling for stable
+ * graph IDs, so pointer/nullptr rules must consult `ParameterTypeClass`.
  *
  * Post-normalization ranking:
- *   - rank 0 — exact (same normalized type)
- *   - rank 1 — integral promotion (char→int, bool→int)
- *   - rank 2 — standard arithmetic conversion (int↔double, char→double,
- *              bool→double)
- *   - Infinity — mismatch (string↔int, user types, pointers, etc.)
+ *   - rank 0: exact (same normalized type)
+ *   - rank 1: integral promotion (char -> int, bool -> int)
+ *   - rank 2: standard conversion (arithmetic, nullptr -> T*, T* -> bool,
+ *             T* -> void*)
+ *   - rank 3: nullptr -> bool (kept worse than nullptr -> T*)
+ *   - rank 4: ellipsis conversion (worst viable)
+ *   - Infinity: mismatch (string -> int, user types, unsupported shapes)
  *
- * This function is intentionally C++-specific (issue #1578 pitfall:
- * keep conversion-rank tables out of shared overload-narrowing). Other
- * languages may define their own `ConversionRankFn` in the future.
+ * This function is intentionally C++-specific. Other languages may define
+ * their own `ConversionRankFn` in the future.
  */
 
+import type { ParameterTypeClass } from 'gitnexus-shared';
+
 /** Set of normalized arithmetic types that support implicit conversion. */
 const ARITHMETIC = new Set(['int', 'double', 'char', 'bool']);
 
-/** Integral promotion targets: char→int and bool→int are rank 1. */
+/** Integral promotion targets: char -> int and bool -> int are rank 1. */
 const INTEGRAL_PROMOTION = new Map([
   ['char', 'int'],
   ['bool', 'int'],
@@ -35,13 +33,40 @@ const INTEGRAL_PROMOTION = new Map([
 /**
  * Return the conversion rank from `argType` to `paramType`.
  *
- * @returns 0 for exact match, 1 for integral promotion (char/bool→int),
- *          2 for standard arithmetic conversion, Infinity for mismatch.
+ * @returns 0 for exact match, 1 for integral promotion, 2 for standard
+ *          conversion, 3 for nullptr -> bool, 4 for ellipsis, Infinity
+ *          for mismatch.
  */
-export function cppConversionRank(argType: string, paramType: string): number {
-  if (argType === paramType) return 0;
-  // Integral promotions: char→int, bool→int (ISO C++ [conv.prom])
+export function cppConversionRank(
+  argType: string,
+  paramType: string,
+  argTypeClass?: ParameterTypeClass,
+  paramTypeClass?: ParameterTypeClass,
+): number {
+  if (argType === paramType) {
+    return exactShapeCompatible(argTypeClass, paramTypeClass) ? 0 : Infinity;
+  }
+  if (paramType === '...') return 4;
   if (INTEGRAL_PROMOTION.get(argType) === paramType) return 1;
   if (ARITHMETIC.has(argType) && ARITHMETIC.has(paramType)) return 2;
+  if (argType === 'null' && isPointer(paramTypeClass)) return 2;
+  if (argType === 'null' && paramType === 'bool') return 3;
+  if (isPointer(argTypeClass) && paramType === 'bool') return 2;
+  if (isPointer(argTypeClass) && isPointer(paramTypeClass) && paramType === 'void') return 2;
   return Infinity;
 }
+
+function isPointer(typeClass: ParameterTypeClass | undefined): boolean {
+  return typeClass?.indirection === 'pointer' && typeClass.pointerDepth > 0;
+}
+
+function exactShapeCompatible(
+  argTypeClass: ParameterTypeClass | undefined,
+  paramTypeClass: ParameterTypeClass | undefined,
+): boolean {
+  if (argTypeClass === undefined || paramTypeClass === undefined) return true;
+  if (argTypeClass.indirection === 'unknown' || paramTypeClass.indirection === 'unknown') {
+    return true;
+  }
+  return isPointer(argTypeClass) === isPointer(paramTypeClass);
+}

gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts

@@ -33,6 +33,7 @@ import {
   resolveCppQualifiedNamespaceMember,
 } from './inline-namespaces.js';
 import { populateCppRangeBindings } from './range-bindings.js';
+import { cppConstraintCompatibility } from './constraint-filter.js';
 
 /**
  * C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by
@@ -85,6 +86,12 @@ export const cppScopeResolver: ScopeResolver = {
   // (def, callsite). ScopeResolver contract is (callsite, def).
   arityCompatibility: (callsite, def) => cppArityCompatibility(def, callsite),
 
+  // SFINAE / `requires`-clause aware overload filter (issue #1579).
+  // Drops candidates whose template constraints (`enable_if_t<P, T>`,
+  // C++20 `requires P`) provably fail at the call site. Three-valued —
+  // `'unknown'` keeps the candidate, preserving "degrade not lie".
+  constraintCompatibility: cppConstraintCompatibility,
+
   buildMro: (graph, parsedFiles, nodeLookup) =>
     buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
 

gitnexus/src/core/ingestion/languages/cpp/type-classifier.ts

@@ -0,0 +1,66 @@
+/**
+ * Coarse-grained type classifier for C++ constraint evaluation
+ * (`<https://en.cppreference.com/w/cpp/types/is_integral>`,
+ *  `<https://en.cppreference.com/w/cpp/types/is_floating_point>`).
+ *
+ * Maps a normalized type token (as produced by `normalizeCppParamType` /
+ * the call-site inference in `captures.ts`) to one of the categories
+ * the `<type_traits>` predicate registry uses for SFINAE filtering.
+ *
+ * `argumentTypes` remain normalized for overload narrowing, while
+ * constraint predicates that need cv/ref/pointer shape read the parallel
+ * `argumentTypeClasses` sidecar. Unknown shapes must stay unknown rather
+ * than being guessed as incompatible.
+ */
+
+export type TypeClass =
+  | 'integral'
+  | 'floating'
+  | 'bool'
+  | 'char'
+  | 'string'
+  | 'null'
+  | 'void'
+  | 'enum'
+  | 'class'
+  | 'pointer'
+  | 'reference'
+  | 'unknown';
+
+/**
+ * Classify a normalized C++ type token. The mapping mirrors the literal-
+ * inference table in `captures.ts:inferCppLiteralType` plus the std::
+ * normalization in `arity-metadata.ts:normalizeCppParamType`.
+ *
+ * Caller note: token should be normalized for overload matching. Enum
+ * tokens produced by the C++ adapter use the internal `enum:<Name>`
+ * prefix so `is_enum_v` does not have to guess that every user token is
+ * class-like.
+ */
+export function classifyType(token: string): TypeClass {
+  if (token.length === 0) return 'unknown';
+  if (token.startsWith('enum:')) return 'enum';
+  switch (token) {
+    case 'void':
+      return 'void';
+    case 'int':
+      return 'integral';
+    case 'double':
+    case 'float':
+      return 'floating';
+    case 'bool':
+      return 'bool';
+    case 'char':
+      return 'char';
+    case 'string':
+      return 'string';
+    case 'null':
+      return 'null';
+    default:
+      // After normalization, anything that isn't a recognized primitive
+      // is assumed to be a class-like type. The Tier-A predicate registry
+      // doesn't introspect class types — `is_integral_v` etc. simply
+      // returns `false` for `'class'`, matching ISO behavior.
+      return 'class';
+  }
+}

gitnexus/src/core/ingestion/languages/java.ts

@@ -27,6 +27,7 @@ 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';
+import type { SymbolDefinition } from 'gitnexus-shared';
 import {
   emitJavaScopeCaptures,
   interpretJavaImport,
@@ -39,6 +40,48 @@ import {
   resolveJavaImportTarget,
 } from './java/index.js';
 
+const orderJavaSameNameTypeCandidates = ({
+  callSiteFilePath,
+  candidates,
+}: {
+  readonly typeName: string;
+  readonly callSiteFilePath: string;
+  readonly candidates: readonly SymbolDefinition[];
+}): readonly SymbolDefinition[] | null => {
+  if (!callSiteFilePath.endsWith('.java')) return null;
+  if (candidates.length <= 1) return null;
+  const callerDir = splitDirectorySegments(callSiteFilePath);
+
+  const scored = candidates.map((candidate, index) => ({
+    candidate,
+    index,
+    score: sharedPrefixLength(callerDir, splitDirectorySegments(candidate.filePath)),
+  }));
+  const bestScore = Math.max(...scored.map((entry) => entry.score));
+  // When all candidates tie, we have no structural signal to prefer one path.
+  // Returning null keeps downstream ambiguity handling conservative.
+  if (scored.every((entry) => entry.score === bestScore)) return null;
+
+  const ordered = [...scored]
+    .sort((a, b) => b.score - a.score || a.index - b.index)
+    .map((entry) => entry.candidate);
+  return ordered;
+};
+
+const splitDirectorySegments = (filePath: string): string[] => {
+  const normalized = filePath.replace(/\\/g, '/');
+  // Remove empty segments from leading/trailing/multiple slashes, then drop filename.
+  const segments = normalized.split('/').filter(Boolean);
+  return segments.slice(0, -1);
+};
+
+const sharedPrefixLength = (left: readonly string[], right: readonly string[]): number => {
+  const max = Math.min(left.length, right.length);
+  let idx = 0;
+  while (idx < max && left[idx] === right[idx]) idx += 1;
+  return idx;
+};
+
 export const javaProvider = defineLanguage({
   id: SupportedLanguages.Java,
   extensions: ['.java'],
@@ -87,4 +130,5 @@ export const javaProvider = defineLanguage({
   receiverBinding: javaReceiverBinding,
   arityCompatibility: javaArityCompatibility,
   resolveImportTarget: resolveJavaImportTarget,
+  orderSameNameTypeCandidates: orderJavaSameNameTypeCandidates,
 });

gitnexus/src/core/ingestion/languages/javascript/arity.ts

@@ -0,0 +1,12 @@
+/**
+ * Arity compatibility for JavaScript.
+ *
+ * Delegates to `typescriptArityCompatibility` unchanged — JavaScript
+ * supports the same arity constructs (rest parameters `...args`, default
+ * parameters `p = v`) and the metadata shape (`parameterCount`,
+ * `requiredParameterCount`, `parameterTypes`) is synthesized by the same
+ * `computeTsArityMetadata` function (which understands both TS and JS
+ * parameter node types via `extractTsJsParameters`).
+ */
+
+export { typescriptArityCompatibility as jsArityCompatibility } from '../typescript/arity.js';

gitnexus/src/core/ingestion/languages/javascript/captures.ts

@@ -0,0 +1,722 @@
+/**
+ * `emitScopeCaptures` for JavaScript.
+ *
+ * Adapts `emitTsScopeCaptures` for the JavaScript grammar:
+ *
+ *   1. **JS grammar** — uses `tree-sitter-javascript` instead of
+ *      `tree-sitter-typescript`. The JS scope query is a subset of the
+ *      TypeScript one (TypeScript-only node types dropped).
+ *
+ *   2. **CJS `require()` decomposition** — `const { X } = require('./m')`
+ *      and `const X = require('./m')` are walked in a post-query pass and
+ *      synthesized as `@import.kind/name/alias/source` markers so that
+ *      `interpretJsImport` can recover a `ParsedImport` using the same
+ *      shape as the TypeScript ESM decomposer.
+ *
+ *   3. **JSDoc type bindings** — JavaScript has no static type annotations
+ *      so `@type-binding.parameter` / `@type-binding.return` must be
+ *      inferred from leading JSDoc comments. A lightweight regex scanner
+ *      (`parseJsDocParams` / `parseJsDocReturn`) extracts `@param {T} n`
+ *      and `@returns {T}` tags and emits synthetic captures positioned on
+ *      the annotated function node.
+ *
+ *   4. **Shared synthesis passes** — destructuring, for-of map-tuple, and
+ *      instanceof narrowing passes are duplicated from `typescript/captures.ts`
+ *      (they are pure AST operations with no grammar-specific logic).
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+
+import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import {
+  findNodeAtRange,
+  nodeToCapture,
+  syntheticCapture,
+  type SyntaxNode,
+} from '../../utils/ast-helpers.js';
+import { splitImportStatement } from '../typescript/import-decomposer.js';
+import { getJsParser, getJsScopeQuery, jsCachedTreeMatchesGrammar } from './query.js';
+import { computeTsArityMetadata } from '../typescript/arity-metadata.js';
+import { synthesizeTsReceiverBinding } from '../typescript/receiver-binding.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+
+/** JS function-like node types that may carry a synthesized `this` binding.
+ *  Kept in sync with the `@scope.function` patterns in `query.ts`. */
+const FUNCTION_NODE_TYPES = [
+  'method_definition',
+  'arrow_function',
+  'function_expression',
+  'function_declaration',
+  'generator_function_declaration',
+] as const;
+
+/** Declaration anchors that carry function-like arity metadata. */
+const FUNCTION_DECL_TAGS = ['@declaration.method', '@declaration.function'] as const;
+
+/** Callsite anchors that should carry `@reference.arity` + param types. */
+const CALL_TAGS = [
+  '@reference.call.free',
+  '@reference.call.member',
+  '@reference.call.constructor',
+] as const;
+
+function pickFirstDefined(grouped: CaptureMatch, tags: readonly string[]): Capture | undefined {
+  for (const tag of tags) {
+    const cap = grouped[tag];
+    if (cap !== undefined) return cap;
+  }
+  return undefined;
+}
+
+/** Filter `@reference.read.member` in non-read contexts (same logic as TS). */
+function shouldEmitReadMember(memberNode: SyntaxNode): boolean {
+  const parent = memberNode.parent;
+  if (parent === null) return true;
+  switch (parent.type) {
+    case 'call_expression':
+      return parent.childForFieldName('function')?.id !== memberNode.id;
+    case 'new_expression':
+      return parent.childForFieldName('constructor')?.id !== memberNode.id;
+    case 'assignment_expression':
+    case 'augmented_assignment_expression':
+      return parent.childForFieldName('left')?.id !== memberNode.id;
+    case 'jsx_self_closing_element':
+    case 'jsx_opening_element':
+      return parent.childForFieldName('name')?.id !== memberNode.id;
+    default:
+      return true;
+  }
+}
+
+/** Find the first JS function-like node at the given range. */
+function findFunctionNode(rootNode: SyntaxNode, range: Capture['range']): SyntaxNode | null {
+  for (const nodeType of FUNCTION_NODE_TYPES) {
+    const n = findNodeAtRange(rootNode, range, nodeType);
+    if (n !== null) return n;
+  }
+  return null;
+}
+
+/** Infer a callsite argument's static type from literal shapes. */
+function inferArgType(argNode: SyntaxNode): string {
+  switch (argNode.type) {
+    case 'number':
+      return 'number';
+    case 'string':
+    case 'template_string':
+      return 'string';
+    case 'true':
+    case 'false':
+      return 'boolean';
+    case 'null':
+      return 'null';
+    case 'undefined':
+      return 'undefined';
+    case 'array':
+      return 'Array';
+    case 'object':
+      return 'object';
+    case 'regex':
+      return 'RegExp';
+    case 'new_expression': {
+      const ctor = argNode.childForFieldName('constructor');
+      return ctor?.text ?? '';
+    }
+    default:
+      return '';
+  }
+}
+
+// ─── CJS require() decomposition ─────────────────────────────────────────
+
+/**
+ * Walk the AST and synthesize `@import.*` captures for CJS `require()` calls:
+ *
+ *   - `const { X, Y } = require('./m')` → one match per destructured name,
+ *     `@import.kind = 'named'`, `@import.name = X / Y`.
+ *   - `const X = require('./m')` → `@import.kind = 'namespace'`,
+ *     `@import.alias = X` (the whole module is bound to X).
+ *   - `require('./m')` as a bare expression-statement → side-effect.
+ *
+ * CJS named-alias form (`const { X: alias } = require('./m')`) emits
+ * `@import.kind = 'named-alias'` with `@import.name = X` and
+ * `@import.alias = alias`.
+ *
+ * The synthesized markers are identical to those produced by
+ * `splitImportStatement` for ESM, so `interpretJsImport` can delegate
+ * unchanged to `interpretTsImport` for all cases.
+ */
+function synthesizeCjsImports(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+
+    if (node.type !== 'call_expression') continue;
+
+    // Require call: function must be bare identifier "require".
+    const fn = node.childForFieldName('function');
+    if (fn === null || fn.type !== 'identifier' || fn.text !== 'require') continue;
+
+    const argsNode = node.childForFieldName('arguments');
+    if (argsNode === null) continue;
+
+    // Source must be a string literal.
+    const firstArg = argsNode.namedChild(0);
+    if (firstArg === null || firstArg.type !== 'string') continue;
+    const rawSource = firstArg.text; // includes surrounding quotes
+    const source = firstArg.namedChild(0)?.text ?? rawSource.slice(1, -1);
+
+    const parent = node.parent;
+
+    // Case 1: const { X } = require('./m') OR const X = require('./m')
+    if (parent?.type === 'variable_declarator') {
+      const nameNode = parent.childForFieldName('name');
+      if (nameNode === null) continue;
+
+      if (nameNode.type === 'object_pattern') {
+        // Destructured: emit one match per specifier.
+        for (const field of nameNode.namedChildren) {
+          if (field === null) continue;
+          if (field.type === 'shorthand_property_identifier_pattern') {
+            const name = field.text;
+            out.push({
+              '@import.statement': syntheticCapture('@import.statement', node, rawSource),
+              '@import.kind': syntheticCapture('@import.kind', node, 'named'),
+              '@import.name': syntheticCapture('@import.name', field, name),
+              '@import.source': syntheticCapture('@import.source', firstArg, source),
+            });
+          } else if (field.type === 'pair_pattern') {
+            const key = field.childForFieldName('key');
+            const value = field.childForFieldName('value');
+            if (key === null || value === null || value.type !== 'identifier') continue;
+            out.push({
+              '@import.statement': syntheticCapture('@import.statement', node, rawSource),
+              '@import.kind': syntheticCapture('@import.kind', node, 'named-alias'),
+              '@import.name': syntheticCapture('@import.name', key, key.text),
+              '@import.alias': syntheticCapture('@import.alias', value, value.text),
+              '@import.source': syntheticCapture('@import.source', firstArg, source),
+            });
+          }
+        }
+      } else if (nameNode.type === 'identifier') {
+        // Namespace-style: const X = require('./m') → bind whole module to X.
+        out.push({
+          '@import.statement': syntheticCapture('@import.statement', node, rawSource),
+          '@import.kind': syntheticCapture('@import.kind', node, 'namespace'),
+          '@import.alias': syntheticCapture('@import.alias', nameNode, nameNode.text),
+          '@import.source': syntheticCapture('@import.source', firstArg, source),
+        });
+      }
+      continue;
+    }
+
+    // Case 2: bare require('./m') — side-effect import.
+    if (parent?.type === 'expression_statement') {
+      out.push({
+        '@import.statement': syntheticCapture('@import.statement', node, rawSource),
+        '@import.kind': syntheticCapture('@import.kind', node, 'side-effect'),
+        '@import.source': syntheticCapture('@import.source', firstArg, source),
+      });
+    }
+  }
+}
+
+// ─── JSDoc type binding synthesis ────────────────────────────────────────
+
+interface JsDocParam {
+  readonly name: string;
+  readonly type: string;
+}
+
+/** Extract `@param {Type} name` entries from a JSDoc comment block. */
+function parseJsDocParams(text: string): readonly JsDocParam[] {
+  const results: JsDocParam[] = [];
+  // Match @param {Type} name or @param {Type} [name] (optional)
+  const re = /@param\s+\{([^}]+)\}\s+\[?(\w+)\]?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    results.push({ type: m[1].trim(), name: m[2].trim() });
+  }
+  return results;
+}
+
+/** Extract `@returns {Type}` or `@return {Type}` from a JSDoc comment. */
+function parseJsDocReturn(text: string): string | null {
+  const m = /@returns?\s+\{([^}]+)\}/.exec(text);
+  return m ? m[1].trim() : null;
+}
+
+/** Extract `@type {Type}` from a JSDoc comment (variable-level annotation). */
+function parseJsDocType(text: string): string | null {
+  const m = /@type\s+\{([^}]+)\}/.exec(text);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Walk the AST and synthesize `@type-binding.*` captures from JSDoc
+ * comments immediately preceding function declarations / expressions.
+ *
+ * Only `/** … *​/` block comments are scanned. Line comments (`//`) are
+ * intentionally excluded — JSDoc lives in block comments.
+ *
+ * Emits:
+ *   - `@type-binding.parameter` for each `@param {T} n` tag.
+ *   - `@type-binding.return` for `@returns {T}` / `@return {T}`.
+ *   - `@type-binding.annotation` for `@type {T}` on `let`/`const`/`var`
+ *     declarations — covers the common `/** @type {User} *​/ const u = …`
+ *     pattern (ECMA-262 §14.3.1/§14.3.2 variable declarations).
+ *
+ * The binding is anchored on the function node so `tsBindingScopeFor`
+ * can hoist method return-type bindings to Module scope (matching the
+ * TypeScript path where `hoistTypeBindingsToModule: true`).
+ */
+function synthesizeJsDocBindings(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+
+    const isFnDecl =
+      node.type === 'function_declaration' || node.type === 'generator_function_declaration';
+    const isMethodDef = node.type === 'method_definition';
+    // Also check lexical_declaration containing an arrow/fn-expression
+    const isLexDecl = node.type === 'lexical_declaration' || node.type === 'variable_declaration';
+
+    if (!isFnDecl && !isMethodDef && !isLexDecl) continue;
+
+    // For `export function foo() { ... }`, the JSDoc comment precedes the
+    // wrapping export_statement, not the inner function_declaration.
+    // Walk up to the export_statement so the preceding-sibling search finds it.
+    const lookupNode =
+      (isFnDecl || isLexDecl) && node.parent?.type === 'export_statement' ? node.parent : node;
+
+    // Find the preceding sibling comment.
+    let sibling = lookupNode.previousNamedSibling;
+    while (sibling !== null && sibling.type === 'comment') {
+      const text = sibling.text;
+      if (text.startsWith('/**')) {
+        // Found a JSDoc block.
+        const params = parseJsDocParams(text);
+        const retType = parseJsDocReturn(text);
+        const varType = isLexDecl ? parseJsDocType(text) : null;
+
+        // Determine the anchor node (the function-like node, for hoisting).
+        const anchor = node;
+
+        for (const p of params) {
+          out.push({
+            '@type-binding.name': syntheticCapture('@type-binding.name', anchor, p.name),
+            '@type-binding.type': syntheticCapture('@type-binding.type', anchor, p.type),
+            '@type-binding.parameter': syntheticCapture('@type-binding.parameter', anchor, '1'),
+          });
+        }
+
+        if (retType !== null) {
+          // For named functions, use the function name as the binding name so
+          // `hoistTypeBindingsToModule` knows which function's return type this is.
+          let fnName: string | null = null;
+          if (isFnDecl) {
+            fnName = node.childForFieldName('name')?.text ?? null;
+          } else if (isMethodDef) {
+            // method_definition uses `name:` field for the method name
+            const nameNode = node.childForFieldName('name');
+            if (nameNode?.type === 'property_identifier') fnName = nameNode.text;
+          } else if (isLexDecl) {
+            const declarator = node.namedChild(0);
+            const nameNode = declarator?.childForFieldName('name');
+            if (nameNode?.type === 'identifier') fnName = nameNode.text;
+          }
+          if (fnName !== null) {
+            out.push({
+              '@type-binding.name': syntheticCapture('@type-binding.name', anchor, fnName),
+              '@type-binding.type': syntheticCapture('@type-binding.type', anchor, retType),
+              '@type-binding.return': syntheticCapture('@type-binding.return', anchor, '1'),
+            });
+          }
+        }
+
+        // @type {T} on let/const/var: `/** @type {User} */ const u = getUser()`.
+        // Emits annotation-strength binding (source = 'annotation') so it
+        // overrides any weaker constructor/alias inference on the same name.
+        if (varType !== null) {
+          for (const declarator of node.namedChildren) {
+            if (declarator === null || declarator.type !== 'variable_declarator') continue;
+            const nameNode = declarator.childForFieldName('name');
+            if (nameNode === null || nameNode.type !== 'identifier') continue;
+            out.push({
+              '@type-binding.name': syntheticCapture('@type-binding.name', nameNode, nameNode.text),
+              '@type-binding.type': syntheticCapture('@type-binding.type', nameNode, varType),
+              '@type-binding.annotation': syntheticCapture(
+                '@type-binding.annotation',
+                nameNode,
+                '1',
+              ),
+            });
+          }
+        }
+
+        break;
+      }
+      sibling = sibling.previousNamedSibling;
+    }
+  }
+}
+
+// ─── Destructuring / for-of / instanceof (shared with TS captures) ───────
+
+function synthesizeDestructuringBindings(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+    if (node.type !== 'variable_declarator') continue;
+    const nameNode = node.childForFieldName('name');
+    const valueNode = node.childForFieldName('value');
+    if (nameNode === null || valueNode === null) continue;
+    if (nameNode.type !== 'object_pattern') continue;
+    if (valueNode.type !== 'identifier') continue;
+    const rhsName = valueNode.text;
+    for (const fieldNode of nameNode.namedChildren) {
+      if (fieldNode === null) continue;
+      if (fieldNode.type === 'shorthand_property_identifier_pattern') {
+        const localName = fieldNode.text;
+        out.push({
+          '@type-binding.name': syntheticCapture('@type-binding.name', fieldNode, localName),
+          '@type-binding.type': syntheticCapture(
+            '@type-binding.type',
+            fieldNode,
+            `${rhsName}.${localName}`,
+          ),
+          '@type-binding.destructured': syntheticCapture(
+            '@type-binding.destructured',
+            fieldNode,
+            fieldNode.text,
+          ),
+        });
+      } else if (fieldNode.type === 'pair_pattern') {
+        const key = fieldNode.childForFieldName('key');
+        const value = fieldNode.childForFieldName('value');
+        if (key === null || value === null || value.type !== 'identifier') continue;
+        const fieldName = key.text;
+        const localName = value.text;
+        out.push({
+          '@type-binding.name': syntheticCapture('@type-binding.name', value, localName),
+          '@type-binding.type': syntheticCapture(
+            '@type-binding.type',
+            fieldNode,
+            `${rhsName}.${fieldName}`,
+          ),
+          '@type-binding.destructured': syntheticCapture(
+            '@type-binding.destructured',
+            fieldNode,
+            fieldNode.text,
+          ),
+        });
+      }
+    }
+  }
+}
+
+function synthesizeForOfMapTupleBindings(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+    if (node.type !== 'for_in_statement') continue;
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (left === null || right === null) continue;
+    if (left.type !== 'array_pattern' || right.type !== 'identifier') continue;
+    const rhs = right.text;
+    let slot = 0;
+    for (const child of left.namedChildren) {
+      if (child === null || child.type !== 'identifier') continue;
+      const localName = child.text;
+      out.push({
+        '@type-binding.name': syntheticCapture('@type-binding.name', child, localName),
+        '@type-binding.type': syntheticCapture(
+          '@type-binding.type',
+          child,
+          `__MAP_TUPLE_${slot}__:${rhs}`,
+        ),
+        '@type-binding.map-tuple-entry': syntheticCapture(
+          '@type-binding.map-tuple-entry',
+          child,
+          String(slot),
+        ),
+      });
+      slot++;
+    }
+  }
+}
+
+function synthesizeInstanceofNarrowings(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+    if (node.type !== 'if_statement') continue;
+    const cond = node.childForFieldName('condition');
+    if (cond === null) continue;
+    const inner = cond.type === 'parenthesized_expression' ? cond.namedChildren[0] : cond;
+    if (inner === null || inner.type !== 'binary_expression') continue;
+    const op = inner.childForFieldName('operator');
+    const left = inner.childForFieldName('left');
+    const right = inner.childForFieldName('right');
+    if (op === null || left === null || right === null) continue;
+    if (op.type !== 'instanceof') continue;
+    if (left.type !== 'identifier') continue;
+    if (right.type !== 'identifier') continue;
+    const varName = left.text;
+    const typeName = right.text;
+    const cons = node.childForFieldName('consequence');
+    if (cons === null) continue;
+    out.push({
+      '@type-binding.name': syntheticCapture('@type-binding.name', cons, varName),
+      '@type-binding.type': syntheticCapture('@type-binding.type', right, typeName),
+      '@type-binding.instanceof-narrow': syntheticCapture(
+        '@type-binding.instanceof-narrow',
+        cons,
+        '1',
+      ),
+    });
+  }
+}
+
+// ─── Constructor field type bindings ─────────────────────────────────────
+
+/**
+ * Synthesize class-scope type bindings from `this.X = new Y()` assignments
+ * inside constructor method bodies.  Covers the traditional ES5+ OOP pattern:
+ *
+ *   class User {
+ *     constructor() {
+ *       /** @type {Address} *\/
+ *       this.address = new Address();
+ *     }
+ *   }
+ *
+ * The emitted `@type-binding.class-field` is hoisted to the Class scope by
+ * `tsBindingScopeFor` so that compound-receiver resolution can look up
+ * `User.address → Address` when resolving `user.address.save()`.
+ *
+ * Type source priority:
+ *   1. JSDoc `@type {T}` comment immediately preceding the statement
+ *   2. `new Y()` constructor inference
+ */
+function synthesizeConstructorFieldBindings(root: SyntaxNode, out: CaptureMatch[]): void {
+  const stack: SyntaxNode[] = [root];
+  for (;;) {
+    const node = stack.pop();
+    if (node === undefined) break;
+    for (const child of node.namedChildren) {
+      if (child !== null) stack.push(child);
+    }
+    // Only process constructor method definitions
+    if (node.type !== 'method_definition') continue;
+    const nameNode = node.childForFieldName('name');
+    if (nameNode?.text !== 'constructor') continue;
+
+    const body = node.childForFieldName('body');
+    if (body === null) continue;
+
+    for (const stmt of body.namedChildren) {
+      if (stmt === null || stmt.type !== 'expression_statement') continue;
+      const expr = stmt.namedChild(0);
+      if (expr === null || expr.type !== 'assignment_expression') continue;
+
+      const left = expr.childForFieldName('left');
+      const right = expr.childForFieldName('right');
+      if (left === null || right === null) continue;
+      if (left.type !== 'member_expression') continue;
+
+      const obj = left.childForFieldName('object');
+      const prop = left.childForFieldName('property');
+      if (obj === null || prop === null) continue;
+      if (obj.text !== 'this' || prop.type !== 'property_identifier') continue;
+
+      const fieldName = prop.text;
+
+      // Prefer JSDoc @type annotation on the preceding sibling comment.
+      let typeName: string | null = null;
+      const prevSib: SyntaxNode | null = stmt.previousNamedSibling;
+      if (prevSib !== null && prevSib.type === 'comment') {
+        const m = /@type\s*\{([^}]+)\}/.exec(prevSib.text);
+        if (m?.[1]) typeName = m[1].trim();
+      }
+      // Fall back to constructor inference from `new Y()`.
+      if (typeName === null && right.type === 'new_expression') {
+        const ctor = right.childForFieldName('constructor');
+        if (ctor !== null && ctor.type === 'identifier') typeName = ctor.text;
+      }
+      if (typeName === null) continue;
+
+      out.push({
+        '@type-binding.name': syntheticCapture('@type-binding.name', prop, fieldName),
+        '@type-binding.type': syntheticCapture('@type-binding.type', prop, typeName),
+        // Anchor: positioned inside the constructor body so tsBindingScopeFor
+        // can walk up from the Function (constructor) scope to the Class scope.
+        '@type-binding.class-field': syntheticCapture('@type-binding.class-field', stmt, '1'),
+      });
+    }
+  }
+}
+
+// ─── Main emitter ──────────────────────────────────────────────────────────
+
+export function emitJsScopeCaptures(
+  sourceText: string,
+  filePath: string,
+  cachedTree?: unknown,
+): readonly CaptureMatch[] {
+  let tree = cachedTree as ReturnType<ReturnType<typeof getJsParser>['parse']> | undefined;
+  if (tree !== undefined && !jsCachedTreeMatchesGrammar(tree)) {
+    tree = undefined;
+  }
+  if (tree === undefined) {
+    tree = parseSourceSafe(getJsParser(filePath), sourceText, undefined, {
+      bufferSize: getTreeSitterBufferSize(sourceText),
+    });
+  }
+
+  const rawMatches = getJsScopeQuery(filePath).matches(tree.rootNode);
+  const out: CaptureMatch[] = [];
+
+  for (const m of rawMatches) {
+    const grouped: Record<string, Capture> = {};
+    for (const c of m.captures) {
+      const tag = '@' + c.name;
+      grouped[tag] = nodeToCapture(tag, c.node);
+    }
+    if (Object.keys(grouped).length === 0) continue;
+
+    // Decompose ESM import_statement / re-export export_statement.
+    if (grouped['@import.statement'] !== undefined) {
+      const stmtCapture = grouped['@import.statement'];
+      const stmtNode =
+        findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement') ??
+        findNodeAtRange(tree.rootNode, stmtCapture.range, 'export_statement');
+      if (stmtNode !== null) {
+        const decomposed = splitImportStatement(stmtNode);
+        for (const d of decomposed) out.push(d);
+      }
+      continue;
+    }
+
+    // Decompose dynamic import() calls.
+    if (grouped['@import.dynamic'] !== undefined) {
+      const dynCapture = grouped['@import.dynamic'];
+      const callNode = findNodeAtRange(tree.rootNode, dynCapture.range, 'call_expression');
+      if (callNode !== null) {
+        const decomposed = splitImportStatement(callNode);
+        for (const d of decomposed) out.push(d);
+      }
+      continue;
+    }
+
+    // Filter @reference.read.member false-positives.
+    if (grouped['@reference.read.member'] !== undefined) {
+      const anchor = grouped['@reference.read.member'];
+      const memberNode = findNodeAtRange(tree.rootNode, anchor.range, 'member_expression');
+      if (memberNode === null || !shouldEmitReadMember(memberNode)) {
+        continue;
+      }
+    }
+
+    // Synthesize arity metadata on function-like declarations.
+    const declAnchor = pickFirstDefined(grouped, FUNCTION_DECL_TAGS);
+    if (declAnchor !== undefined) {
+      const fnNode = findFunctionNode(tree.rootNode, declAnchor.range);
+      if (fnNode !== null) {
+        const arity = computeTsArityMetadata(fnNode);
+        if (arity.parameterCount !== undefined) {
+          grouped['@declaration.parameter-count'] = syntheticCapture(
+            '@declaration.parameter-count',
+            fnNode,
+            String(arity.parameterCount),
+          );
+        }
+        if (arity.requiredParameterCount !== undefined) {
+          grouped['@declaration.required-parameter-count'] = syntheticCapture(
+            '@declaration.required-parameter-count',
+            fnNode,
+            String(arity.requiredParameterCount),
+          );
+        }
+        if (arity.parameterTypes !== undefined) {
+          grouped['@declaration.parameter-types'] = syntheticCapture(
+            '@declaration.parameter-types',
+            fnNode,
+            JSON.stringify(arity.parameterTypes),
+          );
+        }
+      }
+    }
+
+    // Synthesize @reference.arity on callsites.
+    const callAnchor = pickFirstDefined(grouped, CALL_TAGS);
+    if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) {
+      const callNode =
+        findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression') ??
+        findNodeAtRange(tree.rootNode, callAnchor.range, 'new_expression');
+      if (callNode !== null) {
+        const argList = callNode.childForFieldName('arguments');
+        const args: SyntaxNode[] =
+          argList === null
+            ? []
+            : argList.namedChildren.filter(
+                (c): c is SyntaxNode => c !== null && c.type !== 'comment',
+              );
+        grouped['@reference.arity'] = syntheticCapture(
+          '@reference.arity',
+          callNode,
+          String(args.length),
+        );
+        grouped['@reference.parameter-types'] = syntheticCapture(
+          '@reference.parameter-types',
+          callNode,
+          JSON.stringify(args.map(inferArgType)),
+        );
+      }
+    }
+
+    out.push(grouped);
+
+    // Synthesize `this` receiver type-bindings on class member functions.
+    const scopeFnAnchor = grouped['@scope.function'];
+    if (scopeFnAnchor !== undefined) {
+      const fnNode = findFunctionNode(tree.rootNode, scopeFnAnchor.range);
+      if (fnNode !== null) {
+        const synth = synthesizeTsReceiverBinding(fnNode);
+        if (synth !== null) out.push(synth);
+      }
+    }
+  }
+
+  // Post-query synthesis passes.
+  synthesizeCjsImports(tree.rootNode, out);
+  synthesizeJsDocBindings(tree.rootNode, out);
+  synthesizeConstructorFieldBindings(tree.rootNode, out);
+  synthesizeDestructuringBindings(tree.rootNode, out);
+  synthesizeForOfMapTupleBindings(tree.rootNode, out);
+  synthesizeInstanceofNarrowings(tree.rootNode, out);
+
+  return out;
+}

gitnexus/src/core/ingestion/languages/javascript/import-target.ts

@@ -0,0 +1,72 @@
+/**
+ * Import-target resolver for JavaScript.
+ *
+ * Delegates to the TypeScript `resolveTsTarget` standard-strategy resolver
+ * with `language: SupportedLanguages.JavaScript` so the resolver tries
+ * `.js` / `.jsx` extensions in addition to (or instead of) `.ts` / `.tsx`.
+ *
+ * The `TsResolveContext.language` flag already exists in `import-target.ts`
+ * and the resolver (`resolveImportPath`) already branches on it — this
+ * adapter just wires the right value in.
+ *
+ * CJS `require()` calls reference the same module-path strings as ESM
+ * `import` statements, so the resolver handles them uniformly without any
+ * CJS-specific logic here.
+ *
+ * No `tsconfig.json` path-alias support (JavaScript projects don't use
+ * `tsconfig.json` compilerOptions.paths in general). Projects that DO use
+ * tsconfig-based aliases alongside JavaScript can still resolve via the
+ * standard extension-suffix fallback; the alias branch is a no-op when
+ * `tsconfigPaths` is null.
+ */
+
+import { SupportedLanguages } from 'gitnexus-shared';
+import { resolveTsTarget, type TsResolveContext } from '../typescript/import-target.js';
+
+export type JsResolveContext = TsResolveContext;
+
+type PassCache = {
+  readonly key: ReadonlySet<string>;
+  readonly allFilePaths: Set<string>;
+  readonly allFileList: readonly string[];
+  readonly normalizedFileList: readonly string[];
+  readonly resolveCache: Map<string, string | null>;
+};
+
+/**
+ * Build a memoized `resolveImportTarget` adapter for JavaScript.
+ * Caches the derived arrays and per-pass resolve cache across
+ * `resolveImportTarget` calls within a single workspace pass.
+ */
+export function makeJsResolveImportTarget(): (
+  targetRaw: string,
+  fromFile: string,
+  allFilePaths: ReadonlySet<string>,
+  resolutionConfig?: unknown,
+) => string | readonly string[] | null {
+  let cached: PassCache | null = null;
+
+  return (targetRaw, fromFile, allFilePaths) => {
+    if (cached === null || cached.key !== allFilePaths) {
+      const allFileList = Array.from(allFilePaths);
+      cached = {
+        key: allFilePaths,
+        allFilePaths: new Set(allFilePaths),
+        allFileList,
+        normalizedFileList: allFileList.map((f) => f.toLowerCase()),
+        resolveCache: new Map(),
+      };
+    }
+
+    const ws: JsResolveContext = {
+      fromFile,
+      language: SupportedLanguages.JavaScript,
+      allFilePaths: cached.allFilePaths,
+      allFileList: cached.allFileList,
+      normalizedFileList: cached.normalizedFileList,
+      resolveCache: cached.resolveCache,
+      tsconfigPaths: null,
+    };
+    return resolveTsTarget(targetRaw, ws);
+  };
+}

gitnexus/src/core/ingestion/languages/javascript/index.ts

@@ -0,0 +1,49 @@
+/**
+ * JavaScript scope-resolution hooks (RFC #909 Ring 3, issue #928).
+ *
+ * Public API barrel. Consumers should import from this file rather
+ * than the individual modules.
+ *
+ * Module layout (each file is a single concern):
+ *
+ *   - `query.ts`          — JS scope query string + lazy parser/query
+ *                           singletons (`getJsParser`, `getJsScopeQuery`)
+ *   - `captures.ts`       — `emitJsScopeCaptures` — runs the JS scope query,
+ *                           synthesizes CJS require() imports and JSDoc-
+ *                           derived type bindings, delegates arity synthesis
+ *                           and destructuring/instanceof passes to shared
+ *                           or TypeScript utilities
+ *   - `interpret.ts`      — `interpretJsImport` / `interpretJsTypeBinding`
+ *                           (delegate to TypeScript interpreters — same
+ *                           capture-marker vocabulary)
+ *   - `simple-hooks.ts`   — `jsBindingScopeFor` (var hoisting),
+ *                           `jsImportOwningScope`, `jsReceiverBinding`
+ *                           (all delegate to TypeScript counterparts)
+ *   - `merge-bindings.ts` — `jsMergeBindings` (LEGB via typescriptMergeBindings)
+ *   - `arity.ts`          — `jsArityCompatibility` (delegates to TS function)
+ *   - `import-target.ts`  — `makeJsResolveImportTarget` (memoized adapter)
+ *   - `scope-resolver.ts` — `javascriptScopeResolver` wiring object
+ *
+ * ## Known limitations
+ *
+ *   1. **JSDoc coverage** — `@param {T} name`, `@returns {T}` / `@return {T}`,
+ *      and `@type {T}` on variable declarations are synthesized. `@typedef`
+ *      is not yet synthesized (tracked in #1646).
+ *   2. **CJS chained destructuring** — `const { X: { Y } } = require(...)`
+ *      (nested destructuring) emits only the outer `X` binding; `Y` is not
+ *      resolved.
+ *   3. **Dynamic require** — `require(computedPath)` is skipped (non-literal
+ *      argument — cannot statically resolve the target).
+ *   4. **`module.exports` / `exports.X`** — CJS export forms are not yet
+ *      modeled as re-exports. The finalize algorithm treats the exporting
+ *      module as a namespace; importers that do `const X = require('./m')`
+ *      bind the module namespace, and member-call resolution walks the
+ *      class graph from there.
+ */
+
+export { emitJsScopeCaptures } from './captures.js';
+export { interpretJsImport, interpretJsTypeBinding } from './interpret.js';
+export { jsMergeBindings } from './merge-bindings.js';
+export { jsArityCompatibility } from './arity.js';
+export { makeJsResolveImportTarget } from './import-target.js';
+export { jsBindingScopeFor, jsImportOwningScope, jsReceiverBinding } from './simple-hooks.js';

gitnexus/src/core/ingestion/languages/javascript/interpret.ts

@@ -0,0 +1,45 @@
+/**
+ * Capture-match → semantic-shape interpreters for JavaScript.
+ *
+ * `interpretJsImport` delegates to `interpretTsImport` for all cases
+ * because `emitJsScopeCaptures` synthesizes the same
+ * `@import.kind/name/alias/source` markers for both ESM and CJS imports.
+ *
+ * The `@import.kind` values emitted for CJS by `captures.ts`:
+ *
+ *   - `'named'`       : `const { X } = require('./m')`     → named import
+ *   - `'named-alias'` : `const { X: Y } = require('./m')` → aliased import
+ *   - `'namespace'`   : `const X = require('./m')`         → namespace import
+ *   - `'side-effect'` : `require('./m')` bare expression   → side-effect
+ *
+ * These match the kinds `interpretTsImport` already handles for ESM
+ * (`import { X }`, `import { X as Y }`, `import * as X`, `import './m'`),
+ * so no new branch is needed here.
+ *
+ * `interpretJsTypeBinding` handles the JS-only `@type-binding.class-field`
+ * tag before delegating to `interpretTsTypeBinding`.  The class-field tag
+ * is emitted by `synthesizeConstructorFieldBindings` and should produce
+ * `source = 'annotation'` — the same strength as an explicit type
+ * annotation. Remapping it to `@type-binding.annotation` achieves this
+ * without adding a JS-specific branch to the shared TS interpreter
+ * (DoD.md §2.2).
+ */
+
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from 'gitnexus-shared';
+import { interpretTsImport, interpretTsTypeBinding } from '../typescript/interpret.js';
+
+export function interpretJsImport(captures: CaptureMatch): ParsedImport | null {
+  return interpretTsImport(captures);
+}
+
+export function interpretJsTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null {
+  // @type-binding.class-field is a JS-only tag emitted by
+  // synthesizeConstructorFieldBindings. Remap it to the standard
+  // @type-binding.annotation tag so interpretTsTypeBinding assigns
+  // source = 'annotation' without a JS-specific branch in shared code.
+  if (captures['@type-binding.class-field'] !== undefined) {
+    const { '@type-binding.class-field': classField, ...rest } = captures;
+    return interpretTsTypeBinding({ ...rest, '@type-binding.annotation': classField });
+  }
+  return interpretTsTypeBinding(captures);
+}

gitnexus/src/core/ingestion/languages/javascript/merge-bindings.ts

@@ -0,0 +1,21 @@
+/**
+ * Binding-merge precedence for JavaScript.
+ *
+ * JavaScript has no TypeScript declaration-merging (no `interface + class`
+ * coexisting in the same scope, no `namespace + class` dual-space declarations).
+ * However, `typescriptMergeBindings` handles these by falling back to
+ * `['value']` for any `NodeLabel` not explicitly mapped to multiple spaces —
+ * which is what every JavaScript declaration produces. The result is pure
+ * LEGB precedence without any cross-space logic, which is exactly what
+ * JavaScript needs.
+ *
+ * Reuse rather than reimplementing to keep the single source of truth for
+ * the tier (local 0 / import-namespace-reexport 1 / wildcard 2) ordering.
+ */
+
+import type { BindingRef } from 'gitnexus-shared';
+import { typescriptMergeBindings } from '../typescript/merge-bindings.js';
+
+export function jsMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[] {
+  return typescriptMergeBindings(bindings);
+}

gitnexus/src/core/ingestion/languages/javascript/query.ts

@@ -0,0 +1,421 @@
+/**
+ * Tree-sitter query for JavaScript scope captures (RFC §5.1, Ring 3).
+ *
+ * Subset of the TypeScript scope query (`languages/typescript/query.ts`)
+ * compiled against `tree-sitter-javascript`. TypeScript-only node types
+ * (`interface_declaration`, `type_alias_declaration`, `enum_declaration`,
+ * `internal_module`, `abstract_class_declaration`, `function_signature`,
+ * `method_signature`, `abstract_method_signature`, `type_annotation`,
+ * `public_field_definition`) are dropped because:
+ *
+ *   1. The JS grammar doesn't define them — the query compiler would
+ *      throw `InvalidNodeType` if they were included.
+ *   2. JavaScript has no static type annotations, so the `@type-binding.*`
+ *      patterns derived from TS annotation nodes don't apply.
+ *
+ * What IS shared with the TypeScript query:
+ *
+ *   - Scope patterns: `program`, `class_declaration`, `(class)` (the JS
+ *     grammar node for class expressions — NOT `class_expression`, which
+ *     does not exist in `tree-sitter-javascript`), `function_declaration`,
+ *     `generator_function_declaration`, `function_expression`,
+ *     `arrow_function`, `method_definition`.
+ *   - Declaration patterns for functions, classes, const/let/var,
+ *     object-property arrows (Zustand, TanStack, etc.), and HOC-wrapped
+ *     variable declarations (forwardRef / memo / useCallback / useMemo).
+ *   - Import patterns: `import_statement`, `export_statement` re-exports,
+ *     and dynamic `import()` (represented as `call_expression(import)` in
+ *     both grammars — the `import` leaf node exists in tree-sitter-javascript
+ *     as well as tree-sitter-typescript).
+ *   - Type-binding patterns that work without static annotations:
+ *     constructor inference (`new User()`), call-result alias
+ *     (`const u = getUser()`), member-access alias (`const a = u.addr`),
+ *     identifier alias, assignment rebind, and for-of element bindings.
+ *     JSDoc-derived type bindings (`@param {User} u`, `@returns {User}`)
+ *     are handled separately in `captures.ts` via comment-node scanning.
+ *   - Reference patterns: free calls, member calls, constructor calls,
+ *     write-access, read-access, and dynamic import.
+ *
+ * CJS `require()` is NOT captured here; it is handled in `captures.ts`
+ * by scanning parent context (destructured vs. namespace) of `call_expression`
+ * nodes whose callee is the identifier `require`.
+ *
+ * Grammar version: `tree-sitter-javascript` pinned in gitnexus/package.json.
+ *
+ * Exposes lazy `Parser` and `Query` singletons so callers don't pay
+ * tree-sitter init cost per file.
+ */
+
+import Parser from 'tree-sitter';
+import JS from 'tree-sitter-javascript';
+
+const JS_GRAMMAR = JS as Parameters<Parser['setLanguage']>[0];
+
+/** True when the file should be parsed with the JSX-extended query. */
+function isJsxFile(filePath: string): boolean {
+  return filePath.endsWith('.jsx');
+}
+
+const JAVASCRIPT_SCOPE_QUERY = `
+;; Scopes — module / class-likes / function-likes
+(program) @scope.module
+
+(class_declaration) @scope.class
+(class) @scope.class
+
+(function_declaration) @scope.function
+(generator_function_declaration) @scope.function
+(function_expression) @scope.function
+(arrow_function) @scope.function
+(method_definition) @scope.function
+
+;; Declarations — classes
+(class_declaration
+  name: (identifier) @declaration.name) @declaration.class
+
+;; Declarations — methods (inside class bodies)
+(method_definition
+  name: (property_identifier) @declaration.name) @declaration.method
+
+;; Declarations — class fields (JS uses field_definition, not public_field_definition)
+(field_definition
+  property: (property_identifier) @declaration.name) @declaration.property
+
+;; Declarations — free functions
+(function_declaration
+  name: (identifier) @declaration.name) @declaration.function
+
+(generator_function_declaration
+  name: (identifier) @declaration.name) @declaration.function
+
+;; Arrow / function-expression assigned to a const/let/var.
+;; Anchor discipline: @declaration.function sits on the INNER arrow or
+;; function_expression, NOT on the lexical_declaration wrapper. This
+;; aligns anchor.range with the @scope.function range so
+;; pass2AttachDeclarations resolves the innermost scope correctly and
+;; resolveCallerGraphId walks up to the right caller anchor.
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (arrow_function) @declaration.function))
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (function_expression) @declaration.function))
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @declaration.name
+      value: (arrow_function) @declaration.function)))
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @declaration.name
+      value: (function_expression) @declaration.function)))
+
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (arrow_function) @declaration.function))
+
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (function_expression) @declaration.function))
+
+;; Object-property arrows / function expressions named by their pair key.
+;; Same anchor discipline as the lexical_declaration block above: the
+;; @declaration.function capture must sit on the INNER arrow/fn-expression.
+(pair
+  key: (property_identifier) @declaration.name
+  value: (arrow_function) @declaration.function)
+
+(pair
+  key: (property_identifier) @declaration.name
+  value: (function_expression) @declaration.function)
+
+(pair
+  key: (string (string_fragment) @declaration.name)
+  value: (arrow_function) @declaration.function)
+
+(pair
+  key: (string (string_fragment) @declaration.name)
+  value: (function_expression) @declaration.function)
+
+;; HOC-wrapped variable declarations: const X = HOC((args) => { ... }).
+;; Covers React.forwardRef, memo, useCallback, useMemo, observer,
+;; debounce, and any user-defined HOC factory.
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (call_expression
+      arguments: (arguments
+        (arrow_function) @declaration.function))))
+
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (call_expression
+      arguments: (arguments
+        (function_expression) @declaration.function))))
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @declaration.name
+      value: (call_expression
+        arguments: (arguments
+          (arrow_function) @declaration.function)))))
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @declaration.name
+      value: (call_expression
+        arguments: (arguments
+          (function_expression) @declaration.function)))))
+
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (call_expression
+      arguments: (arguments
+        (arrow_function) @declaration.function))))
+
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name
+    value: (call_expression
+      arguments: (arguments
+        (function_expression) @declaration.function))))
+
+;; Variable / constant declarations (non-function values).
+(lexical_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name)) @declaration.const
+
+(export_statement
+  declaration: (lexical_declaration
+    (variable_declarator
+      name: (identifier) @declaration.name))) @declaration.const
+
+(variable_declaration
+  (variable_declarator
+    name: (identifier) @declaration.name)) @declaration.variable
+
+;; Imports (ESM) — single anchor per statement; decomposer emits per-specifier markers.
+(import_statement) @import.statement
+
+;; Re-exports with a source clause.
+(export_statement
+  source: (string)) @import.statement
+
+;; Dynamic imports: import('./m') — tree-sitter-javascript represents this
+;; as call_expression with a named import leaf as the function field,
+;; identical to tree-sitter-typescript.
+(call_expression
+  function: (import)) @import.dynamic
+
+;; ── Type bindings (no static annotations in JS; inferred from AST shape) ──
+
+;; Constructor-inferred: const u = new User()
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (new_expression
+    constructor: (identifier) @type-binding.type)) @type-binding.constructor
+
+;; Qualified constructor: const u = new models.User()
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (new_expression
+    constructor: (member_expression) @type-binding.type)) @type-binding.constructor
+
+;; Call-result alias: const u = getUser()
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (call_expression
+    function: (identifier) @type-binding.type)) @type-binding.alias
+
+;; Member-call alias: const u = svc.getUser()
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (call_expression
+    function: (member_expression) @type-binding.type)) @type-binding.alias
+
+;; Await chain: const u = await getUser() / await svc.getUser()
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (await_expression
+    (call_expression
+      function: (identifier) @type-binding.type))) @type-binding.alias
+
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (await_expression
+    (call_expression
+      function: (member_expression) @type-binding.type))) @type-binding.alias
+
+;; Member-access alias: const addr = user.address
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (member_expression) @type-binding.type) @type-binding.member-alias
+
+;; Identifier alias: const alias = user
+(variable_declarator
+  name: (identifier) @type-binding.name
+  value: (identifier) @type-binding.type) @type-binding.alias
+
+;; Assignment rebind: u = new User() / u = getUser()
+(assignment_expression
+  left: (identifier) @type-binding.name
+  right: (new_expression
+    constructor: (identifier) @type-binding.type)) @type-binding.constructor
+
+(assignment_expression
+  left: (identifier) @type-binding.name
+  right: (call_expression
+    function: (identifier) @type-binding.type)) @type-binding.alias
+
+(assignment_expression
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+;; For-of element: for (const u of users) / for (const u of getUsers())
+(for_in_statement
+  left: (identifier) @type-binding.name
+  right: (identifier) @type-binding.type) @type-binding.alias
+
+(for_in_statement
+  left: (identifier) @type-binding.name
+  right: (call_expression
+    function: (identifier) @type-binding.type)) @type-binding.alias
+
+(for_in_statement
+  left: (identifier) @type-binding.name
+  right: (call_expression
+    function: (member_expression) @type-binding.type)) @type-binding.alias
+
+(for_in_statement
+  left: (identifier) @type-binding.name
+  right: (member_expression
+    property: (property_identifier) @type-binding.type)) @type-binding.alias
+
+;; ── References ────────────────────────────────────────────────────────────
+
+;; Free calls: fn(args). The dynamic-import filter runs in captures.ts.
+(call_expression
+  function: (identifier) @reference.name) @reference.call.free
+
+;; Awaited free call: await fn<T>(...) re-associated by tree-sitter.
+(call_expression
+  function: (await_expression
+    (identifier) @reference.name)) @reference.call.free
+
+;; Member calls: obj.method() (includes optional chain).
+(call_expression
+  function: (member_expression
+    object: (_) @reference.receiver
+    property: (property_identifier) @reference.name)) @reference.call.member
+
+;; Awaited member call: await svc.m<T>(...)
+(call_expression
+  function: (await_expression
+    (member_expression
+      object: (_) @reference.receiver
+      property: (property_identifier) @reference.name))) @reference.call.member
+
+;; Constructor calls: new User() / new ns.User()
+(new_expression
+  constructor: (identifier) @reference.name) @reference.call.constructor
+
+(new_expression
+  constructor: (member_expression) @reference.call.constructor.qualified) @reference.call.constructor
+
+;; Write access: obj.field = value
+(assignment_expression
+  left: (member_expression
+    object: (_) @reference.receiver
+    property: (property_identifier) @reference.name)) @reference.write.member
+
+(augmented_assignment_expression
+  left: (member_expression
+    object: (_) @reference.receiver
+    property: (property_identifier) @reference.name)) @reference.write.member
+
+;; Read access: obj.field (in read context; captures.ts filters non-reads).
+(member_expression
+  object: (_) @reference.receiver
+  property: (property_identifier) @reference.name) @reference.read.member
+`;
+
+/** JSX-only suffix — appended when compiling against the JSX grammar for .jsx files. */
+const JSX_QUERY_SUFFIX = `
+;; <Foo />
+((jsx_self_closing_element
+  name: (identifier) @reference.name) @reference.call.free
+  (#match? @reference.name "^[A-Z]"))
+
+;; <Foo> ... </Foo>
+((jsx_opening_element
+  name: (identifier) @reference.name) @reference.call.free
+  (#match? @reference.name "^[A-Z]"))
+
+;; <Foo.Bar />
+(jsx_self_closing_element
+  name: (member_expression
+    object: (_) @reference.receiver
+    property: (property_identifier) @reference.name)) @reference.call.member
+
+(jsx_opening_element
+  name: (member_expression
+    object: (_) @reference.receiver
+    property: (property_identifier) @reference.name)) @reference.call.member
+`;
+
+let _jsParser: Parser | null = null;
+let _jsQuery: Parser.Query | null = null;
+let _jsxParser: Parser | null = null;
+let _jsxQuery: Parser.Query | null = null;
+
+export function getJsParser(filePath?: string): Parser {
+  // JSX files use the same JavaScript grammar in tree-sitter-javascript;
+  // both .js and .jsx parse with the same grammar object. We keep separate
+  // singletons only to mirror the TypeScript pattern and in case a future
+  // version of the grammar diverges.
+  if (filePath !== undefined && isJsxFile(filePath)) {
+    if (_jsxParser === null) {
+      _jsxParser = new Parser();
+      _jsxParser.setLanguage(JS_GRAMMAR);
+    }
+    return _jsxParser;
+  }
+  if (_jsParser === null) {
+    _jsParser = new Parser();
+    _jsParser.setLanguage(JS_GRAMMAR);
+  }
+  return _jsParser;
+}
+
+export function getJsScopeQuery(filePath?: string): Parser.Query {
+  if (filePath !== undefined && isJsxFile(filePath)) {
+    if (_jsxQuery === null) {
+      _jsxQuery = new Parser.Query(JS_GRAMMAR, JAVASCRIPT_SCOPE_QUERY + JSX_QUERY_SUFFIX);
+    }
+    return _jsxQuery;
+  }
+  if (_jsQuery === null) {
+    _jsQuery = new Parser.Query(JS_GRAMMAR, JAVASCRIPT_SCOPE_QUERY);
+  }
+  return _jsQuery;
+}
+
+/** Validate that a cached Tree was produced by the JS grammar. */
+export function jsCachedTreeMatchesGrammar(tree: unknown): boolean {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const lang = (tree as any)?.getLanguage?.();
+  if (lang === undefined || lang === null) return true;
+  return lang === JS_GRAMMAR;
+}

gitnexus/src/core/ingestion/languages/javascript/scope-resolver.ts

@@ -0,0 +1,89 @@
+/**
+ * JavaScript `ScopeResolver` registered in `SCOPE_RESOLVERS` and
+ * consumed by the generic `runScopeResolution` orchestrator
+ * (RFC #909 Ring 3, issue #928).
+ *
+ * Follows the same minimal wiring-only pattern as TypeScript (the third
+ * migration). Per-hook logic lives in sibling modules:
+ *
+ *   - `query.ts`          — JS scope query + parser/query singletons
+ *   - `captures.ts`       — `emitJsScopeCaptures` (JS grammar, CJS, JSDoc)
+ *   - `interpret.ts`      — `interpretJsImport` (delegates to TS interpreter)
+ *   - `simple-hooks.ts`   — `jsBindingScopeFor`, `jsImportOwningScope`,
+ *                           `jsReceiverBinding` (all delegate to TS hooks)
+ *   - `merge-bindings.ts` — `jsMergeBindings` (delegates to TS function)
+ *   - `arity.ts`          — `jsArityCompatibility` (delegates to TS function)
+ *   - `import-target.ts`  — `makeJsResolveImportTarget` (TS resolver, JS extensions)
+ *
+ * See `./index.ts` for the full per-module rationale.
+ *
+ * ## Key differences from TypeScript resolver
+ *
+ *   - `fieldFallbackOnMethodLookup: true` — JavaScript is dynamically typed;
+ *     the field-fallback heuristic is ENABLED (unlike TypeScript, which
+ *     disables it because the type-binding layer is precise).
+ *   - `allowGlobalFreeCallFallback: true` — CJS `require` patterns and
+ *     global helpers (e.g. `process`, `console`) benefit from workspace-
+ *     wide unique-name fallback. TypeScript uses explicit imports.
+ *   - `loadResolutionConfig` is omitted — JavaScript projects don't use
+ *     `tsconfig.json` path aliases in general. `tsconfigPaths: null` is
+ *     threaded through the resolver adapter.
+ *   - `hoistTypeBindingsToModule: true` — JSDoc `@returns {T}` bindings are
+ *     synthesized on the function scope and hoisted, matching TypeScript's
+ *     method return-type hoisting strategy for cross-file chain resolution.
+ */
+
+import type { ParsedFile } from 'gitnexus-shared';
+import { SupportedLanguages } from 'gitnexus-shared';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+import { javascriptProvider } from '../typescript.js';
+import { jsMergeBindings } from './merge-bindings.js';
+import { jsArityCompatibility } from './arity.js';
+import { makeJsResolveImportTarget } from './import-target.js';
+
+const javascriptScopeResolver: ScopeResolver = {
+  language: SupportedLanguages.JavaScript,
+  languageProvider: javascriptProvider,
+  importEdgeReason: 'javascript-scope: import',
+
+  resolveImportTarget: makeJsResolveImportTarget(),
+
+  // JavaScript LEGB — same tier ordering as TypeScript; no declaration-
+  // merging across type/value/namespace spaces.
+  mergeBindings: (existing, incoming) => [...jsMergeBindings([...existing, ...incoming])],
+
+  // Adapter: jsArityCompatibility uses (def, callsite); contract is (callsite, def).
+  arityCompatibility: (callsite, def) => jsArityCompatibility(def, callsite),
+
+  buildMro: (graph, parsedFiles, nodeLookup) =>
+    buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+
+  populateOwners: (parsed: ParsedFile) => populateClassOwnedMembers(parsed),
+
+  // JavaScript `super` keyword: same pattern as TypeScript.
+  isSuperReceiver: (text) => /^super(\s*\(|\s*\.|\s*\[|\s*$)/.test(text.trim()),
+
+  // JavaScript is dynamically typed — enable the field-fallback heuristic
+  // so member-call receivers without type annotations can still resolve
+  // through declared class fields (e.g. JSDoc-typed fields).
+  fieldFallbackOnMethodLookup: true,
+
+  // Return-type propagation (across ESM imports) mirrors TypeScript's
+  // default behavior. JSDoc @returns bindings are hoisted to Module scope
+  // and propagated to importers via the standard mechanism.
+  propagatesReturnTypesAcrossImports: true,
+
+  // JSDoc @returns bindings are synthesized on the function/method node
+  // and hoisted to Module scope by `jsBindingScopeFor` (identical to the
+  // TypeScript `tsBindingScopeFor` `@type-binding.return` branch).
+  hoistTypeBindingsToModule: true,
+
+  // CJS-heavy codebases often have utility functions exported without
+  // explicit imports at the call site. Workspace-wide unique-name fallback
+  // recovers these edges.
+  allowGlobalFreeCallFallback: true,
+};
+
+export { javascriptScopeResolver };

gitnexus/src/core/ingestion/languages/javascript/simple-hooks.ts

@@ -0,0 +1,48 @@
+/**
+ * Simple hooks for the JavaScript scope-resolution provider.
+ *
+ * `jsBindingScopeFor` wraps `tsBindingScopeFor` and adds the JS-only
+ * `@type-binding.class-field` hoisting rule.  The other two hooks
+ * (`jsImportOwningScope`, `jsReceiverBinding`) are identical to their
+ * TypeScript counterparts and are re-exported directly.
+ *
+ * ## Why class-field hoisting lives here (not in `tsBindingScopeFor`)
+ *
+ * `@type-binding.class-field` is emitted exclusively by
+ * `synthesizeConstructorFieldBindings` in `captures.ts`, which is a
+ * JavaScript-only synthesis pass.  TypeScript uses
+ * `@type-binding.parameter-property` for constructor parameter
+ * properties instead.  Keeping the JS-only rule in the JS hook file
+ * prevents language-specific logic from leaking into shared TypeScript
+ * infrastructure (DoD.md §2.2).
+ */
+
+import type { CaptureMatch, Scope, ScopeId, ScopeTree } from 'gitnexus-shared';
+import { tsBindingScopeFor, walkToScope } from '../typescript/simple-hooks.js';
+
+export {
+  tsImportOwningScope as jsImportOwningScope,
+  tsReceiverBinding as jsReceiverBinding,
+} from '../typescript/simple-hooks.js';
+
+/**
+ * Like `tsBindingScopeFor` but additionally hoists
+ * `@type-binding.class-field` captures to the enclosing Class scope.
+ *
+ * `@type-binding.class-field` is anchored inside the constructor body
+ * (by `synthesizeConstructorFieldBindings`) so that `walkToScope` can
+ * walk up from the Function (constructor) scope to the Class scope.
+ * This puts `User.address → Address` in the class's typeBindings so
+ * compound-receiver resolution finds it when resolving
+ * `user.address.save()`.
+ */
+export function jsBindingScopeFor(
+  decl: CaptureMatch,
+  innermost: Scope,
+  tree: ScopeTree,
+): ScopeId | null {
+  if (decl['@type-binding.class-field'] !== undefined) {
+    return walkToScope(innermost, tree, 'Class');
+  }
+  return tsBindingScopeFor(decl, innermost, tree);
+}

gitnexus/src/core/ingestion/languages/kotlin.ts

@@ -29,6 +29,16 @@ 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';
+import {
+  emitKotlinScopeCaptures,
+  interpretKotlinImport,
+  interpretKotlinTypeBinding,
+  kotlinArityCompatibility,
+  kotlinBindingScopeFor,
+  kotlinImportOwningScope,
+  kotlinMergeBindings,
+  kotlinReceiverBinding,
+} from './kotlin/index.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.
@@ -166,4 +176,14 @@ export const kotlinProvider = defineLanguage({
     if (isKotlinClassMethod(functionNode)) return 'Method';
     return defaultLabel;
   },
+
+  // ── RFC #909 Ring 3: scope-based resolution hooks ──
+  emitScopeCaptures: emitKotlinScopeCaptures,
+  interpretImport: interpretKotlinImport,
+  interpretTypeBinding: interpretKotlinTypeBinding,
+  bindingScopeFor: kotlinBindingScopeFor,
+  importOwningScope: kotlinImportOwningScope,
+  mergeBindings: (_scope, bindings) => kotlinMergeBindings(bindings),
+  receiverBinding: kotlinReceiverBinding,
+  arityCompatibility: kotlinArityCompatibility,
 });

gitnexus/src/core/ingestion/languages/kotlin/arity-metadata.ts

@@ -0,0 +1,26 @@
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+import { kotlinMethodConfig } from '../../method-extractors/configs/jvm.js';
+
+export interface KotlinArityMetadata {
+  readonly parameterCount: number | undefined;
+  readonly requiredParameterCount: number | undefined;
+  readonly parameterTypes: readonly string[] | undefined;
+}
+
+export function computeKotlinArityMetadata(fnNode: SyntaxNode): KotlinArityMetadata {
+  const params = kotlinMethodConfig.extractParameters?.(fnNode) ?? [];
+  let hasVararg = false;
+  const parameterTypes: string[] = [];
+  for (const param of params) {
+    if (param.isVariadic) hasVararg = true;
+    if (param.type !== null) parameterTypes.push(param.type);
+  }
+  if (hasVararg) parameterTypes.push('vararg');
+
+  const required = params.filter((p) => !p.isOptional && !p.isVariadic).length;
+  return {
+    parameterCount: hasVararg ? undefined : params.length,
+    requiredParameterCount: required,
+    parameterTypes: parameterTypes.length > 0 ? parameterTypes : undefined,
+  };
+}

gitnexus/src/core/ingestion/languages/kotlin/arity.ts

@@ -0,0 +1,18 @@
+import type { Callsite, SymbolDefinition } from 'gitnexus-shared';
+
+export function kotlinArityCompatibility(
+  def: SymbolDefinition,
+  callsite: Callsite,
+): 'compatible' | 'unknown' | 'incompatible' {
+  const min = def.requiredParameterCount;
+  const max = def.parameterCount;
+  if (min === undefined && max === undefined) return 'unknown';
+
+  const argCount = callsite.arity;
+  if (!Number.isFinite(argCount) || argCount < 0) return 'unknown';
+
+  const hasVararg = def.parameterTypes?.some((t) => t === 'vararg') ?? false;
+  if (min !== undefined && argCount < min) return 'incompatible';
+  if (max !== undefined && argCount > max && !hasVararg) return 'incompatible';
+  return 'compatible';
+}

gitnexus/src/core/ingestion/languages/kotlin/cache-stats.ts

@@ -0,0 +1,19 @@
+let hits = 0;
+let misses = 0;
+
+export function recordKotlinCacheHit(): void {
+  hits += 1;
+}
+
+export function recordKotlinCacheMiss(): void {
+  misses += 1;
+}
+
+export function getKotlinCaptureCacheStats(): { readonly hits: number; readonly misses: number } {
+  return { hits, misses };
+}
+
+export function resetKotlinCaptureCacheStats(): void {
+  hits = 0;
+  misses = 0;
+}

gitnexus/src/core/ingestion/languages/kotlin/captures.ts

@@ -0,0 +1,484 @@
+import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import {
+  findNodeAtRange,
+  nodeToCapture,
+  syntheticCapture,
+  type SyntaxNode,
+} from '../../utils/ast-helpers.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+import { computeKotlinArityMetadata } from './arity-metadata.js';
+import { splitKotlinImportHeader } from './import-decomposer.js';
+import { recordKotlinCacheHit, recordKotlinCacheMiss } from './cache-stats.js';
+import { normalizeKotlinType } from './interpret.js';
+import { synthesizeKotlinReceiverBinding } from './receiver-binding.js';
+import { getKotlinParser, getKotlinScopeQuery } from './query.js';
+
+const FUNCTION_DECL_TAGS = ['@declaration.function'] as const;
+
+export function emitKotlinScopeCaptures(
+  sourceText: string,
+  _filePath: string,
+  cachedTree?: unknown,
+): readonly CaptureMatch[] {
+  let tree = cachedTree as ReturnType<ReturnType<typeof getKotlinParser>['parse']> | undefined;
+  if (tree === undefined) {
+    tree = parseSourceSafe(getKotlinParser(), sourceText, undefined, {
+      bufferSize: getTreeSitterBufferSize(sourceText),
+    });
+    recordKotlinCacheMiss();
+  } else {
+    recordKotlinCacheHit();
+  }
+
+  const out: CaptureMatch[] = [];
+  const returnTypes = collectKotlinReturnTypeTexts(tree.rootNode);
+  out.push(...synthesizeKotlinLocalAssignmentBindings(tree.rootNode, returnTypes));
+  out.push(...synthesizeKotlinLoopBindings(tree.rootNode, returnTypes));
+
+  for (const match of getKotlinScopeQuery().matches(tree.rootNode)) {
+    const grouped: Record<string, Capture> = {};
+    for (const capture of match.captures) {
+      const tag = '@' + capture.name;
+      grouped[tag] = nodeToCapture(tag, capture.node);
+    }
+    if (Object.keys(grouped).length === 0) continue;
+
+    if (grouped['@import.statement'] !== undefined) {
+      const importNode = findNodeAtRange(
+        tree.rootNode,
+        grouped['@import.statement']!.range,
+        'import_header',
+      );
+      if (importNode !== null) {
+        const decomposed = splitKotlinImportHeader(importNode);
+        if (decomposed !== null) {
+          out.push(decomposed);
+          continue;
+        }
+      }
+    }
+
+    if (
+      grouped['@reference.call.free'] !== undefined &&
+      grouped['@reference.receiver'] !== undefined
+    ) {
+      continue;
+    }
+
+    if (grouped['@reference.read.member'] !== undefined) {
+      const anchor = grouped['@reference.read.member']!;
+      const navNode = findNodeAtRange(tree.rootNode, anchor.range, 'navigation_expression');
+      if (navNode === null || !shouldEmitReadMember(navNode)) continue;
+    }
+
+    if (grouped['@scope.function'] !== undefined) {
+      out.push(grouped);
+      const fnNode = findNodeAtRange(
+        tree.rootNode,
+        grouped['@scope.function']!.range,
+        'function_declaration',
+      );
+      if (fnNode !== null) {
+        out.push(...synthesizeKotlinReceiverBinding(fnNode));
+      }
+      continue;
+    }
+
+    const declTag = FUNCTION_DECL_TAGS.find((tag) => grouped[tag] !== undefined);
+    if (declTag !== undefined) {
+      const fnNode = findNodeAtRange(
+        tree.rootNode,
+        grouped[declTag]!.range,
+        'function_declaration',
+      );
+      if (fnNode !== null) {
+        const arity = computeKotlinArityMetadata(fnNode);
+        if (arity.parameterCount !== undefined) {
+          grouped['@declaration.parameter-count'] = syntheticCapture(
+            '@declaration.parameter-count',
+            fnNode,
+            String(arity.parameterCount),
+          );
+        }
+        if (arity.requiredParameterCount !== undefined) {
+          grouped['@declaration.required-parameter-count'] = syntheticCapture(
+            '@declaration.required-parameter-count',
+            fnNode,
+            String(arity.requiredParameterCount),
+          );
+        }
+        if (arity.parameterTypes !== undefined) {
+          grouped['@declaration.parameter-types'] = syntheticCapture(
+            '@declaration.parameter-types',
+            fnNode,
+            JSON.stringify(arity.parameterTypes),
+          );
+        }
+      }
+    }
+
+    const callTag = (
+      ['@reference.call.free', '@reference.call.member', '@reference.call.constructor'] as const
+    ).find((tag) => grouped[tag] !== undefined);
+    if (callTag !== undefined && grouped['@reference.arity'] === undefined) {
+      const callNode = findNodeAtRange(tree.rootNode, grouped[callTag]!.range, 'call_expression');
+      if (callNode !== null) {
+        const args = callArguments(callNode);
+        grouped['@reference.arity'] = syntheticCapture(
+          '@reference.arity',
+          callNode,
+          String(args.length),
+        );
+        grouped['@reference.parameter-types'] = syntheticCapture(
+          '@reference.parameter-types',
+          callNode,
+          JSON.stringify(args.map(inferArgType)),
+        );
+      }
+    }
+
+    out.push(grouped);
+
+    const extensionFallback = extensionFreeCallFallback(grouped, tree.rootNode);
+    if (extensionFallback !== null) out.push(extensionFallback);
+  }
+
+  return out;
+}
+
+function synthesizeKotlinLoopBindings(
+  rootNode: SyntaxNode,
+  returnTypes: ReadonlyMap<string, string>,
+): CaptureMatch[] {
+  const out: CaptureMatch[] = [];
+  for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+    const localTypes = collectKotlinLocalTypeTexts(fnNode, returnTypes);
+    for (const forNode of descendantsOfType(fnNode, 'for_statement')) {
+      const variable = forNode.namedChildren.find((child) => child.type === 'variable_declaration');
+      const name = variable?.namedChildren.find((child) => child.type === 'simple_identifier');
+      if (variable === undefined || name === undefined) continue;
+
+      const explicitType = variable.namedChildren.find((child) => isKotlinTypeNode(child));
+      const iterable = forNode.namedChildren.find(
+        (child) => child.id !== variable.id && child.type !== 'control_structure_body',
+      );
+      const rawType =
+        explicitType?.text ??
+        (iterable === undefined
+          ? null
+          : inferKotlinIterableElementType(iterable, localTypes, returnTypes));
+      if (rawType === null || rawType.trim() === '') continue;
+
+      const anchor =
+        forNode.namedChildren.find((child) => child.type === 'control_structure_body') ?? forNode;
+      out.push({
+        '@type-binding.annotation': nodeToCapture('@type-binding.annotation', anchor),
+        '@type-binding.name': syntheticCapture('@type-binding.name', name, name.text),
+        '@type-binding.type': syntheticCapture(
+          '@type-binding.type',
+          explicitType ?? iterable ?? name,
+          normalizeKotlinType(rawType),
+        ),
+      });
+    }
+  }
+  return out;
+}
+
+function synthesizeKotlinLocalAssignmentBindings(
+  rootNode: SyntaxNode,
+  returnTypes: ReadonlyMap<string, string>,
+): CaptureMatch[] {
+  const out: CaptureMatch[] = [];
+  for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+    const localTypes = new Map<string, string>();
+    for (const prop of descendantsOfType(fnNode, 'property_declaration')) {
+      const inferred = inferKotlinPropertyType(prop, localTypes, returnTypes);
+      if (inferred === null) continue;
+      localTypes.set(inferred.name.text, inferred.rawType);
+      if (inferred.synthetic) {
+        out.push({
+          '@type-binding.annotation': nodeToCapture('@type-binding.annotation', prop),
+          '@type-binding.name': syntheticCapture(
+            '@type-binding.name',
+            inferred.name,
+            inferred.name.text,
+          ),
+          '@type-binding.type': syntheticCapture(
+            '@type-binding.type',
+            inferred.source,
+            normalizeKotlinType(inferred.rawType),
+          ),
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function collectKotlinLocalTypeTexts(
+  fnNode: SyntaxNode,
+  returnTypes: ReadonlyMap<string, string>,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const node of descendants(fnNode)) {
+    if (node.type === 'parameter') {
+      const name = descendantsOfType(node, 'simple_identifier')[0];
+      const type = node.namedChildren.find((child) => isKotlinTypeNode(child));
+      if (name !== undefined && type !== undefined) out.set(name.text, type.text);
+      continue;
+    }
+
+    if (node.type === 'property_declaration') {
+      const inferred = inferKotlinPropertyType(node, out, returnTypes);
+      if (inferred !== null) out.set(inferred.name.text, inferred.rawType);
+    }
+  }
+  return out;
+}
+
+function collectKotlinReturnTypeTexts(rootNode: SyntaxNode): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+    const name = fnNode.namedChildren.find((child) => child.type === 'simple_identifier');
+    const paramsIndex = fnNode.namedChildren.findIndex(
+      (child) => child.type === 'function_value_parameters',
+    );
+    const type =
+      paramsIndex < 0
+        ? undefined
+        : fnNode.namedChildren.slice(paramsIndex + 1).find((child) => isKotlinTypeNode(child));
+    if (name !== undefined && type !== undefined) out.set(name.text, type.text);
+  }
+  return out;
+}
+
+function inferKotlinPropertyType(
+  prop: SyntaxNode,
+  localTypes: ReadonlyMap<string, string>,
+  returnTypes: ReadonlyMap<string, string>,
+): { name: SyntaxNode; rawType: string; source: SyntaxNode; synthetic: boolean } | null {
+  const variable = prop.namedChildren.find((child) => child.type === 'variable_declaration');
+  const name = variable?.namedChildren.find((child) => child.type === 'simple_identifier');
+  if (variable === undefined || name === undefined) return null;
+
+  const explicitType = variable.namedChildren.find((child) => isKotlinTypeNode(child));
+  if (explicitType !== undefined) {
+    return { name, rawType: explicitType.text, source: explicitType, synthetic: false };
+  }
+
+  const value = prop.namedChildren.find(
+    (child) => child.id !== variable.id && child.type !== 'binding_pattern_kind',
+  );
+  if (value?.type === 'simple_identifier') {
+    const rawType = localTypes.get(value.text);
+    return rawType === undefined ? null : { name, rawType, source: value, synthetic: true };
+  }
+
+  if (value?.type === 'call_expression') {
+    const callee = value.namedChildren.find((child) => child.type === 'simple_identifier');
+    if (callee === undefined) return null;
+    const rawType =
+      returnTypes.get(callee.text) ?? (isUppercaseName(callee.text) ? callee.text : null);
+    if (rawType === null) return null;
+    return { name, rawType, source: callee, synthetic: true };
+  }
+
+  return null;
+}
+
+function inferKotlinIterableElementType(
+  iterable: SyntaxNode,
+  localTypes: ReadonlyMap<string, string>,
+  returnTypes: ReadonlyMap<string, string>,
+): string | null {
+  if (iterable.type === 'simple_identifier') {
+    const raw = localTypes.get(iterable.text);
+    return raw === undefined ? null : kotlinContainerElementType(raw, 'values');
+  }
+
+  if (iterable.type === 'navigation_expression') {
+    const receiver = iterable.namedChildren[0];
+    const member = iterable.namedChildren
+      .find((child) => child.type === 'navigation_suffix')
+      ?.namedChildren.find((child) => child.type === 'simple_identifier')?.text;
+    if (receiver?.type !== 'simple_identifier') return null;
+    const raw = localTypes.get(receiver.text);
+    return raw === undefined ? null : kotlinContainerElementType(raw, member ?? 'values');
+  }
+
+  if (iterable.type === 'call_expression') {
+    const callee = iterable.namedChildren.find((child) => child.type === 'simple_identifier');
+    if (callee === undefined) return null;
+    const raw = returnTypes.get(callee.text);
+    return raw === undefined ? null : kotlinContainerElementType(raw, 'values');
+  }
+
+  return null;
+}
+
+function isUppercaseName(text: string): boolean {
+  return /^[A-Z]/.test(text);
+}
+
+function kotlinContainerElementType(rawType: string, member: string): string | null {
+  const parsed = parseKotlinGeneric(rawType);
+  if (parsed === null) return normalizeKotlinType(rawType);
+
+  const base = parsed.base.split('.').pop() ?? parsed.base;
+  if (isKotlinMapType(base)) {
+    if (member === 'keys') return parsed.args[0] ?? null;
+    return parsed.args[1] ?? null;
+  }
+  if (isKotlinIterableType(base)) return parsed.args[0] ?? null;
+  return normalizeKotlinType(rawType);
+}
+
+function parseKotlinGeneric(text: string): { base: string; args: string[] } | null {
+  const trimmed = text.trim().replace(/\?$/, '');
+  const open = trimmed.indexOf('<');
+  const close = trimmed.lastIndexOf('>');
+  if (open < 0 || close < open) return null;
+  return {
+    base: trimmed.slice(0, open).trim(),
+    args: splitTopLevelKotlinArgs(trimmed.slice(open + 1, close)),
+  };
+}
+
+function splitTopLevelKotlinArgs(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '<') depth++;
+    else if (ch === '>') depth--;
+    else if (ch === ',' && depth === 0) {
+      out.push(text.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  out.push(text.slice(start).trim());
+  return out.filter((arg) => arg.length > 0);
+}
+
+function isKotlinMapType(base: string): boolean {
+  return ['Map', 'MutableMap', 'HashMap', 'LinkedHashMap'].includes(base);
+}
+
+function isKotlinIterableType(base: string): boolean {
+  return [
+    'List',
+    'MutableList',
+    'ArrayList',
+    'Set',
+    'MutableSet',
+    'Collection',
+    'Iterable',
+    'Sequence',
+    'Array',
+  ].includes(base);
+}
+
+function isKotlinTypeNode(node: SyntaxNode): boolean {
+  return (
+    node.type === 'user_type' || node.type === 'nullable_type' || node.type === 'function_type'
+  );
+}
+
+function descendantsOfType(node: SyntaxNode, type: string): SyntaxNode[] {
+  return descendants(node).filter((child) => child.type === type);
+}
+
+function descendants(node: SyntaxNode): SyntaxNode[] {
+  const out: SyntaxNode[] = [];
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child === null) continue;
+    out.push(child, ...descendants(child));
+  }
+  return out;
+}
+
+function shouldEmitReadMember(navNode: SyntaxNode): boolean {
+  const parent = navNode.parent;
+  if (parent === null) return true;
+  if (parent.type === 'call_expression') return false;
+  if (parent.type === 'directly_assignable_expression') return false;
+  return true;
+}
+
+function callArguments(callNode: SyntaxNode): SyntaxNode[] {
+  const suffix = callNode.namedChildren.find((child) => child.type === 'call_suffix');
+  if (suffix === undefined) return [];
+
+  const valueArgs = suffix?.namedChildren.find((child) => child.type === 'value_arguments');
+  const args = valueArgs?.namedChildren.filter((child) => child.type === 'value_argument') ?? [];
+  const trailingLambdas = suffix.namedChildren.filter((child) => child.type === 'annotated_lambda');
+  return [...args, ...trailingLambdas];
+}
+
+function inferArgType(argNode: SyntaxNode): string {
+  const value = argNode.namedChild(0) ?? argNode;
+  switch (value.type) {
+    case 'integer_literal':
+    case 'long_literal':
+      return 'Int';
+    case 'real_literal':
+      return 'Double';
+    case 'string_literal':
+    case 'line_string_literal':
+    case 'multi_line_string_literal':
+      return 'String';
+    case 'character_literal':
+      return 'Char';
+    case 'boolean_literal':
+      return 'Boolean';
+    case 'call_expression': {
+      const first = value.namedChild(0);
+      return first?.type === 'simple_identifier' ? first.text : '';
+    }
+    default:
+      return '';
+  }
+}
+
+function extensionFreeCallFallback(
+  grouped: Record<string, Capture>,
+  rootNode: SyntaxNode,
+): CaptureMatch | null {
+  const member = grouped['@reference.call.member'];
+  const receiver = grouped['@reference.receiver'];
+  const name = grouped['@reference.name'];
+  if (member === undefined || receiver === undefined || name === undefined) return null;
+
+  const callNode = findNodeAtRange(rootNode, member.range, 'call_expression');
+  if (callNode === null) return null;
+  const receiverNode = findNodeAtRange(rootNode, receiver.range);
+  if (receiverNode === null || !isLiteralReceiver(receiverNode)) return null;
+
+  const out: Record<string, Capture> = {
+    '@reference.call.free': syntheticCapture('@reference.call.free', callNode, callNode.text),
+    '@reference.name': syntheticCapture('@reference.name', callNode, name.text),
+  };
+  if (grouped['@reference.arity'] !== undefined)
+    out['@reference.arity'] = grouped['@reference.arity'];
+  if (grouped['@reference.parameter-types'] !== undefined) {
+    out['@reference.parameter-types'] = grouped['@reference.parameter-types'];
+  }
+  return out;
+}
+
+function isLiteralReceiver(node: SyntaxNode): boolean {
+  return [
+    'integer_literal',
+    'long_literal',
+    'real_literal',
+    'string_literal',
+    'line_string_literal',
+    'multi_line_string_literal',
+    'character_literal',
+    'boolean_literal',
+  ].includes(node.type);
+}

gitnexus/src/core/ingestion/languages/kotlin/import-decomposer.ts

@@ -0,0 +1,49 @@
+import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js';
+
+type KotlinImportKind = 'named' | 'alias' | 'wildcard';
+
+interface KotlinImportSpec {
+  readonly kind: KotlinImportKind;
+  readonly source: string;
+  readonly name: string;
+  readonly alias?: string;
+  readonly atNode: SyntaxNode;
+}
+
+export function splitKotlinImportHeader(importNode: SyntaxNode): CaptureMatch | null {
+  if (importNode.type !== 'import_header') return null;
+  const spec = parseKotlinImport(importNode);
+  if (spec === null) return null;
+
+  const out: Record<string, Capture> = {
+    '@import.statement': nodeToCapture('@import.statement', importNode),
+    '@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
+    '@import.source': syntheticCapture('@import.source', spec.atNode, spec.source),
+    '@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
+  };
+  if (spec.alias !== undefined) {
+    out['@import.alias'] = syntheticCapture('@import.alias', spec.atNode, spec.alias);
+  }
+  return out;
+}
+
+function parseKotlinImport(node: SyntaxNode): KotlinImportSpec | null {
+  const identifier = node.namedChildren.find((child) => child.type === 'identifier');
+  if (identifier === undefined) return null;
+  const source = identifier.text.trim();
+  if (source.length === 0) return null;
+
+  const hasWildcard = node.namedChildren.some((child) => child.type === 'wildcard_import');
+  if (hasWildcard) {
+    return { kind: 'wildcard', source, name: '*', atNode: node };
+  }
+
+  const aliasNode = node.namedChildren.find((child) => child.type === 'import_alias');
+  const alias = aliasNode?.namedChildren.find((child) => child.type === 'type_identifier')?.text;
+  const importedName = source.split('.').pop() ?? source;
+  if (alias !== undefined && alias.length > 0) {
+    return { kind: 'alias', source, name: importedName, alias, atNode: node };
+  }
+  return { kind: 'named', source, name: importedName, atNode: node };
+}

gitnexus/src/core/ingestion/languages/kotlin/import-target.ts

@@ -0,0 +1,76 @@
+import type { ParsedImport, WorkspaceIndex } from 'gitnexus-shared';
+
+export interface KotlinResolveContext {
+  readonly fromFile: string;
+  readonly allFilePaths: ReadonlySet<string>;
+}
+
+export function resolveKotlinImportTarget(
+  parsedImport: ParsedImport,
+  workspaceIndex: WorkspaceIndex,
+): string | null {
+  const ctx = workspaceIndex as KotlinResolveContext | undefined;
+  if (
+    ctx === undefined ||
+    typeof (ctx as { fromFile?: unknown }).fromFile !== 'string' ||
+    !((ctx as { allFilePaths?: unknown }).allFilePaths instanceof Set)
+  ) {
+    return null;
+  }
+  if (parsedImport.kind === 'dynamic-unresolved') return null;
+  if (parsedImport.targetRaw === null || parsedImport.targetRaw === '') return null;
+
+  const target = parsedImport.targetRaw.endsWith('.*')
+    ? parsedImport.targetRaw.slice(0, -2)
+    : parsedImport.targetRaw;
+  const pathLike = target.replace(/\./g, '/');
+
+  return (
+    findKotlinFile(ctx.allFilePaths, pathLike) ??
+    findKotlinFile(ctx.allFilePaths, pathLike.split('/').slice(0, -1).join('/')) ??
+    findByProgressivePrefixStrip(ctx.allFilePaths, pathLike)
+  );
+}
+
+function findKotlinFile(allFilePaths: ReadonlySet<string>, pathLike: string): string | null {
+  if (pathLike === '') return null;
+  const extensions = ['.kt', '.kts'];
+  const suffix = `/${pathLike}`;
+  const dirPrefix = `${pathLike}/`;
+  const suffixDirPrefix = `/${dirPrefix}`;
+
+  let suffixFile: string | null = null;
+  let directoryChild: string | null = null;
+
+  for (const raw of allFilePaths) {
+    const file = raw.replace(/\\/g, '/');
+    if (!extensions.some((ext) => file.endsWith(ext))) continue;
+    for (const ext of extensions) {
+      if (file === `${pathLike}${ext}`) return raw;
+      if (suffixFile === null && file.endsWith(`${suffix}${ext}`)) suffixFile = raw;
+    }
+    if (directoryChild === null) {
+      const atRoot = file.startsWith(dirPrefix);
+      const atNested = file.includes(suffixDirPrefix);
+      if (atRoot || atNested) {
+        const idx = atRoot ? 0 : file.indexOf(suffixDirPrefix) + 1;
+        const after = file.slice(idx + dirPrefix.length);
+        if (after.length > 0 && !after.includes('/')) directoryChild = raw;
+      }
+    }
+  }
+
+  return suffixFile ?? directoryChild;
+}
+
+function findByProgressivePrefixStrip(
+  allFilePaths: ReadonlySet<string>,
+  pathLike: string,
+): string | null {
+  const segments = pathLike.split('/').filter(Boolean);
+  for (let skip = 1; skip < segments.length; skip++) {
+    const found = findKotlinFile(allFilePaths, segments.slice(skip).join('/'));
+    if (found !== null) return found;
+  }
+  return null;
+}

gitnexus/src/core/ingestion/languages/kotlin/index.ts

@@ -0,0 +1,12 @@
+export { emitKotlinScopeCaptures } from './captures.js';
+export { getKotlinCaptureCacheStats, resetKotlinCaptureCacheStats } from './cache-stats.js';
+export { interpretKotlinImport, interpretKotlinTypeBinding } from './interpret.js';
+export { kotlinArityCompatibility } from './arity.js';
+export { resolveKotlinImportTarget, type KotlinResolveContext } from './import-target.js';
+export { kotlinMergeBindings } from './merge-bindings.js';
+export { populateKotlinOwners } from './owners.js';
+export {
+  kotlinBindingScopeFor,
+  kotlinImportOwningScope,
+  kotlinReceiverBinding,
+} from './simple-hooks.js';

gitnexus/src/core/ingestion/languages/kotlin/interpret.ts

@@ -0,0 +1,71 @@
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared';
+
+export function interpretKotlinImport(captures: CaptureMatch): ParsedImport | null {
+  const kind = captures['@import.kind']?.text;
+  const source = captures['@import.source']?.text;
+  const name = captures['@import.name']?.text;
+  if (kind === undefined || source === undefined) return null;
+
+  switch (kind) {
+    case 'named':
+      return {
+        kind: 'named',
+        localName: name ?? source.split('.').pop() ?? source,
+        importedName: name ?? source.split('.').pop() ?? source,
+        targetRaw: source,
+      };
+    case 'alias': {
+      const alias = captures['@import.alias']?.text;
+      if (alias === undefined || name === undefined) return null;
+      return {
+        kind: 'alias',
+        localName: alias,
+        importedName: name,
+        alias,
+        targetRaw: source,
+      };
+    }
+    case 'wildcard':
+      return { kind: 'wildcard', targetRaw: source.endsWith('.*') ? source : `${source}.*` };
+    default:
+      return null;
+  }
+}
+
+export function interpretKotlinTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null {
+  const nameCap = captures['@type-binding.name'];
+  const typeCap = captures['@type-binding.type'];
+  if (nameCap === undefined || typeCap === undefined) return null;
+
+  let source: TypeRef['source'] = 'annotation';
+  if (captures['@type-binding.self'] !== undefined) source = 'self';
+  else if (captures['@type-binding.parameter'] !== undefined) source = 'parameter-annotation';
+  else if (captures['@type-binding.return'] !== undefined) source = 'return-annotation';
+  else if (captures['@type-binding.constructor'] !== undefined) source = 'constructor-inferred';
+
+  return {
+    boundName: nameCap.text,
+    rawTypeName: normalizeKotlinType(typeCap.text),
+    source,
+  };
+}
+
+export function normalizeKotlinType(text: string): string {
+  let out = text.trim();
+  while (out.endsWith('?')) out = out.slice(0, -1).trim();
+  const lastDot = out.lastIndexOf('.');
+  if (lastDot >= 0) out = out.slice(lastDot + 1);
+
+  const collection = out.match(
+    /^(?:List|MutableList|ArrayList|Set|MutableSet|Collection|Iterable|Sequence|Array)<([^,<>]+)>$/,
+  );
+  if (collection !== null) return normalizeKotlinType(collection[1]!);
+
+  const map = out.match(/^(?:Map|MutableMap|HashMap|LinkedHashMap)<[^,<>]+,\s*([^,<>]+)>$/);
+  if (map !== null) return normalizeKotlinType(map[1]!);
+
+  const erased = out.match(/^([A-Za-z_][A-Za-z0-9_]*)<.+>$/s);
+  if (erased !== null) return erased[1]!;
+
+  return out;
+}

gitnexus/src/core/ingestion/languages/kotlin/merge-bindings.ts

@@ -0,0 +1,26 @@
+import type { BindingRef } from 'gitnexus-shared';
+
+function tierOf(binding: BindingRef): number {
+  switch (binding.origin) {
+    case 'local':
+      return 0;
+    case 'import':
+    case 'namespace':
+    case 'reexport':
+      return 1;
+    case 'wildcard':
+      return 2;
+    default:
+      return 3;
+  }
+}
+
+export function kotlinMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[] {
+  if (bindings.length === 0) return bindings;
+  const best = Math.min(...bindings.map(tierOf));
+  const seen = new Map<string, BindingRef>();
+  for (const binding of bindings) {
+    if (tierOf(binding) === best) seen.set(binding.def.nodeId, binding);
+  }
+  return [...seen.values()];
+}

gitnexus/src/core/ingestion/languages/kotlin/owners.ts

@@ -0,0 +1,50 @@
+import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared';
+import { isClassLike, populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js';
+
+export function populateKotlinOwners(parsed: ParsedFile): void {
+  populateClassOwnedMembers(parsed);
+  populateCompanionMembersOnEnclosingClass(parsed);
+}
+
+function populateCompanionMembersOnEnclosingClass(parsed: ParsedFile): void {
+  const scopesById = new Map<ScopeId, ParsedFile['scopes'][number]>();
+  for (const scope of parsed.scopes) scopesById.set(scope.id, scope);
+
+  for (const scope of parsed.scopes) {
+    if (scope.kind !== 'Function' || scope.parent === null) continue;
+    const parent = scopesById.get(scope.parent);
+    if (parent === undefined || parent.kind !== 'Class') continue;
+    if (parent.ownedDefs.some((def) => isClassLike(def.type))) continue;
+
+    const enclosing = findEnclosingClassWithDef(parent.parent, scopesById);
+    if (enclosing === undefined) continue;
+    for (const def of scope.ownedDefs) {
+      if (def.ownerId !== undefined) continue;
+      (def as { ownerId?: string }).ownerId = enclosing.nodeId;
+      qualify(def, enclosing);
+    }
+  }
+}
+
+function findEnclosingClassWithDef(
+  start: ScopeId | null,
+  scopesById: ReadonlyMap<ScopeId, ParsedFile['scopes'][number]>,
+): SymbolDefinition | undefined {
+  let current = start;
+  while (current !== null) {
+    const scope = scopesById.get(current);
+    if (scope === undefined) return undefined;
+    if (scope.kind === 'Class') {
+      const classDef = scope.ownedDefs.find((def) => isClassLike(def.type));
+      if (classDef !== undefined) return classDef;
+    }
+    current = scope.parent;
+  }
+  return undefined;
+}
+
+function qualify(def: SymbolDefinition, owner: SymbolDefinition): void {
+  if (def.qualifiedName === undefined || def.qualifiedName.includes('.')) return;
+  if (owner.qualifiedName === undefined || owner.qualifiedName.length === 0) return;
+  (def as { qualifiedName: string }).qualifiedName = `${owner.qualifiedName}.${def.qualifiedName}`;
+}

gitnexus/src/core/ingestion/languages/kotlin/query.ts

@@ -0,0 +1,116 @@
+import Parser from 'tree-sitter';
+import Kotlin from 'tree-sitter-kotlin';
+
+const KOTLIN_SCOPE_QUERY = `
+;; Scopes
+(source_file) @scope.module
+(class_declaration) @scope.class
+(object_declaration) @scope.class
+(companion_object) @scope.class
+(function_declaration) @scope.function
+
+;; Declarations — types
+(class_declaration
+  "interface"
+  (type_identifier) @declaration.name) @declaration.interface
+
+(class_declaration
+  "class"
+  (type_identifier) @declaration.name) @declaration.class
+
+(object_declaration
+  (type_identifier) @declaration.name) @declaration.class
+
+(companion_object
+  (type_identifier) @declaration.name) @declaration.class
+
+(type_alias
+  (type_identifier) @declaration.name) @declaration.type_alias
+
+;; Declarations — functions / methods / properties
+(function_declaration
+  (simple_identifier) @declaration.name) @declaration.function
+
+(property_declaration
+  (variable_declaration
+    (simple_identifier) @declaration.name)) @declaration.property
+
+(class_parameter
+  (binding_pattern_kind)
+  (simple_identifier) @declaration.name) @declaration.property
+
+;; Imports
+(import_header) @import.statement
+
+;; Type bindings — parameters
+(parameter
+  (simple_identifier) @type-binding.name
+  [(user_type) (nullable_type) (function_type)] @type-binding.type) @type-binding.parameter
+
+;; Type bindings — property / local annotations
+(property_declaration
+  (variable_declaration
+    (simple_identifier) @type-binding.name
+    [(user_type) (nullable_type) (function_type)] @type-binding.type)) @type-binding.annotation
+
+(class_parameter
+  (binding_pattern_kind)
+  (simple_identifier) @type-binding.name
+  [(user_type) (nullable_type) (function_type)] @type-binding.type) @type-binding.annotation
+
+;; Type bindings — constructor-inferred val user = User(...)
+(property_declaration
+  (variable_declaration
+    (simple_identifier) @type-binding.name)
+  (call_expression
+    (simple_identifier) @type-binding.type)) @type-binding.constructor
+
+;; Type bindings — return annotations after function parameters
+(function_declaration
+  (simple_identifier) @type-binding.name
+  (function_value_parameters)
+  [(user_type) (nullable_type) (function_type)] @type-binding.type) @type-binding.return
+
+;; References — direct calls / constructor syntax
+(call_expression
+  (simple_identifier) @reference.name) @reference.call.free
+
+;; References — member calls: obj.method()
+(call_expression
+  (navigation_expression
+    (_) @reference.receiver
+    (navigation_suffix
+      (simple_identifier) @reference.name))) @reference.call.member
+
+;; References — property writes
+(assignment
+  (directly_assignable_expression
+    (_) @reference.receiver
+    (navigation_suffix
+      (simple_identifier) @reference.name))
+  (_)) @reference.write.member
+
+;; References — property reads
+(navigation_expression
+  (_) @reference.receiver
+  (navigation_suffix
+    (simple_identifier) @reference.name)) @reference.read.member
+`;
+
+let parser: Parser | null = null;
+let query: Parser.Query | null = null;
+
+export function getKotlinParser(): Parser {
+  if (parser === null) {
+    parser = new Parser();
+    parser.setLanguage(Kotlin as Parameters<Parser['setLanguage']>[0]);
+  }
+  return parser;
+}
+
+export function getKotlinScopeQuery(): Parser.Query {
+  if (query === null) {
+    query = new Parser.Query(Kotlin as Parameters<Parser['setLanguage']>[0], KOTLIN_SCOPE_QUERY);
+  }
+  return query;
+}

gitnexus/src/core/ingestion/languages/kotlin/receiver-binding.ts

@@ -0,0 +1,106 @@
+import type { Capture, CaptureMatch } from 'gitnexus-shared';
+import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js';
+import { normalizeKotlinType } from './interpret.js';
+
+const TYPE_DECL_NODE_TYPES = new Set([
+  'class_declaration',
+  'object_declaration',
+  'companion_object',
+]);
+
+export function synthesizeKotlinReceiverBinding(fnNode: SyntaxNode): CaptureMatch[] {
+  if (fnNode.type !== 'function_declaration') return [];
+
+  const anchorNode = findFunctionBody(fnNode);
+  if (anchorNode === null) return [];
+
+  const extensionReceiver = extensionReceiverType(fnNode);
+  if (extensionReceiver !== null) {
+    return [buildReceiverMatch(anchorNode, 'this', extensionReceiver)];
+  }
+
+  const enclosingType = findEnclosingTypeDeclaration(fnNode);
+  if (enclosingType === null) return [];
+
+  const enclosingName = typeDeclarationName(enclosingType);
+  if (enclosingName === null) return [];
+
+  const out = [buildReceiverMatch(anchorNode, 'this', enclosingName)];
+  const superName = firstSuperclassText(enclosingType);
+  if (superName !== null) out.push(buildReceiverMatch(anchorNode, 'super', superName));
+  return out;
+}
+
+function findFunctionBody(fnNode: SyntaxNode): SyntaxNode | null {
+  for (let i = 0; i < fnNode.namedChildCount; i++) {
+    const child = fnNode.namedChild(i);
+    if (child?.type === 'function_body') return child;
+  }
+  return fnNode;
+}
+
+function extensionReceiverType(fnNode: SyntaxNode): string | null {
+  for (let i = 0; i < fnNode.namedChildCount; i++) {
+    const child = fnNode.namedChild(i);
+    if (child === null) continue;
+    if (child.type === 'simple_identifier') return null;
+    if (child.type === 'user_type' || child.type === 'nullable_type') {
+      return normalizeKotlinType(child.text);
+    }
+  }
+  return null;
+}
+
+function findEnclosingTypeDeclaration(node: SyntaxNode): SyntaxNode | null {
+  let current = node.parent;
+  while (current !== null) {
+    if (TYPE_DECL_NODE_TYPES.has(current.type)) return current;
+    current = current.parent;
+  }
+  return null;
+}
+
+function typeDeclarationName(typeNode: SyntaxNode): string | null {
+  if (typeNode.type === 'companion_object') {
+    return (
+      typeNode.namedChildren.find((child) => child.type === 'type_identifier')?.text ??
+      enclosingNonCompanionTypeName(typeNode) ??
+      'Companion'
+    );
+  }
+  return typeNode.namedChildren.find((child) => child.type === 'type_identifier')?.text ?? null;
+}
+
+function enclosingNonCompanionTypeName(node: SyntaxNode): string | null {
+  let current = node.parent;
+  while (current !== null) {
+    if (current.type === 'class_declaration' || current.type === 'object_declaration') {
+      return current.namedChildren.find((child) => child.type === 'type_identifier')?.text ?? null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+function firstSuperclassText(typeNode: SyntaxNode): string | null {
+  if (typeNode.type !== 'class_declaration') return null;
+  for (const child of typeNode.namedChildren) {
+    if (child.type !== 'delegation_specifier') continue;
+    const ctor = child.namedChildren.find((n) => n.type === 'constructor_invocation');
+    const userType =
+      ctor?.namedChildren.find((n) => n.type === 'user_type') ??
+      child.namedChildren.find((n) => n.type === 'user_type');
+    const name = userType?.namedChildren.find((n) => n.type === 'type_identifier')?.text;
+    if (name !== undefined) return normalizeKotlinType(name);
+  }
+  return null;
+}
+
+function buildReceiverMatch(anchorNode: SyntaxNode, name: string, typeText: string): CaptureMatch {
+  const out: Record<string, Capture> = {
+    '@type-binding.self': nodeToCapture('@type-binding.self', anchorNode),
+    '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, name),
+    '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeText),
+  };
+  return out;
+}

gitnexus/src/core/ingestion/languages/kotlin/scope-resolver.ts

@@ -0,0 +1,56 @@
+import { SupportedLanguages, type ParsedFile } from 'gitnexus-shared';
+import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js';
+import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js';
+import { kotlinProvider } from '../kotlin.js';
+import {
+  kotlinArityCompatibility,
+  kotlinMergeBindings,
+  populateKotlinOwners,
+  resolveKotlinImportTarget,
+  type KotlinResolveContext,
+} from './index.js';
+
+/**
+ * Kotlin scope resolver for RFC #909 Ring 3.
+ *
+ * Kotlin is intentionally registered but not yet listed in
+ * `MIGRATED_LANGUAGES`, matching the Java migration pattern from #1482:
+ * the resolver can run in shadow/forced mode, while production default
+ * stays on the legacy DAG until registry-primary parity reaches the
+ * RFC threshold. Forced mode currently passes 154/175 fixtures (88%),
+ * including core import, receiver, companion, default-param, vararg,
+ * constructor, local assignment-chain, and collection-iteration fixtures.
+ * Remaining gaps are advanced TypeEnv behaviors such as smart casts,
+ * cross-file iterable return propagation, method-chain fixpoint cases,
+ * overload target-id selection, virtual dispatch, and interface default
+ * method dispatch.
+ */
+export const kotlinScopeResolver: ScopeResolver = {
+  language: SupportedLanguages.Kotlin,
+  languageProvider: kotlinProvider,
+  importEdgeReason: 'kotlin-scope: import',
+
+  resolveImportTarget: (targetRaw, fromFile, allFilePaths) => {
+    const ws: KotlinResolveContext = { fromFile, allFilePaths };
+    return resolveKotlinImportTarget(
+      { kind: 'named', localName: '_', importedName: '_', targetRaw },
+      ws,
+    );
+  },
+
+  mergeBindings: (existing, incoming) => [...kotlinMergeBindings([...existing, ...incoming])],
+
+  arityCompatibility: (callsite, def) => kotlinArityCompatibility(def, callsite),
+
+  buildMro: (graph, parsedFiles, nodeLookup) =>
+    buildMro(graph, parsedFiles, nodeLookup, defaultLinearize),
+
+  populateOwners: (parsed: ParsedFile) => populateKotlinOwners(parsed),
+
+  isSuperReceiver: (text) => text.trim() === 'super',
+
+  fieldFallbackOnMethodLookup: false,
+  propagatesReturnTypesAcrossImports: true,
+  collapseMemberCallsByCallerTarget: false,
+  hoistTypeBindingsToModule: true,
+};

gitnexus/src/core/ingestion/languages/kotlin/simple-hooks.ts

@@ -0,0 +1,36 @@
+import type {
+  CaptureMatch,
+  ParsedImport,
+  Scope,
+  ScopeId,
+  ScopeTree,
+  TypeRef,
+} from 'gitnexus-shared';
+
+export function kotlinBindingScopeFor(
+  decl: CaptureMatch,
+  innermost: Scope,
+  tree: ScopeTree,
+): ScopeId | null {
+  if (decl['@type-binding.return'] === undefined) return null;
+
+  let current: Scope | undefined = innermost;
+  while (current !== undefined && current.kind !== 'Module') {
+    if (current.parent === null) break;
+    current = tree.getScope(current.parent);
+  }
+  return current?.kind === 'Module' ? current.id : null;
+}
+
+export function kotlinImportOwningScope(
+  _imp: ParsedImport,
+  _innermost: Scope,
+  _tree: ScopeTree,
+): ScopeId | null {
+  return null;
+}
+
+export function kotlinReceiverBinding(functionScope: Scope): TypeRef | null {
+  if (functionScope.kind !== 'Function') return null;
+  return functionScope.typeBindings.get('this') ?? functionScope.typeBindings.get('super') ?? null;
+}

gitnexus/src/core/ingestion/languages/typescript.ts

@@ -56,6 +56,16 @@ import {
   typescriptArityCompatibility,
   resolveTsImportTarget,
 } from './typescript/index.js';
+import {
+  emitJsScopeCaptures,
+  interpretJsImport,
+  interpretJsTypeBinding,
+  jsBindingScopeFor,
+  jsImportOwningScope,
+  jsReceiverBinding,
+  jsMergeBindings,
+  jsArityCompatibility,
+} from './javascript/index.js';
 
 /**
  * TypeScript/JavaScript: arrow_function and function_expression are
@@ -359,4 +369,19 @@ export const javascriptProvider = defineLanguage({
   classExtractor: createClassExtractor(javascriptClassConfig),
   heritageExtractor: createHeritageExtractor(SupportedLanguages.JavaScript),
   builtInNames: BUILT_INS,
+
+  // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
+  // JavaScript is the fourth migration after Python, C#, and TypeScript.
+  // Hooks are thin wrappers over the TypeScript implementations where
+  // semantics are identical; JS-specific additions (CJS require(),
+  // JSDoc type bindings) live in ./javascript/captures.ts.
+  // See ./javascript/index.ts for the full per-module rationale.
+  emitScopeCaptures: emitJsScopeCaptures,
+  interpretImport: interpretJsImport,
+  interpretTypeBinding: interpretJsTypeBinding,
+  bindingScopeFor: jsBindingScopeFor,
+  importOwningScope: jsImportOwningScope,
+  mergeBindings: (_scope, bindings) => jsMergeBindings(bindings),
+  receiverBinding: jsReceiverBinding,
+  arityCompatibility: jsArityCompatibility,
 });

gitnexus/src/core/ingestion/languages/typescript/captures.ts

@@ -64,7 +64,7 @@ const CALL_TAGS = [
   '@reference.call.constructor',
 ] as const;
 
-function pickFirstDefined(grouped: CaptureMatch, tags: readonly string[]): Capture | undefined {
+function pickFirstCapture(grouped: CaptureMatch, tags: readonly string[]): Capture | undefined {
   for (const tag of tags) {
     const cap = grouped[tag];
     if (cap !== undefined) return cap;
@@ -72,6 +72,17 @@ function pickFirstDefined(grouped: CaptureMatch, tags: readonly string[]): Captu
   return undefined;
 }
 
+function pickFirstNode(
+  grouped: Record<string, SyntaxNode | undefined>,
+  tags: readonly string[],
+): SyntaxNode | undefined {
+  for (const tag of tags) {
+    const node = grouped[tag];
+    if (node !== undefined) return node;
+  }
+  return undefined;
+}
+
 /**
  * Drop `@reference.read.member` matches whose underlying `member_expression`
  * is NOT actually a read context:
@@ -113,6 +124,34 @@ function shouldEmitReadMember(memberNode: SyntaxNode): boolean {
   }
 }
 
+/** Walks the parent chain from `node` (inclusive), returning the first node
+ *  whose type matches, or null. Faster than `findNodeAtRange` when the caller
+ *  already holds the anchor node — avoids re-scanning the tree from the root. */
+function findSelfOrAncestorOfType(node: SyntaxNode | undefined, type: string): SyntaxNode | null {
+  if (node === undefined) return null;
+  let current: SyntaxNode | null = node;
+  while (current !== null) {
+    if (current.type === type) return current;
+    current = current.parent;
+  }
+  return null;
+}
+
+/** Walks the parent chain from `node` (inclusive), returning the first node
+ *  whose type is in the set, or null. Plural form of {@link findSelfOrAncestorOfType}. */
+function findSelfOrAncestorOfTypes(
+  node: SyntaxNode | undefined,
+  types: readonly string[],
+): SyntaxNode | null {
+  if (node === undefined) return null;
+  let current: SyntaxNode | null = node;
+  while (current !== null) {
+    if (types.includes(current.type)) return current;
+    current = current.parent;
+  }
+  return null;
+}
+
 export function emitTsScopeCaptures(
   sourceText: string,
   filePath: string,
@@ -151,9 +190,11 @@ export function emitTsScopeCaptures(
     // `@`; we put it back so the central extractor's prefix lookups
     // (`@scope.`, `@declaration.`, …) work.
     const grouped: Record<string, Capture> = {};
+    const groupedNodes: Record<string, SyntaxNode> = {};
     for (const c of m.captures) {
       const tag = '@' + c.name;
       grouped[tag] = nodeToCapture(tag, c.node);
+      groupedNodes[tag] = c.node;
     }
     if (Object.keys(grouped).length === 0) continue;
 
@@ -165,6 +206,10 @@ export function emitTsScopeCaptures(
     if (grouped['@import.statement'] !== undefined) {
       const stmtCapture = grouped['@import.statement'];
       const stmtNode =
+        findSelfOrAncestorOfTypes(groupedNodes['@import.statement'], [
+          'import_statement',
+          'export_statement',
+        ]) ??
         findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_statement') ??
         findNodeAtRange(tree.rootNode, stmtCapture.range, 'export_statement');
       if (stmtNode !== null) {
@@ -183,7 +228,9 @@ export function emitTsScopeCaptures(
     // `splitDynamicImport` branch consumes.
     if (grouped['@import.dynamic'] !== undefined) {
       const dynCapture = grouped['@import.dynamic'];
-      const callNode = findNodeAtRange(tree.rootNode, dynCapture.range, 'call_expression');
+      const callNode =
+        findSelfOrAncestorOfType(groupedNodes['@import.dynamic'], 'call_expression') ??
+        findNodeAtRange(tree.rootNode, dynCapture.range, 'call_expression');
       if (callNode !== null) {
         const decomposed = splitImportStatement(callNode);
         for (const d of decomposed) out.push(d);
@@ -197,7 +244,9 @@ export function emitTsScopeCaptures(
     // we rely on this emit-side filter so the query stays simple.
     if (grouped['@reference.read.member'] !== undefined) {
       const anchor = grouped['@reference.read.member'];
-      const memberNode = findNodeAtRange(tree.rootNode, anchor.range, 'member_expression');
+      const memberNode =
+        findSelfOrAncestorOfType(groupedNodes['@reference.read.member'], 'member_expression') ??
+        findNodeAtRange(tree.rootNode, anchor.range, 'member_expression');
       if (memberNode === null || !shouldEmitReadMember(memberNode)) {
         continue;
       }
@@ -208,9 +257,10 @@ export function emitTsScopeCaptures(
     // overloads — TypeScript supports overload signatures via
     // function_signature, so `parameterTypes` is populated when
     // available.
-    const declAnchor = pickFirstDefined(grouped, FUNCTION_DECL_TAGS);
+    const declAnchor = pickFirstCapture(grouped, FUNCTION_DECL_TAGS);
+    const declAnchorNode = pickFirstNode(groupedNodes, FUNCTION_DECL_TAGS);
     if (declAnchor !== undefined) {
-      const fnNode = findFunctionNode(tree.rootNode, declAnchor.range);
+      const fnNode = findFunctionNode(tree.rootNode, declAnchor.range, declAnchorNode);
       if (fnNode !== null) {
         const arity = computeTsArityMetadata(fnNode);
         if (arity.parameterCount !== undefined) {
@@ -255,9 +305,11 @@ export function emitTsScopeCaptures(
     // calls to disambiguate by props-arity, a JSX-aware arity
     // synthesizer would need to count `jsx_attribute` children of the
     // opening tag instead of `arguments`.
-    const callAnchor = pickFirstDefined(grouped, CALL_TAGS);
+    const callAnchor = pickFirstCapture(grouped, CALL_TAGS);
+    const callAnchorNode = pickFirstNode(groupedNodes, CALL_TAGS);
     if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) {
       const callNode =
+        findSelfOrAncestorOfTypes(callAnchorNode, ['call_expression', 'new_expression']) ??
         findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression') ??
         findNodeAtRange(tree.rootNode, callAnchor.range, 'new_expression');
       if (callNode !== null) {
@@ -293,7 +345,11 @@ export function emitTsScopeCaptures(
     // lookup instead of synthesis — covered by `tsReceiverBinding`.
     const scopeFnAnchor = grouped['@scope.function'];
     if (scopeFnAnchor !== undefined) {
-      const fnNode = findFunctionNode(tree.rootNode, scopeFnAnchor.range);
+      const fnNode = findFunctionNode(
+        tree.rootNode,
+        scopeFnAnchor.range,
+        groupedNodes['@scope.function'],
+      );
       if (fnNode !== null) {
         const synth = synthesizeTsReceiverBinding(fnNode);
         if (synth !== null) out.push(synth);
@@ -518,7 +574,13 @@ function inferArgType(argNode: SyntaxNode): string {
  *  The `@scope.function` anchor range covers the whole node, but the
  *  tag alone doesn't identify which node type among the many TS
  *  function-likes. */
-function findFunctionNode(rootNode: SyntaxNode, range: Capture['range']): SyntaxNode | null {
+function findFunctionNode(
+  rootNode: SyntaxNode,
+  range: Capture['range'],
+  anchorNode?: SyntaxNode,
+): SyntaxNode | null {
+  const fromAnchor = findSelfOrAncestorOfTypes(anchorNode, FUNCTION_NODE_TYPES);
+  if (fromAnchor !== null) return fromAnchor;
   for (const nodeType of FUNCTION_NODE_TYPES) {
     const n = findNodeAtRange(rootNode, range, nodeType);
     if (n !== null) return n;

gitnexus/src/core/ingestion/languages/typescript/simple-hooks.ts

@@ -75,8 +75,11 @@ export function tsBindingScopeFor(
  * any of `kinds`. Returns the matching scope's id or `null` when no
  * ancestor matches (e.g., a return type binding emitted outside any
  * Module scope — shouldn't happen in well-formed input).
+ *
+ * Exported so language-specific hook wrappers (e.g. `jsBindingScopeFor`)
+ * can reuse it without duplicating the traversal logic.
  */
-function walkToScope(
+export function walkToScope(
   from: Scope,
   tree: ScopeTree,
   ...kinds: readonly Scope['kind'][]

gitnexus/src/core/ingestion/model/field-registry.ts

@@ -2,18 +2,35 @@
  * Field Registry
  *
  * Owner-scoped field/property index extracted from SymbolTable.
- * Stores Property symbols keyed by `ownerNodeId\0fieldName` for O(1) lookup.
+ * Stores Property / Variable / Const / Static symbols keyed by
+ * `ownerNodeId\0fieldName` for O(1) lookup. Supports multiple defs
+ * under the same (owner, name) — e.g. legacy Property plus a
+ * scope-resolution Variable reconciliation entry.
  */
 
 import type { SymbolDefinition } from 'gitnexus-shared';
 
+const EMPTY: readonly SymbolDefinition[] = Object.freeze([]);
+
 // ---------------------------------------------------------------------------
 // Public read-only interface
 // ---------------------------------------------------------------------------
 
 export interface FieldRegistry {
-  /** Look up a field/property by its owning class nodeId and field name. */
+  /**
+   * First field registered under `(ownerNodeId, fieldName)`, if any.
+   * Registration order is first-wins: when a Property and a Variable share
+   * an `(owner, simpleName)` key, the earlier `register(...)` call's def is
+   * returned. Prefer `lookupAllByOwner` when overloads or duplicate-kind
+   * entries under the same name must all be visible.
+   */
   lookupFieldByOwner(ownerNodeId: string, fieldName: string): SymbolDefinition | undefined;
+
+  /**
+   * Every field registered under `(ownerNodeId, fieldName)` in registration
+   * order. Returns `[]` on miss.
+   */
+  lookupAllByOwner(ownerNodeId: string, fieldName: string): readonly SymbolDefinition[];
 }
 
 // ---------------------------------------------------------------------------
@@ -21,7 +38,7 @@ export interface FieldRegistry {
 // ---------------------------------------------------------------------------
 
 export interface MutableFieldRegistry extends FieldRegistry {
-  /** Register a field/property under its owner. */
+  /** Register a field under its owner. Appends when the key already exists. */
   register(ownerNodeId: string, fieldName: string, def: SymbolDefinition): void;
   /** Clear all entries. */
   clear(): void;
@@ -32,22 +49,36 @@ export interface MutableFieldRegistry extends FieldRegistry {
 // ---------------------------------------------------------------------------
 
 export const createFieldRegistry = (): MutableFieldRegistry => {
-  const fieldByOwner = new Map<string, SymbolDefinition>();
+  const fieldByOwner = new Map<string, SymbolDefinition[]>();
+
+  const lookupAllByOwner = (
+    ownerNodeId: string,
+    fieldName: string,
+  ): readonly SymbolDefinition[] => {
+    return fieldByOwner.get(`${ownerNodeId}\0${fieldName}`) ?? EMPTY;
+  };
 
   const lookupFieldByOwner = (
     ownerNodeId: string,
     fieldName: string,
   ): SymbolDefinition | undefined => {
-    return fieldByOwner.get(`${ownerNodeId}\0${fieldName}`);
+    const pool = lookupAllByOwner(ownerNodeId, fieldName);
+    return pool.length === 0 ? undefined : pool[0];
   };
 
   const register = (ownerNodeId: string, fieldName: string, def: SymbolDefinition): void => {
-    fieldByOwner.set(`${ownerNodeId}\0${fieldName}`, def);
+    const key = `${ownerNodeId}\0${fieldName}`;
+    const existing = fieldByOwner.get(key);
+    if (existing) {
+      existing.push(def);
+    } else {
+      fieldByOwner.set(key, [def]);
+    }
   };
 
   const clear = (): void => {
     fieldByOwner.clear();
   };
 
-  return { lookupFieldByOwner, register, clear };
+  return { lookupFieldByOwner, lookupAllByOwner, register, clear };
 };

gitnexus/src/core/ingestion/model/owned-members-lookup.ts

@@ -0,0 +1,45 @@
+/**
+ * Owner-keyed member lookup for Step 2 (RFC #909 / PR #1656).
+ *
+ * Merges MethodRegistry + FieldRegistry hits for `(ownerDefId, memberName)`
+ * in O(1) map time per registry — no `defs.byId` scan. Callers that omit
+ * this helper and leave `ownedMembersByOwner` unset fall back to an O(|defs|)
+ * compatibility scan inside `lookupCore.collectOwnedMembers`.
+ */
+
+import type { DefId, SymbolDefinition } from 'gitnexus-shared';
+import type { SemanticModel } from './semantic-model.js';
+
+const EMPTY: readonly SymbolDefinition[] = Object.freeze([]);
+
+/**
+ * Production hook for `RegistryContext.ownedMembersByOwner`.
+ * Returns `[]` on miss (authoritative indexed empty) — never `undefined`.
+ *
+ * Merges hits from all three owner-keyed registries (methods, fields,
+ * nested types) under the same `(ownerDefId, memberName)` key. The
+ * caller's `acceptedKinds` filter in `lookupCore` picks the right subset.
+ */
+export function lookupOwnedMembersByOwner(
+  model: Pick<SemanticModel, 'methods' | 'fields' | 'types'>,
+  ownerDefId: DefId,
+  memberName: string,
+): readonly SymbolDefinition[] {
+  const methods = model.methods.lookupAllByOwner(ownerDefId, memberName);
+  const fields = model.fields.lookupAllByOwner(ownerDefId, memberName);
+  const nestedTypes = model.types.lookupAllByOwner(ownerDefId, memberName);
+  const methodCount = methods.length;
+  const fieldCount = fields.length;
+  const typeCount = nestedTypes.length;
+  const total = methodCount + fieldCount + typeCount;
+  if (total === 0) return EMPTY;
+  if (methodCount === total) return methods;
+  if (fieldCount === total) return fields;
+  if (typeCount === total) return nestedTypes;
+  const merged = new Array<SymbolDefinition>(total);
+  let i = 0;
+  for (let j = 0; j < methodCount; j++) merged[i++] = methods[j]!;
+  for (let j = 0; j < fieldCount; j++) merged[i++] = fields[j]!;
+  for (let j = 0; j < typeCount; j++) merged[i++] = nestedTypes[j]!;
+  return merged;
+}

gitnexus/src/core/ingestion/model/symbol-table.ts

@@ -34,7 +34,7 @@
  * logic up the dependency chain instead.
  */
 
-import type { NodeLabel, SymbolDefinition } from 'gitnexus-shared';
+import type { NodeLabel, ParameterTypeClass, SymbolDefinition } from 'gitnexus-shared';
 
 /**
  * Class-like NodeLabels — used for qualifiedName fallback inside
@@ -126,6 +126,7 @@ export interface AddMetadata {
   parameterCount?: number;
   requiredParameterCount?: number;
   parameterTypes?: string[];
+  parameterTypeClasses?: ParameterTypeClass[];
   returnType?: string;
   declaredType?: string;
   templateArguments?: string[];
@@ -276,6 +277,9 @@ export const createSymbolTable = (): InternalSymbolTable => {
       ...(metadata?.parameterTypes !== undefined
         ? { parameterTypes: metadata.parameterTypes }
         : {}),
+      ...(metadata?.parameterTypeClasses !== undefined
+        ? { parameterTypeClasses: metadata.parameterTypeClasses }
+        : {}),
       ...(metadata?.returnType !== undefined ? { returnType: metadata.returnType } : {}),
       ...(metadata?.declaredType !== undefined ? { declaredType: metadata.declaredType } : {}),
       ...(metadata?.templateArguments !== undefined

gitnexus/src/core/ingestion/model/type-registry.ts

@@ -8,6 +8,8 @@
 
 import type { SymbolDefinition } from 'gitnexus-shared';
 
+const EMPTY: readonly SymbolDefinition[] = Object.freeze([]);
+
 // ---------------------------------------------------------------------------
 // Public read-only interface
 // ---------------------------------------------------------------------------
@@ -35,6 +37,14 @@ export interface TypeRegistry {
    * Returned array is a view into the live index — do not mutate.
    */
   lookupImplByName(name: string): readonly SymbolDefinition[];
+
+  /**
+   * Look up nested-type defs registered under `(ownerNodeId, simpleName)`
+   * in registration order. Returns `[]` on miss. Used by Step 2 Receiver/MRO
+   * resolution when the receiver's owner declares nested classes/structs/
+   * enums/typedefs/etc. that the caller's `acceptedKinds` includes.
+   */
+  lookupAllByOwner(ownerNodeId: string, simpleName: string): readonly SymbolDefinition[];
 }
 
 // ---------------------------------------------------------------------------
@@ -46,6 +56,8 @@ export interface MutableTypeRegistry extends TypeRegistry {
   registerClass(name: string, qualifiedName: string, def: SymbolDefinition): void;
   /** Register a Rust Impl block by name. */
   registerImpl(name: string, def: SymbolDefinition): void;
+  /** Register a nested type under its owner. Appends when the key already exists. */
+  registerByOwner(ownerNodeId: string, simpleName: string, def: SymbolDefinition): void;
   /** Clear all entries. */
   clear(): void;
 }
@@ -58,6 +70,7 @@ export const createTypeRegistry = (): MutableTypeRegistry => {
   const classByName = new Map<string, SymbolDefinition[]>();
   const classByQualifiedName = new Map<string, SymbolDefinition[]>();
   const implByName = new Map<string, SymbolDefinition[]>();
+  const nestedByOwner = new Map<string, SymbolDefinition[]>();
 
   const lookupClassByName = (name: string): SymbolDefinition[] => {
     return classByName.get(name) ?? [];
@@ -71,6 +84,13 @@ export const createTypeRegistry = (): MutableTypeRegistry => {
     return implByName.get(name) ?? [];
   };
 
+  const lookupAllByOwner = (
+    ownerNodeId: string,
+    simpleName: string,
+  ): readonly SymbolDefinition[] => {
+    return nestedByOwner.get(`${ownerNodeId}\0${simpleName}`) ?? EMPTY;
+  };
+
   const registerClass = (name: string, qualifiedName: string, def: SymbolDefinition): void => {
     const existing = classByName.get(name);
     if (existing) {
@@ -96,18 +116,35 @@ export const createTypeRegistry = (): MutableTypeRegistry => {
     }
   };
 
+  const registerByOwner = (
+    ownerNodeId: string,
+    simpleName: string,
+    def: SymbolDefinition,
+  ): void => {
+    const key = `${ownerNodeId}\0${simpleName}`;
+    const existing = nestedByOwner.get(key);
+    if (existing) {
+      existing.push(def);
+    } else {
+      nestedByOwner.set(key, [def]);
+    }
+  };
+
   const clear = (): void => {
     classByName.clear();
     classByQualifiedName.clear();
     implByName.clear();
+    nestedByOwner.clear();
   };
 
   return {
     lookupClassByName,
     lookupClassByQualifiedName,
     lookupImplByName,
+    lookupAllByOwner,
     registerClass,
     registerImpl,
+    registerByOwner,
     clear,
   };
 };

gitnexus/src/core/ingestion/parsing-processor.ts

@@ -1,4 +1,4 @@
-import type { GraphNode, GraphRelationship, NodeLabel } from 'gitnexus-shared';
+import type { GraphNode, GraphRelationship, NodeLabel, ParameterTypeClass } from 'gitnexus-shared';
 import { KnowledgeGraph } from '../graph/types.js';
 import Parser from 'tree-sitter';
 import { loadParser, loadLanguage, isLanguageAvailable } from '../tree-sitter/parser-loader.js';
@@ -14,6 +14,7 @@ import { isVerboseIngestionEnabled } from './utils/verbose.js';
 import {
   getDefinitionNodeFromCaptures,
   findEnclosingClassInfo,
+  findObjectLiteralBindingInfo,
   getLabelFromCaptures,
   CLASS_CONTAINER_TYPES,
   type SyntaxNode,
@@ -30,7 +31,11 @@ import {
   constTagForId,
   buildCollisionGroups,
 } from './utils/method-props.js';
-import { extractTemplateArguments, templateArgumentsIdTag } from './utils/template-arguments.js';
+import {
+  extractTemplateArguments,
+  templateArgumentsIdTag,
+  templateConstraintsIdTag,
+} from './utils/template-arguments.js';
 import type { LanguageProvider } from './language-provider.js';
 import type { ParsedFile } from 'gitnexus-shared';
 import { WorkerPool } from './workers/worker-pool.js';
@@ -128,6 +133,7 @@ export const mergeChunkResults = (
         parameterCount: sym.parameterCount,
         requiredParameterCount: sym.requiredParameterCount,
         parameterTypes: sym.parameterTypes,
+        parameterTypeClasses: sym.parameterTypeClasses,
         returnType: sym.returnType,
         declaredType: sym.declaredType,
         templateArguments: sym.templateArguments,
@@ -526,6 +532,10 @@ const processParsingSequential = async (
           )
         : null;
       const enclosingClassId = enclosingClassInfo?.classId ?? null;
+      const objectLiteralOwnerInfo =
+        !enclosingClassId && nodeLabel === 'Method' && definitionNode
+          ? findObjectLiteralBindingInfo(definitionNode, file.path)
+          : null;
 
       // Qualify method/property IDs with enclosing class name to avoid collisions
       // e.g. "Method:animal.dart:Animal.speak" vs "Method:animal.dart:Dog.speak"
@@ -650,9 +660,38 @@ const processParsingSequential = async (
         classTemplateArguments.length > 0
           ? templateArgumentsIdTag(classTemplateArguments)
           : '';
+      // SFINAE / `requires`-clause aware ID disambiguation (issue #1579).
+      // Function-template overloads with identical parameterTypes but
+      // mutually-exclusive constraints (e.g. `enable_if_t<is_integral_v<T>>`
+      // vs `enable_if_t<is_floating_point_v<T>>`) need distinct graph
+      // nodes so the constraint-filter step in `narrowOverloadCandidates`
+      // has two candidates to narrow between. Without this tag they
+      // collapse to a single Function node and the SFINAE call resolves
+      // to only one edge regardless of which overload's constraint holds.
+      // The provider hook is the right invocation point — parsing-processor
+      // sees raw tree-sitter matches without the `@`-prefixed synthetic
+      // captures `scope-extractor` consumes, so we delegate extraction to
+      // the language adapter (C++ implements this; other languages opt out).
+      let parsedTemplateConstraints: unknown = undefined;
+      let constraintsTag = '';
+      if (
+        (nodeLabel === 'Function' || nodeLabel === 'Method') &&
+        provider.extractTemplateConstraints !== undefined &&
+        definitionNode !== null
+      ) {
+        try {
+          parsedTemplateConstraints = provider.extractTemplateConstraints(definitionNode);
+          if (parsedTemplateConstraints !== undefined) {
+            constraintsTag = templateConstraintsIdTag(parsedTemplateConstraints);
+          }
+        } catch {
+          parsedTemplateConstraints = undefined;
+          constraintsTag = '';
+        }
+      }
       const nodeId = generateId(
         nodeLabel,
-        `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}`,
+        `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}${constraintsTag}`,
       );
       const classNodeForSymbol = definitionNodeForRange || definitionNode || nameNode;
       const qualifiedTypeName =
@@ -689,6 +728,9 @@ const processParsingSequential = async (
           ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0
             ? { templateArguments: classTemplateArguments }
             : {}),
+          ...(parsedTemplateConstraints !== undefined
+            ? { templateConstraints: parsedTemplateConstraints }
+            : {}),
           ...(frameworkHint
             ? {
                 astFrameworkMultiplier: frameworkHint.entryPointMultiplier,
@@ -744,10 +786,11 @@ const processParsingSequential = async (
         parameterCount: methodProps.parameterCount as number | undefined,
         requiredParameterCount: methodProps.requiredParameterCount as number | undefined,
         parameterTypes: methodProps.parameterTypes as string[] | undefined,
+        parameterTypeClasses: methodProps.parameterTypeClasses as ParameterTypeClass[] | undefined,
         returnType: methodProps.returnType as string | undefined,
         declaredType,
         templateArguments: classTemplateArguments,
-        ownerId: enclosingClassId ?? undefined,
+        ownerId: enclosingClassId ?? objectLiteralOwnerInfo?.ownerId ?? undefined,
         qualifiedName: qualifiedTypeName,
       });
 
@@ -767,15 +810,18 @@ const processParsingSequential = async (
       graph.addRelationship(relationship);
 
       // ── HAS_METHOD / HAS_PROPERTY: link member to enclosing class ──
-      if (enclosingClassId) {
+      const ownerIdForMemberEdge = enclosingClassId ?? objectLiteralOwnerInfo?.ownerId ?? null;
+      if (ownerIdForMemberEdge) {
         const memberEdgeType = nodeLabel === 'Property' ? 'HAS_PROPERTY' : 'HAS_METHOD';
         graph.addRelationship({
-          id: generateId(memberEdgeType, `${enclosingClassId}->${nodeId}`),
-          sourceId: enclosingClassId,
+          id: generateId(memberEdgeType, `${ownerIdForMemberEdge}->${nodeId}`),
+          sourceId: ownerIdForMemberEdge,
           targetId: nodeId,
           type: memberEdgeType,
           confidence: 1.0,
-          reason: '',
+          reason: objectLiteralOwnerInfo
+            ? 'object literal method belongs to exported object binding'
+            : '',
         });
       }
     });
@@ -794,6 +840,14 @@ const processParsingSequential = async (
 // Public API
 // ============================================================================
 
+/**
+ * Per-`WorkerPool` log-dedup state for quarantine reporting. Keyed on the
+ * pool instance so multiple concurrent pools (test fixtures, future
+ * multi-pool callers) each get their own seen-set. WeakMap entries vanish
+ * when the pool is garbage-collected.
+ */
+const loggedQuarantineByPool = new WeakMap<WorkerPool, Set<string>>();
+
 export const processParsing = async (
   graph: KnowledgeGraph,
   files: { path: string; content: string }[],
@@ -836,25 +890,75 @@ export const processParsing = async (
         `[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`,
       );
     }
-    try {
-      return await processParsingWithWorkers(
-        graph,
-        files,
-        symbolTable,
-        astCache,
-        workerPool,
-        reportProgress,
-        outRawResults,
-      );
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      logger.warn({ message }, 'Worker pool parsing stopped; continuing with sequential parser:');
-      reportProgress?.(
-        lastProgress,
-        files.length,
-        `Sequential fallback after worker issue: ${message}`,
-      );
+    // U20 design pivot: the worker pool's resilience layers
+    // (respawn budget, circuit breaker, quarantine, slot-attribution,
+    // cumulative timeout) are the SOLE contract for handling worker
+    // failures. There is no sequential-parser fallback for either
+    // partial quarantine or full pool failure — the operator must see
+    // a clear hard signal when workers can't recover, instead of a
+    // silently-degraded graph from a possibly-crashing main-thread
+    // sequential parser. A failing tree-sitter native binding that
+    // quarantined a worker would, under the previous design, re-trigger
+    // the same SIGSEGV on the main thread; we avoid that risk entirely.
+    //
+    // - Partial quarantine: the file is missing from this run's graph;
+    //   the per-chunk warn log below surfaces it; U2's chunk-cache
+    //   write-guard in parse-impl.ts keeps the chunk uncached so the
+    //   next analyze gets a cache miss and a fresh pool retries.
+    // - Full pool failure: `WorkerPoolDispatchError` propagates from
+    //   `processParsingWithWorkers` up through this function. The
+    //   analyze run errors out instead of falling back to sequential.
+    const data = await processParsingWithWorkers(
+      graph,
+      files,
+      symbolTable,
+      astCache,
+      workerPool,
+      reportProgress,
+      outRawResults,
+    );
+    // Session-scoped quarantine (worker-pool resilience Layer 3): surface
+    // any files this pool has decided are unsafe for workers so the
+    // operator can see what was skipped. The pool already filtered them
+    // out of dispatch; we only need to log + progress-report. Quarantine
+    // is session-scoped per pool instance — a fresh `createWorkerPool`
+    // call clears it.
+    //
+    // Dedup: log full path list only for entries newly quarantined since
+    // the previous dispatch on the same pool. The per-chunk progress
+    // message still surfaces the count for UX continuity, but the
+    // structured `quarantinedFiles` payload is only emitted when there
+    // is new signal — prevents O(quarantine × chunks) log spam.
+    const quarantineSnapshot = workerPool.getQuarantinedPaths?.() ?? [];
+    const quarantineSet = new Set(quarantineSnapshot);
+    if (quarantineSet.size > 0) {
+      const quarantinedInChunk = files.filter((file) => quarantineSet.has(file.path));
+      if (quarantinedInChunk.length > 0) {
+        const seenForPool = loggedQuarantineByPool.get(workerPool) ?? new Set<string>();
+        const newlyQuarantined = quarantinedInChunk
+          .map((file) => file.path)
+          .filter((p) => !seenForPool.has(p));
+        for (const p of newlyQuarantined) seenForPool.add(p);
+        loggedQuarantineByPool.set(workerPool, seenForPool);
+        if (newlyQuarantined.length > 0) {
+          logger.warn(
+            {
+              newlyQuarantined,
+              cumulativeQuarantine: quarantineSet.size,
+              chunkSkipped: quarantinedInChunk.length,
+            },
+            `Worker quarantine: ${newlyQuarantined.length} new file(s) skipped this chunk ` +
+              `(${quarantinedInChunk.length} skipped total, ${quarantineSet.size} cumulative).`,
+          );
+        }
+        reportProgress?.(
+          lastProgress,
+          files.length,
+          `${quarantinedInChunk.length} worker-quarantined file(s) skipped`,
+        );
+      }
     }
+    return data;
   }
 
   // Fallback: sequential parsing (no pre-extracted data)

gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts

@@ -48,13 +48,14 @@ import { ASTCache, createASTCache } from '../ast-cache.js';
 import { type PipelineProgress, getLanguageFromFilename } from 'gitnexus-shared';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
-import { createWorkerPool } from '../workers/worker-pool.js';
+import { createWorkerPool, WorkerPoolInitializationError } from '../workers/worker-pool.js';
 import type { WorkerPool } from '../workers/worker-pool.js';
 import type {
   ExtractedAssignment,
   ExtractedCall,
   ExtractedDecoratorRoute,
   ExtractedFetchCall,
+  ExtractedImport,
   ExtractedORMQuery,
   ExtractedRoute,
   ExtractedToolDef,
@@ -69,6 +70,7 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { isDev } from '../utils/env.js';
+import { isVerboseIngestionEnabled } from '../utils/verbose.js';
 import { synthesizeWildcardImportBindings, needsSynthesis } from './wildcard-synthesis.js';
 import { extractORMQueriesInline } from './orm-extraction.js';
 
@@ -85,11 +87,24 @@ import { logger } from '../../logger.js';
  * gives a useful invalidation floor (~1/N chunks on a multi-MB repo)
  * while keeping worker dispatch overhead under 5% on cold runs.
  */
-const CHUNK_BYTE_BUDGET = (() => {
+/**
+ * Built-in chunk byte budget when neither `PipelineOptions.chunkByteBudget`
+ * nor `GITNEXUS_CHUNK_BYTE_BUDGET` is set. Tuned to give a useful
+ * cache-invalidation floor (~1/N chunks on a multi-MB repo) while keeping
+ * worker dispatch overhead under 5% on cold runs. Resolution happens at
+ * call time inside `runChunkedParseAndResolve` (U14 from PR #1693 review)
+ * — previously this was a module-load IIFE, which froze the env value at
+ * import time and meant per-call option threading silently no-op'd.
+ */
+const DEFAULT_CHUNK_BYTE_BUDGET = 2 * 1024 * 1024;
+
+function resolveChunkByteBudget(options?: PipelineOptions): number {
+  const opt = options?.chunkByteBudget;
+  if (typeof opt === 'number' && Number.isFinite(opt) && opt > 0) return opt;
   const env = Number(process.env.GITNEXUS_CHUNK_BYTE_BUDGET);
   if (Number.isFinite(env) && env > 0) return env;
-  return 2 * 1024 * 1024;
-})();
+  return DEFAULT_CHUNK_BYTE_BUDGET;
+}
 
 // ── Main parse + resolve function ──────────────────────────────────────────
 
@@ -177,18 +192,28 @@ export async function runChunkedParseAndResolve(
   if (totalParseable === 0) {
     onProgress({
       phase: 'parsing',
-      percent: 82,
+      // Skip directly to the end of the parse-phase progress band (M2 from PR
+      // #1693 review). Parse 20-70%, deferred 70-95%; nothing in either runs
+      // when there's no parseable file, so jump to 95.
+      percent: 95,
       message: 'No parseable files found — skipping parsing phase',
       stats: { filesProcessed: 0, totalFiles: 0, nodesCreated: graph.nodeCount },
     });
   }
 
-  // Build byte-budget chunks
+  // Build byte-budget chunks. The budget is resolved per-call (U14): options
+  // first, then env, then the built-in default. Pre-U14 this was a
+  // module-load IIFE constant, which froze the env value at import time
+  // and made `PipelineOptions.chunkByteBudget` silently no-op on warm test
+  // runs. Resolving in the function body restores per-call configurability
+  // and matches the pattern used by resolveAutoPoolSize and the U1
+  // parseChunkConcurrency resolver.
+  const chunkByteBudget = resolveChunkByteBudget(options);
   const chunks: string[][] = [];
   let currentChunk: string[] = [];
   let currentBytes = 0;
   for (const file of parseableScanned) {
-    if (currentChunk.length > 0 && currentBytes + file.size > CHUNK_BYTE_BUDGET) {
+    if (currentChunk.length > 0 && currentBytes + file.size > chunkByteBudget) {
       chunks.push(currentChunk);
       currentChunk = [];
       currentBytes = 0;
@@ -203,16 +228,22 @@ export async function runChunkedParseAndResolve(
   if (isDev) {
     const totalMB = parseableScanned.reduce((s, f) => s + f.size, 0) / (1024 * 1024);
     logger.info(
-      `📂 Scan: ${totalFiles} paths, ${totalParseable} parseable (${totalMB.toFixed(0)}MB), ${numChunks} chunks @ ${CHUNK_BYTE_BUDGET / (1024 * 1024)}MB budget`,
+      `📂 Scan: ${totalFiles} paths, ${totalParseable} parseable (${totalMB.toFixed(0)}MB), ${numChunks} chunks @ ${chunkByteBudget / (1024 * 1024)}MB budget`,
     );
   }
 
-  onProgress({
-    phase: 'parsing',
-    percent: 20,
-    message: `Parsing ${totalParseable} files in ${numChunks} chunk${numChunks !== 1 ? 's' : ''}...`,
-    stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
-  });
+  // Skip the "Parsing N files..." announcement when there's nothing to parse
+  // — the early-return branch above already emitted percent 95 ("skipping
+  // parsing phase"), and emitting percent 20 here would regress the
+  // progress stream non-monotonically (M2 from PR #1693 review).
+  if (totalParseable > 0) {
+    onProgress({
+      phase: 'parsing',
+      percent: 20,
+      message: `Parsing ${totalParseable} files in ${numChunks} chunk${numChunks !== 1 ? 's' : ''}...`,
+      stats: { filesProcessed: 0, totalFiles: totalParseable, nodesCreated: graph.nodeCount },
+    });
+  }
 
   // Don't spawn workers for tiny repos — overhead exceeds benefit.
   // Test suites may lower the thresholds via `options.workerThresholdsForTest`
@@ -221,18 +252,36 @@ export async function runChunkedParseAndResolve(
   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
-  let workerPool: WorkerPool | undefined;
-  if (
+  // Create worker pool lazily, reuse across cache-miss chunks.
+  //
+  // `workerPoolSize === 0` is a programmatic equivalent of `skipWorkers:
+  // true` per the `PipelineOptions.workerPoolSize` contract. Short-
+  // circuiting here avoids constructing a useless pool. The pool is
+  // intentionally NOT created before parse-cache lookup: a warm-cache
+  // all-hit run should replay cached worker output without loading
+  // parse-worker.js or any tree-sitter/N-API native bindings.
+  const shouldUseWorkers =
     !options?.skipWorkers &&
-    (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS)
-  ) {
+    options?.workerPoolSize !== 0 &&
+    (totalParseable >= MIN_FILES_FOR_WORKERS || totalBytes >= MIN_BYTES_FOR_WORKERS);
+  let workerPool: WorkerPool | undefined;
+  let workerPoolDisabled = false;
+  const getOrCreateWorkerPool = (): WorkerPool | undefined => {
+    if (!shouldUseWorkers || workerPoolDisabled) return undefined;
+    if (workerPool) return workerPool;
     try {
-      let workerUrl = new URL('../workers/parse-worker.js', import.meta.url);
+      // U20.U3 test-only injection: integration tests pass a custom
+      // worker script URL via `workerUrlForTest` (mirrors the
+      // `workerThresholdsForTest` precedent) so they can drive the
+      // chunk-loop with deterministically-misbehaving workers without
+      // mocking the module import graph. When unset, the normal src/
+      // → dist/ resolution runs.
+      let workerUrl =
+        options?.workerUrlForTest ?? new URL('../workers/parse-worker.js', import.meta.url);
       // When running under vitest, import.meta.url points to src/ where no .js exists.
       // Fall back to the compiled dist/ worker so the pool can spawn real worker threads.
       const thisDir = fileURLToPath(new URL('.', import.meta.url));
-      if (!fs.existsSync(fileURLToPath(workerUrl))) {
+      if (!options?.workerUrlForTest && !fs.existsSync(fileURLToPath(workerUrl))) {
         const distWorker = path.resolve(
           thisDir,
           '..',
@@ -249,14 +298,17 @@ export async function runChunkedParseAndResolve(
           workerUrl = pathToFileURL(distWorker);
         }
       }
-      workerPool = createWorkerPool(workerUrl);
+      workerPool = createWorkerPool(workerUrl, options?.workerPoolSize);
+      return workerPool;
     } catch (err) {
+      workerPoolDisabled = true;
       logger.warn(
         { err: (err as Error).message },
         'Worker pool creation failed, using sequential fallback:',
       );
+      return undefined;
     }
-  }
+  };
 
   let filesParsedSoFar = 0;
 
@@ -301,6 +353,16 @@ export async function runChunkedParseAndResolve(
   const deferredWorkerHeritage: ExtractedHeritage[] = [];
   const deferredConstructorBindings: FileConstructorBindings[] = [];
   const deferredAssignments: ExtractedAssignment[] = [];
+  // Imports accumulated across chunks. Previously processed per-chunk
+  // via `processImportsFromExtracted` inside the chunk loop, which
+  // forced workers to sit idle on the main thread's extraction pass
+  // between chunk dispatches (4-5% CPU utilization symptom). Deferring
+  // to a single end-of-loop pass lets the worker pool start chunk N+1
+  // immediately after chunk N's worker dispatch returns. Resolution is
+  // strictly-more-information at end-of-loop because graph now has
+  // every chunk's symbols — improves cross-chunk import targets.
+  const deferredWorkerImports: ExtractedImport[] = [];
+  let anyChunkNeedsWildcardSynth = false;
   // Aggregated per-file ParsedFile artifacts produced by workers' calls
   // to `extractParsedFile`. Threaded through to the scope-resolution
   // phase so it can SKIP its own re-extraction on cache hits — this is
@@ -317,13 +379,63 @@ export async function runChunkedParseAndResolve(
   let chunkCacheMisses = 0;
 
   try {
+    // U1 — bounded chunk concurrency (B1 from PR #1693 review): pre-fetch
+    // chunk file contents up to `parseChunkConcurrency` chunks ahead of the
+    // dispatch cursor so file I/O overlaps with worker compute. Worker
+    // dispatch itself stays serial because `WorkerPool.dispatch` is not
+    // reentrant (concurrent calls would race on the shared per-slot
+    // busy/in-flight state). With concurrency=1 behavior is identical to
+    // the pure-serial loop. F4: deferred-state aggregation still happens
+    // in chunkIdx order (the for-loop below iterates sequentially), so
+    // cross-chunk processors see deterministic input regardless of
+    // file-read completion order. Honors options.parseChunkConcurrency
+    // (threaded from the CLI), then GITNEXUS_PARSE_CHUNK_CONCURRENCY env
+    // (default 2 — matches the help text the CLI advertises).
+    const parseChunkConcurrency = ((): number => {
+      const opt = options?.parseChunkConcurrency;
+      if (typeof opt === 'number' && Number.isInteger(opt) && opt >= 1) return opt;
+      const env = Number(process.env.GITNEXUS_PARSE_CHUNK_CONCURRENCY);
+      if (Number.isInteger(env) && env >= 1) return env;
+      return 2;
+    })();
+    const chunkContentPromises = new Array<Promise<Map<string, string>> | undefined>(numChunks);
+    const startChunkPrefetch = (i: number): void => {
+      if (i >= numChunks || chunkContentPromises[i] !== undefined) return;
+      chunkContentPromises[i] = readFileContents(repoPath, chunks[i]);
+    };
+    for (let i = 0; i < Math.min(parseChunkConcurrency, numChunks); i++) {
+      startChunkPrefetch(i);
+    }
+
+    // Hoisted loop-invariant: GITNEXUS_VERBOSE / NODE_ENV are read once
+    // (not on every chunk). Previously evaluated at the top of the loop
+    // body, which re-read process.env on every iteration even though
+    // the env can't change mid-run.
+    const verboseThroughputLog = isDev || isVerboseIngestionEnabled();
+
     for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
       const chunkPaths = chunks[chunkIdx];
+      // Start wall-clock for the per-chunk throughput log emitted at end
+      // of this iteration. The gate is computed once above; here we just
+      // sample the clock if the gate is on. Computed when either
+      // NODE_ENV=development OR the operator passed `--verbose`
+      // (GITNEXUS_VERBOSE) — the previous `isDev`-only gate meant
+      // operators running `gitnexus analyze --verbose` in production
+      // never saw the log (M3 from PR #1693 review).
+      const chunkStartMs: number | null = verboseThroughputLog ? Date.now() : null;
 
-      const chunkContents = await readFileContents(repoPath, chunkPaths);
-      const chunkFiles = chunkPaths
-        .filter((p) => chunkContents.has(p))
-        .map((p) => ({ path: p, content: chunkContents.get(p)! }));
+      const chunkContentPromise = chunkContentPromises[chunkIdx];
+      if (!chunkContentPromise) {
+        throw new Error(`Missing prefetched parse chunk ${chunkIdx + 1}/${numChunks}`);
+      }
+      const chunkContents = await chunkContentPromise;
+      chunkContentPromises[chunkIdx] = undefined; // release the in-memory copy
+      startChunkPrefetch(chunkIdx + parseChunkConcurrency);
+      const chunkFiles: Array<{ path: string; content: string }> = [];
+      for (const p of chunkPaths) {
+        const content = chunkContents.get(p);
+        if (content !== undefined) chunkFiles.push({ path: p, content });
+      }
 
       // Compute the chunk's content-hash signature (if cache available).
       let chunkHash: string | null = null;
@@ -336,7 +448,7 @@ export async function runChunkedParseAndResolve(
       }
 
       let chunkWorkerData: WorkerExtractedData | null;
-      const cachedRaw = chunkHash ? parseCache!.entries.get(chunkHash) : undefined;
+      const cachedRaw = chunkHash && parseCache ? parseCache.entries.get(chunkHash) : undefined;
 
       // Track every chunk hash we touched so the orchestrator can
       // prune stale entries (chunks whose composition no longer
@@ -350,14 +462,18 @@ export async function runChunkedParseAndResolve(
         chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw);
         if (isDev) {
           logger.info(
-            `📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash!.slice(0, 8)})`,
+            `📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash?.slice(0, 8) ?? 'unknown'})`,
           );
         }
         // Progress update so UI advances even on a cache hit.
         const cachedFiles = chunkFiles.length;
         onProgress({
           phase: 'parsing',
-          percent: Math.round(20 + ((filesParsedSoFar + cachedFiles) / totalParseable) * 62),
+          // Parse phase covers 20-70 (50 points). Deferred extraction below
+          // takes 70-95 so the UI advances through the (potentially long)
+          // resolution stages instead of holding at 82 (M2 from PR #1693
+          // review).
+          percent: Math.round(20 + ((filesParsedSoFar + cachedFiles) / totalParseable) * 50),
           message: `Parsing chunk ${chunkIdx + 1}/${numChunks} (cache)...`,
           stats: {
             filesProcessed: filesParsedSoFar + cachedFiles,
@@ -370,85 +486,121 @@ export async function runChunkedParseAndResolve(
         // them under the chunk hash for the next run.
         chunkCacheMisses++;
         const rawResults: ParseWorkerResult[] = [];
-        chunkWorkerData = await processParsing(
-          graph,
-          chunkFiles,
-          symbolTable,
-          astCache,
-          scopeTreeCache,
-          (current, _total, filePath) => {
-            const globalCurrent = filesParsedSoFar + current;
-            const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
-            onProgress({
-              phase: 'parsing',
-              percent: Math.round(parsingProgress),
-              message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
-              detail: filePath,
-              stats: {
-                filesProcessed: globalCurrent,
-                totalFiles: totalParseable,
-                nodesCreated: graph.nodeCount,
-              },
-            });
-          },
-          workerPool,
-          // Capture raw results only when we have a cache to write to —
-          // otherwise we'd retain extra arrays for nothing.
-          parseCache && chunkHash ? rawResults : undefined,
-        );
+        const progressForChunk = (current: number, _total: number, filePath: string) => {
+          const globalCurrent = filesParsedSoFar + current;
+          // Parse phase covers 20-70 (M2). Deferred extraction handles 70-95.
+          const parsingProgress = 20 + (globalCurrent / totalParseable) * 50;
+          onProgress({
+            phase: 'parsing',
+            percent: Math.round(parsingProgress),
+            message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
+            detail: filePath,
+            stats: {
+              filesProcessed: globalCurrent,
+              totalFiles: totalParseable,
+              nodesCreated: graph.nodeCount,
+            },
+          });
+        };
+        const activeWorkerPool = getOrCreateWorkerPool();
+        try {
+          chunkWorkerData = await processParsing(
+            graph,
+            chunkFiles,
+            symbolTable,
+            astCache,
+            scopeTreeCache,
+            progressForChunk,
+            activeWorkerPool,
+            // Capture raw results only when we have a cache to write to —
+            // otherwise we'd retain extra arrays for nothing.
+            parseCache && chunkHash && activeWorkerPool ? rawResults : undefined,
+          );
+        } catch (err) {
+          if (!(err instanceof WorkerPoolInitializationError)) throw err;
+          logger.warn(
+            {
+              err: err.message,
+              readinessFailures: err.readinessFailures,
+            },
+            'Worker pool initialization failed, using sequential fallback:',
+          );
+          rawResults.length = 0;
+          workerPoolDisabled = true;
+          const failedPool = workerPool;
+          workerPool = undefined;
+          await failedPool?.terminate().catch(() => undefined);
+          chunkWorkerData = await processParsing(
+            graph,
+            chunkFiles,
+            symbolTable,
+            astCache,
+            scopeTreeCache,
+            progressForChunk,
+            undefined,
+            undefined,
+          );
+        }
         // Persist the raw results for this chunk hash. Sequential path
         // doesn't populate rawResults (it writes directly to graph), so
         // small repos without worker pool simply don't cache. That's fine.
+        //
+        // U20.U2: refuse the write when any chunk file is in the
+        // worker pool's cumulative quarantine snapshot. The chunkHash
+        // is computed from EVERY file in the chunk, but the pool's
+        // Layer 3 quarantine filters quarantined files out of dispatch
+        // — so `rawResults` is narrower than the chunkHash key implies.
+        // Caching it would silently replay incomplete results on the
+        // next run with unchanged content (the corruption class Codex's
+        // adversarial review of PR #1693 flagged).
+        //
+        // Skipping the write means the next analyze gets a cache miss
+        // for this chunk and re-dispatches against a fresh worker pool
+        // (quarantine is session-scoped — `createQuarantine` is called
+        // per-pool at worker-pool.ts), giving the quarantined file
+        // another chance. If quarantine fires again, U20.U1's
+        // sequential gap-fill still produces a complete graph for this
+        // run; the cache just stays empty for this chunk until a fully-
+        // clean dispatch lands.
         if (parseCache && chunkHash && rawResults.length > 0) {
-          parseCache.entries.set(chunkHash, rawResults);
-          if (isDev) {
-            logger.info(
-              `📦 parse-cache MISS+store: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`,
-            );
+          const quarantineSnapshot = workerPool?.getQuarantinedPaths?.() ?? [];
+          const quarantineSet = new Set(quarantineSnapshot);
+          const chunkHadQuarantine = chunkFiles.some((f) => quarantineSet.has(f.path));
+          if (chunkHadQuarantine) {
+            if (isDev) {
+              const quarantinedInChunk = chunkFiles.filter((f) => quarantineSet.has(f.path)).length;
+              logger.info(
+                `📦 parse-cache SKIP: chunk ${chunkIdx + 1}/${numChunks} ` +
+                  `had ${quarantinedInChunk} worker-quarantined file(s); ` +
+                  `next run will rediscover (${chunkHash.slice(0, 8)})`,
+              );
+            }
+          } else {
+            parseCache.entries.set(chunkHash, rawResults);
+            if (isDev) {
+              logger.info(
+                `📦 parse-cache MISS+store: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`,
+              );
+            }
           }
         }
       }
 
-      const chunkBasePercent = 20 + (filesParsedSoFar / totalParseable) * 62;
-
+      // Per-chunk extraction passes (processImportsFromExtracted,
+      // processHeritageFromExtracted, processRoutesFromExtracted,
+      // synthesizeWildcardImportBindings, seedCrossFileReceiverTypes)
+      // moved out of the chunk loop into a single end-of-loop pass below.
+      // Reason: per-chunk extraction blocked the chunk loop on
+      // main-thread work between worker dispatches — workers sat idle
+      // and total CPU utilization plateaued at 4-5% on multi-core boxes.
+      // Deferring keeps workers busy chunk-after-chunk; resolution sees
+      // strictly-more-information (full repo graph) so cross-chunk import
+      // and heritage targets resolve at least as well as before.
       if (chunkWorkerData) {
-        await processImportsFromExtracted(
-          graph,
-          allPathObjects,
-          chunkWorkerData.imports,
-          ctx,
-          (current, total) => {
-            onProgress({
-              phase: 'parsing',
-              percent: Math.round(chunkBasePercent),
-              message: `Resolving imports (chunk ${chunkIdx + 1}/${numChunks})...`,
-              detail: `${current}/${total} files`,
-              stats: {
-                filesProcessed: filesParsedSoFar,
-                totalFiles: totalParseable,
-                nodesCreated: graph.nodeCount,
-              },
-            });
-          },
-          repoPath,
-          importCtx,
-        );
         if (chunkNeedsSynthesis[chunkIdx]) {
-          synthesizeWildcardImportBindings(graph, ctx);
-          hasSynthesized = true;
-        }
-        if (exportedTypeMap.size > 0 && ctx.namedImportMap.size > 0) {
-          const { enrichedCount } = seedCrossFileReceiverTypes(
-            chunkWorkerData.calls,
-            ctx.namedImportMap,
-            exportedTypeMap,
-          );
-          if (isDev && enrichedCount > 0) {
-            logger.info(
-              `🔗 E1: Seeded ${enrichedCount} cross-file receiver types (chunk ${chunkIdx + 1})`,
-            );
-          }
+          anyChunkNeedsWildcardSynth = true;
         }
+        for (const item of chunkWorkerData.imports) deferredWorkerImports.push(item);
         for (const item of chunkWorkerData.calls) deferredWorkerCalls.push(item);
         for (const item of chunkWorkerData.heritage) deferredWorkerHeritage.push(item);
         for (const item of chunkWorkerData.constructorBindings)
@@ -463,35 +615,6 @@ export async function runChunkedParseAndResolve(
           for (const item of chunkWorkerData.assignments) deferredAssignments.push(item);
         }
 
-        await Promise.all([
-          processHeritageFromExtracted(graph, chunkWorkerData.heritage, ctx, (current, total) => {
-            onProgress({
-              phase: 'parsing',
-              percent: Math.round(chunkBasePercent),
-              message: `Resolving heritage (chunk ${chunkIdx + 1}/${numChunks})...`,
-              detail: `${current}/${total} records`,
-              stats: {
-                filesProcessed: filesParsedSoFar,
-                totalFiles: totalParseable,
-                nodesCreated: graph.nodeCount,
-              },
-            });
-          }),
-          processRoutesFromExtracted(graph, chunkWorkerData.routes ?? [], ctx, (current, total) => {
-            onProgress({
-              phase: 'parsing',
-              percent: Math.round(chunkBasePercent),
-              message: `Resolving routes (chunk ${chunkIdx + 1}/${numChunks})...`,
-              detail: `${current}/${total} routes`,
-              stats: {
-                filesProcessed: filesParsedSoFar,
-                totalFiles: totalParseable,
-                nodesCreated: graph.nodeCount,
-              },
-            });
-          }),
-        ]);
-
         if (chunkWorkerData.fileScopeBindings?.length) {
           for (const { filePath, bindings } of chunkWorkerData.fileScopeBindings) {
             if (typeof filePath !== 'string' || filePath.length === 0) continue;
@@ -530,6 +653,24 @@ export async function runChunkedParseAndResolve(
 
       filesParsedSoFar += chunkFiles.length;
       astCache.clear();
+
+      // Throughput observability (U3): emit a per-chunk metrics line
+      // under verbose ingestion mode so operators can verify CPU
+      // utilization moved + tune `--workers` / batch sizes without
+      // guessing. Cheap snapshot — just reads pool closure state.
+      if (verboseThroughputLog && chunkStartMs !== null) {
+        const elapsedMs = Date.now() - chunkStartMs;
+        const filesPerSec = elapsedMs > 0 ? (chunkFiles.length * 1000) / elapsedMs : 0;
+        const stats = workerPool?.getStats?.();
+        const poolFrag = stats
+          ? ` pool: ${stats.activeSlots}/${stats.size} active, ` +
+            `${stats.quarantined} quarantined${stats.poolBroken ? ', BROKEN' : ''}`
+          : ' (sequential)';
+        logger.info(
+          `📊 chunk ${chunkIdx + 1}/${numChunks}: ${chunkFiles.length} files in ${elapsedMs}ms ` +
+            `(${filesPerSec.toFixed(1)} files/s)${poolFrag}`,
+        );
+      }
     }
 
     if (isDev && parseCache && (chunkCacheHits > 0 || chunkCacheMisses > 0)) {
@@ -538,10 +679,129 @@ export async function runChunkedParseAndResolve(
       );
     }
 
+    // Deferred end-of-loop extraction (moved out of the per-chunk block):
+    //   1. processImportsFromExtracted on all chunks' imports
+    //   2. synthesizeWildcardImportBindings (if any chunk had wildcards)
+    //   3. seedCrossFileReceiverTypes on deferred calls (depends on
+    //      namedImportMap populated by step 1)
+    //   4. processHeritageFromExtracted on all chunks' heritage
+    //   5. processRoutesFromExtracted on all chunks' routes
+    // Same logic as the prior per-chunk passes, just batched — resolution
+    // sees the full repo graph instead of just current-and-earlier chunks.
+    // Deferred extraction band (M2 from PR #1693 review): the 4 stages below
+    // each get their own 5-10 point slice of the 70-95 range so percent
+    // advances monotonically through the (potentially long) resolution work
+    // instead of holding flat at 82. Stages that are skipped (zero-length
+    // input) leave their band as a no-op jump — the next stage still starts
+    // at its own band, preserving monotonicity.
+    //   imports:  70 -> 75 (5)
+    //   heritage: 75 -> 80 (5)
+    //   routes:   80 -> 85 (5)
+    //   calls:    85 -> 95 (10)
+    if (deferredWorkerImports.length > 0) {
+      await processImportsFromExtracted(
+        graph,
+        allPathObjects,
+        deferredWorkerImports,
+        ctx,
+        (current, total) => {
+          const ratio = total > 0 ? current / total : 1;
+          onProgress({
+            phase: 'parsing',
+            percent: 70 + Math.round(ratio * 5),
+            message: 'Resolving imports (all chunks)...',
+            detail: `${current}/${total} files`,
+            stats: {
+              filesProcessed: filesParsedSoFar,
+              totalFiles: totalParseable,
+              nodesCreated: graph.nodeCount,
+            },
+          });
+        },
+        repoPath,
+        importCtx,
+      );
+      // U15 (lightweight M1): processImportsFromExtracted is the sole
+      // consumer of `deferredWorkerImports`. Free the array now so the
+      // GC can reclaim the per-file ExtractedImport records before the
+      // heavier downstream stages run (heritage, routes, calls). Peak
+      // accumulator memory drops from O(repo) to O(repo - imports) for
+      // the remainder of the deferred phase. The future per-chunk
+      // streaming upgrade can rewrite this with the same correctness
+      // contract once profile data shows it's warranted.
+      deferredWorkerImports.length = 0;
+    }
+    if (anyChunkNeedsWildcardSynth) {
+      synthesizeWildcardImportBindings(graph, ctx);
+      hasSynthesized = true;
+    }
+    // L5 from PR #1693 review: populate `exportedTypeMap` from the in-progress
+    // graph BEFORE `seedCrossFileReceiverTypes` runs. Previously the seeding
+    // branch below was reached with `exportedTypeMap.size === 0` in the
+    // worker path (the map was only built at the post-parse block far below,
+    // AFTER the seeding branch), so the seed dead-coded itself silently and
+    // call resolution never got the cross-file receiver-type enrichment.
+    // The post-parse builder still runs as a defensive fallback on the
+    // sequential path; its `size === 0` guard means we don't pay the cost
+    // twice on the worker path.
+    if (exportedTypeMap.size === 0 && graph.nodeCount > 0) {
+      const graphExports = buildExportedTypeMapFromGraph(graph, ctx.model.symbols);
+      for (const [fp, exports] of graphExports) exportedTypeMap.set(fp, exports);
+    }
+    if (exportedTypeMap.size > 0 && ctx.namedImportMap.size > 0 && deferredWorkerCalls.length > 0) {
+      const { enrichedCount } = seedCrossFileReceiverTypes(
+        deferredWorkerCalls,
+        ctx.namedImportMap,
+        exportedTypeMap,
+      );
+      if (isDev && enrichedCount > 0) {
+        logger.info(`🔗 E1: Seeded ${enrichedCount} cross-file receiver types (all chunks)`);
+      }
+    }
+    if (deferredWorkerHeritage.length > 0) {
+      await processHeritageFromExtracted(graph, deferredWorkerHeritage, ctx, (current, total) => {
+        const ratio = total > 0 ? current / total : 1;
+        onProgress({
+          phase: 'parsing',
+          percent: 75 + Math.round(ratio * 5),
+          message: 'Resolving heritage (all chunks)...',
+          detail: `${current}/${total} records`,
+          stats: {
+            filesProcessed: filesParsedSoFar,
+            totalFiles: totalParseable,
+            nodesCreated: graph.nodeCount,
+          },
+        });
+      });
+    }
+    if (allExtractedRoutes.length > 0) {
+      await processRoutesFromExtracted(graph, allExtractedRoutes, ctx, (current, total) => {
+        const ratio = total > 0 ? current / total : 1;
+        onProgress({
+          phase: 'parsing',
+          percent: 80 + Math.round(ratio * 5),
+          message: 'Resolving routes (all chunks)...',
+          detail: `${current}/${total} routes`,
+          stats: {
+            filesProcessed: filesParsedSoFar,
+            totalFiles: totalParseable,
+            nodesCreated: graph.nodeCount,
+          },
+        });
+      });
+    }
+
     const fullWorkerHeritageMap =
       deferredWorkerHeritage.length > 0
         ? buildHeritageMap(deferredWorkerHeritage, ctx, getHeritageStrategyForLanguage)
         : undefined;
+    // U15 (lightweight M1): buildHeritageMap is the LAST consumer of the
+    // raw `deferredWorkerHeritage` records — processCallsFromExtracted
+    // below reads from the derived `fullWorkerHeritageMap` instead. Free
+    // the raw heritage array now so the GC can reclaim it before the
+    // (potentially long) call-resolution stage. processHeritageFromExtracted
+    // earlier was a read-only consumer (pushed to graph, didn't drain).
+    deferredWorkerHeritage.length = 0;
 
     if (deferredWorkerCalls.length > 0) {
       await processCallsFromExtracted(
@@ -549,9 +809,13 @@ export async function runChunkedParseAndResolve(
         deferredWorkerCalls,
         ctx,
         (current, total) => {
+          const ratio = total > 0 ? current / total : 1;
           onProgress({
             phase: 'parsing',
-            percent: 82,
+            // Calls is the longest deferred stage on real repos — give it the
+            // 10-point tail 85-95 so the progress bar visibly advances during
+            // call resolution instead of holding at 82 (M2).
+            percent: 85 + Math.round(ratio * 10),
             message: 'Resolving calls (all chunks)...',
             detail: `${current}/${total} files`,
             stats: {
@@ -576,6 +840,20 @@ export async function runChunkedParseAndResolve(
         bindingAccumulator,
       );
     }
+    // U15 (lightweight M1): all three arrays have had their last consumer
+    // by the time we reach this point — processCallsFromExtracted drained
+    // `deferredWorkerCalls` and read `deferredConstructorBindings`;
+    // processAssignmentsFromExtracted drained `deferredAssignments` and
+    // also read `deferredConstructorBindings`. Free them now so the
+    // function-scope references die before downstream graph-build /
+    // scope-resolution starts using its own working memory. Note: arrays
+    // returned in the function result object (allFetchCalls,
+    // allExtractedRoutes, allDecoratorRoutes, allToolDefs, allORMQueries,
+    // allParsedFiles) intentionally stay live — downstream consumers
+    // need them.
+    deferredWorkerCalls.length = 0;
+    deferredConstructorBindings.length = 0;
+    deferredAssignments.length = 0;
   } finally {
     await workerPool?.terminate();
   }
@@ -605,9 +883,11 @@ export async function runChunkedParseAndResolve(
     const cachedSequentialChunkFiles: Array<Array<{ path: string; content: string }>> = [];
     for (const chunkPaths of sequentialChunkPaths) {
       const chunkContents = await readFileContents(repoPath, chunkPaths);
-      const chunkFiles = chunkPaths
-        .filter((p) => chunkContents.has(p))
-        .map((p) => ({ path: p, content: chunkContents.get(p)! }));
+      const chunkFiles: Array<{ path: string; content: string }> = [];
+      for (const p of chunkPaths) {
+        const content = chunkContents.get(p);
+        if (content !== undefined) chunkFiles.push({ path: p, content });
+      }
       cachedSequentialChunkFiles.push(chunkFiles);
       astCache = createASTCache(chunkFiles.length);
       const sequentialHeritage = await extractExtractedHeritageFromFiles(chunkFiles, astCache);

gitnexus/src/core/ingestion/pipeline.ts

@@ -55,6 +55,16 @@ export interface PipelineOptions {
     minFiles?: number;
     minBytes?: number;
   };
+  /**
+   * @internal Test-only override for the worker script URL the pool
+   * spawns. When unset, parse-impl resolves `parse-worker.js` from the
+   * adjacent `workers/` directory (or the compiled `dist/` fallback
+   * under vitest). Integration tests use this to inject a custom
+   * worker script that deterministically triggers worker-pool
+   * resilience paths (e.g., crash-on-poison-file) — same precedent as
+   * `workerThresholdsForTest`. Do not use from production call sites.
+   */
+  workerUrlForTest?: URL;
   /**
    * Incremental-indexing parse cache. When provided:
    *   - The parse phase looks up each chunk's content hash in
@@ -68,6 +78,46 @@ export interface PipelineOptions {
    * See `gitnexus/src/storage/parse-cache.ts`.
    */
   parseCache?: import('../../storage/parse-cache.js').ParseCache;
+  /**
+   * Worker pool size override, threaded from the CLI `--workers` flag
+   * via `AnalyzeOptions`. When set, parse-impl passes this directly to
+   * `createWorkerPool` so the pool sizing bypasses the env-var fallback
+   * in `resolveAutoPoolSize`. The env-var channel
+   * (`GITNEXUS_WORKER_POOL_SIZE`) remains as a back-compat fallback when
+   * this field is undefined. Setting `workerPoolSize: 0` disables the
+   * pool entirely (sequential fallback) — equivalent to `skipWorkers`
+   * but expressed in the same units as `--workers <N>` so long-running
+   * hosts (eval-server, MCP daemon) can size per-call without leaking
+   * `process.env` state across analyze invocations.
+   */
+  workerPoolSize?: number;
+  /**
+   * Number of chunks whose file contents may be read into memory in
+   * parallel while the worker pool is busy dispatching the current
+   * chunk. Pre-fetching overlaps disk I/O for chunk N+1..N+K with the
+   * worker compute on chunk N — modest but real wall-clock win on
+   * repos large enough to chunk. Worker dispatch itself remains serial
+   * because `WorkerPool.dispatch` is not reentrant (concurrent calls
+   * would race on the shared per-slot busy/in-flight state).
+   *
+   * `1` matches today's pure-serial behavior; `2` is the documented
+   * default (`GITNEXUS_PARSE_CHUNK_CONCURRENCY`). Falls back to the
+   * env var when undefined; defaults to 2 when neither is set.
+   */
+  parseChunkConcurrency?: number;
+  /**
+   * Byte budget per parse chunk (in bytes). When set, parse-impl uses
+   * this instead of the `GITNEXUS_CHUNK_BYTE_BUDGET` env var or the
+   * built-in 2 MB default. Smaller values produce more chunks (finer
+   * cache-hit granularity, more worker dispatches); larger values
+   * batch more files per dispatch.
+   *
+   * Threading the value through options instead of the env var lets
+   * tests vary the chunk layout per-call without `vi.resetModules` and
+   * lets long-running hosts (eval-server, MCP daemon) size per-call
+   * without leaking `process.env` state across invocations.
+   */
+  chunkByteBudget?: number;
 }
 
 // ── Phase registry ─────────────────────────────────────────────────────────

gitnexus/src/core/ingestion/registry-primary-flag.ts

@@ -74,6 +74,7 @@ export const MIGRATED_LANGUAGES: ReadonlySet<SupportedLanguages> = new Set<Suppo
   SupportedLanguages.C,
   SupportedLanguages.CPlusPlus,
   SupportedLanguages.PHP,
+  SupportedLanguages.JavaScript,
 ]);
 
 /**

gitnexus/src/core/ingestion/resolve-references.ts

@@ -64,6 +64,8 @@ export interface ResolveReferencesInput {
   readonly scopes: ScopeResolutionIndexes;
   /** Provider hooks consumed by the registries (e.g. `arityCompatibility`). */
   readonly providers?: RegistryProviders;
+  /** Required owner-keyed member lookup used by Step 2 receiver/MRO walks. */
+  readonly ownedMembersByOwner: RegistryContext['ownedMembersByOwner'];
 }
 
 export interface ResolveStats {
@@ -92,6 +94,7 @@ export function resolveReferenceSites(input: ResolveReferencesInput): ResolveRef
     defs: scopes.defs,
     qualifiedNames: scopes.qualifiedNames,
     moduleScopes: scopes.moduleScopes,
+    ownedMembersByOwner: input.ownedMembersByOwner,
     methodDispatch: scopes.methodDispatch,
     providers,
   };
@@ -191,7 +194,10 @@ function lookupForSite(
     case 'write': {
       // Try field first; fall through to method then class so bare-name
       // reads of a function (e.g. `cb = save`) still resolve.
-      const fieldHits = fieldRegistry.lookup(site.name, site.inScope);
+      const fieldOpts: Parameters<FieldRegistry['lookup']>[2] = {
+        ...(site.explicitReceiver !== undefined ? { explicitReceiver: site.explicitReceiver } : {}),
+      };
+      const fieldHits = fieldRegistry.lookup(site.name, site.inScope, fieldOpts);
       if (fieldHits.length > 0) return fieldHits;
       const methodHits = methodRegistry.lookup(site.name, site.inScope);
       if (methodHits.length > 0) return methodHits;

gitnexus/src/core/ingestion/scope-extractor.ts

@@ -63,6 +63,7 @@ import type {
   BindingRef,
   CaptureMatch,
   ImportEdge,
+  ParameterTypeClass,
   ParsedFile,
   ParsedImport,
   ReferenceSite,
@@ -545,8 +546,12 @@ function buildDefFromDeclarationMatch(
   const parameterCount = parseIntCapture(match['@declaration.parameter-count']);
   const requiredParameterCount = parseIntCapture(match['@declaration.required-parameter-count']);
   const parameterTypes = parseJsonStringArrayCapture(match['@declaration.parameter-types']);
+  const parameterTypeClasses = parseJsonParameterTypeClassesCapture(
+    match['@declaration.parameter-type-classes'],
+  );
   const declaredType = match['@declaration.field-type']?.text;
   const returnType = match['@declaration.return-type']?.text;
+  const templateConstraints = parseJsonCapture(match['@declaration.template-constraints']);
 
   return {
     nodeId: makeDefId(filePath, anchor.range, type, nameCap.text),
@@ -556,18 +561,79 @@ function buildDefFromDeclarationMatch(
     ...(parameterCount !== undefined ? { parameterCount } : {}),
     ...(requiredParameterCount !== undefined ? { requiredParameterCount } : {}),
     ...(parameterTypes !== undefined ? { parameterTypes } : {}),
+    ...(parameterTypeClasses !== undefined ? { parameterTypeClasses } : {}),
     ...(declaredType !== undefined ? { declaredType } : {}),
     ...(returnType !== undefined ? { returnType } : {}),
     ...(templateArguments !== undefined ? { templateArguments } : {}),
+    ...(templateConstraints !== undefined ? { templateConstraints } : {}),
   };
 }
 
+/** Parse an opaque JSON payload synthesized by per-language captures
+ *  (e.g. C++ `@declaration.template-constraints`). Producer owns the
+ *  shape; shared code threads it through as `unknown` per the
+ *  `SymbolDefinition.templateConstraints` contract. */
+function parseJsonCapture(cap: { readonly text: string } | undefined): unknown {
+  if (cap === undefined) return undefined;
+  try {
+    return JSON.parse(cap.text);
+  } catch {
+    return undefined;
+  }
+}
+
 function parseIntCapture(cap: { readonly text: string } | undefined): number | undefined {
   if (cap === undefined) return undefined;
   const n = Number.parseInt(cap.text, 10);
   return Number.isFinite(n) ? n : undefined;
 }
 
+function parseJsonParameterTypeClassesCapture(
+  cap: { readonly text: string } | undefined,
+): ParameterTypeClass[] | undefined {
+  if (cap === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(cap.text);
+    if (!Array.isArray(parsed)) return undefined;
+    const out: ParameterTypeClass[] = [];
+    for (const item of parsed) {
+      if (item === null || typeof item !== 'object') return undefined;
+      const o = item as Record<string, unknown>;
+      if (typeof o.base !== 'string') return undefined;
+      if (
+        o.cv !== 'none' &&
+        o.cv !== 'const' &&
+        o.cv !== 'volatile' &&
+        o.cv !== 'const volatile' &&
+        o.cv !== 'unknown'
+      ) {
+        return undefined;
+      }
+      if (
+        o.indirection !== 'value' &&
+        o.indirection !== 'lvalue-ref' &&
+        o.indirection !== 'rvalue-ref' &&
+        o.indirection !== 'pointer' &&
+        o.indirection !== 'unknown'
+      ) {
+        return undefined;
+      }
+      if (typeof o.pointerDepth !== 'number' || !Number.isFinite(o.pointerDepth)) {
+        return undefined;
+      }
+      out.push({
+        base: o.base,
+        cv: o.cv,
+        indirection: o.indirection,
+        pointerDepth: o.pointerDepth,
+      });
+    }
+    return out;
+  } catch {
+    return undefined;
+  }
+}
+
 function parseJsonStringArrayCapture(
   cap: { readonly text: string } | undefined,
 ): string[] | undefined {
@@ -627,8 +693,14 @@ function normalizeNodeLabel(kindStr: string): SymbolDefinition['type'] | undefin
     case 'property':
       return 'Property';
     case 'variable':
-    case 'const':
       return 'Variable';
+    // `const` / `let` declarations align with the legacy DAG parse phase,
+    // which emits `Const` graph nodes via `@definition.const` capture for
+    // `lexical_declaration`. Returning `'Const'` here lets resolveDefGraphId's
+    // qualified-key path succeed for value receivers without relying on the
+    // simple-key fallback (PR #1718 review Finding 1 / 2026-05-21-002 U4).
+    case 'const':
+      return 'Const';
     case 'typealias':
     case 'type_alias':
       return 'TypeAlias';
@@ -847,6 +919,9 @@ function pass5CollectReferences(
     const explicitReceiver = extractExplicitReceiver(match);
     const arity = extractArity(match);
     const argumentTypes = extractArgumentTypes(match);
+    const argumentTypeClasses = parseJsonParameterTypeClassesCapture(
+      match['@reference.parameter-type-classes'],
+    );
 
     const site: ReferenceSite = {
       name: nameCap.text,
@@ -857,6 +932,7 @@ function pass5CollectReferences(
       ...(explicitReceiver !== undefined ? { explicitReceiver } : {}),
       ...(arity !== undefined ? { arity } : {}),
       ...(argumentTypes !== undefined ? { argumentTypes } : {}),
+      ...(argumentTypeClasses !== undefined ? { argumentTypeClasses } : {}),
     };
     referenceSites.push(site);
   }
@@ -974,9 +1050,12 @@ const KNOWN_SUB_TAGS: ReadonlySet<string> = new Set<string>([
   '@reference.receiver',
   '@reference.arity',
   '@reference.parameter-types',
+  '@reference.parameter-type-classes',
   '@declaration.parameter-count',
   '@declaration.required-parameter-count',
   '@declaration.parameter-types',
+  '@declaration.parameter-type-classes',
+  '@declaration.template-constraints',
 ]);
 
 /**

gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts

@@ -254,6 +254,7 @@
 import type {
   BindingRef,
   Callsite,
+  ConstraintContext,
   ParsedFile,
   ScopeId,
   SupportedLanguages,
@@ -279,6 +280,10 @@ export type LinearizeStrategy = (
 /** Result of `ScopeResolver.arityCompatibility` — mirrors `RegistryProviders.arityCompatibility`. */
 export type ArityVerdict = 'compatible' | 'unknown' | 'incompatible';
 
+/** Re-exported for ScopeResolver consumers — same shape as
+ *  `RegistryProviders.constraintCompatibility`'s third parameter. */
+export type { ConstraintContext } from 'gitnexus-shared';
+
 export interface ScopeResolver {
   /** Identity for telemetry + per-language flag check. */
   readonly language: SupportedLanguages;
@@ -374,6 +379,28 @@ export interface ScopeResolver {
    */
   arityCompatibility(callsite: Callsite, def: SymbolDefinition): ArityVerdict;
 
+  /**
+   * Per-language constraint compatibility between a callsite and a
+   * candidate `def` that carries `templateConstraints` metadata.
+   * Mirrors `arityCompatibility` semantics: the three-valued verdict
+   * MUST treat `'unknown'` as keep-candidate (monotonicity — adding
+   * a predicate can only narrow correctly, never produce a wrong
+   * edge). Consulted by `narrowOverloadCandidates` after the arity
+   * and parameter-type filters.
+   *
+   * Optional. Languages without constrained-overload semantics
+   * (SFINAE, `requires` clauses, trait bounds, conditional types)
+   * leave this undefined and the constraint filter is a pass-through.
+   *
+   * C++ is the first consumer; see `languages/cpp/constraint-filter.ts`
+   * for the Tier-A predicate registry and Kleene 3-valued evaluator.
+   */
+  readonly constraintCompatibility?: (
+    callsite: Callsite,
+    def: SymbolDefinition,
+    ctx: ConstraintContext,
+  ) => ArityVerdict;
+
   // ─── Per-language strategies ───────────────────────────────────────────────
 
   /**

gitnexus/src/core/ingestion/scope-resolution/graph-bridge/edges.ts

@@ -98,3 +98,54 @@ export function tryEmitEdge(
   });
   return true;
 }
+
+/**
+ * Variant of `tryEmitEdge` that takes a pre-resolved target graph id
+ * instead of resolving it from a `SymbolDefinition`. Used by the
+ * value-receiver-owner bridge (`receiver-bound-calls.ts` Case 5) where
+ * the picked owner-indexed method def carries no `qualifiedName` (object
+ * literals have no class owner to seed it) and therefore cannot
+ * round-trip through `resolveDefGraphId`. The def's `nodeId` IS the
+ * canonical graph node id (written by the parse phase), so the caller
+ * passes it directly.
+ *
+ * All other invariants of `tryEmitEdge` apply: dedup key shape, collapse
+ * flag honoring, edge-type mapping, caller-id resolution.
+ */
+export function tryEmitEdgeWithExplicitTargetId(
+  graph: KnowledgeGraph,
+  scopes: ScopeResolutionIndexes,
+  nodeLookup: GraphNodeLookup,
+  site: {
+    readonly inScope: ScopeId;
+    readonly atRange: { startLine: number; startCol: number };
+    readonly kind: string;
+  },
+  targetGraphId: string,
+  reason: string,
+  seen: Set<string>,
+  confidence = 0.85,
+  collapseByCallerTarget = false,
+): boolean {
+  const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup);
+  const edgeType = mapReferenceKindToEdgeType(site.kind as Reference['kind']);
+  if (callerGraphId === undefined) return false;
+  if (edgeType === undefined) return false;
+
+  const useCollapsed = collapseByCallerTarget && edgeType === 'CALLS';
+  const dedupKey = useCollapsed
+    ? `${edgeType}:${callerGraphId}->${targetGraphId}`
+    : `${edgeType}:${callerGraphId}->${targetGraphId}:${site.atRange.startLine}:${site.atRange.startCol}`;
+  if (seen.has(dedupKey)) return false;
+  seen.add(dedupKey);
+
+  graph.addRelationship({
+    id: `rel:${dedupKey}`,
+    sourceId: callerGraphId,
+    targetId: targetGraphId,
+    type: edgeType,
+    confidence,
+    reason,
+  });
+  return true;
+}

gitnexus/src/core/ingestion/scope-resolution/graph-bridge/ids.ts

@@ -21,6 +21,7 @@ import type { NodeLabel, ScopeId, SymbolDefinition } from 'gitnexus-shared';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import { generateId } from '../../../../lib/utils.js';
 import { qualifiedKey, simpleKey, type GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 /**
  * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
  * source ("caller"). A Variable / Property can be the TARGET of an
@@ -76,12 +77,31 @@ export function resolveDefGraphId(
     type?: NodeLabel;
     parameterTypes?: readonly string[];
     templateArguments?: readonly string[];
+    templateConstraints?: unknown;
   },
   nodeLookup: GraphNodeLookup,
 ): string | undefined {
   const qn = def.qualifiedName;
   if (qn === undefined || qn.length === 0) return undefined;
   if (def.type !== undefined) {
+    // SFINAE / `requires`-clause disambiguation (issue #1579) — try the
+    // constraint-fingerprinted key FIRST. Two function-template overloads
+    // with identical `parameterTypes` but mutually-exclusive SFINAE
+    // constraints route to their distinct graph nodes via this key.
+    // Must run before the parameter-types key because both overloads
+    // share the latter.
+    if (
+      (def.type === 'Function' || def.type === 'Method') &&
+      def.templateConstraints !== undefined
+    ) {
+      const cKey = qualifiedKey(
+        filePath,
+        def.type,
+        `${qn}${templateConstraintsIdTag(def.templateConstraints)}`,
+      );
+      const cHit = nodeLookup.get(cKey);
+      if (cHit !== undefined) return cHit;
+    }
     // Overload disambiguation: when the def carries parameter types,
     // try the parameter-typed key first so same-name same-arity
     // overloads route to their distinct graph nodes.

gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts

@@ -20,6 +20,7 @@
 
 import type { NodeLabel } from 'gitnexus-shared';
 import type { KnowledgeGraph } from '../../../graph/types.js';
+import { templateConstraintsIdTag } from '../../utils/template-arguments.js';
 
 export type GraphNodeLookup = ReadonlyMap<string, string>;
 
@@ -97,6 +98,21 @@ export function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup {
         // Each overload is unique — set unconditionally.
         lookup.set(pKey, node.id);
       }
+      // SFINAE / `requires`-clause disambiguation (issue #1579) — register
+      // a constraint-fingerprinted key so resolveDefGraphId can locate the
+      // correct overload by hashing the def's `templateConstraints`. Mirrors
+      // the parameter-types key but keys on the opaque constraint payload
+      // instead, separating two `process<T>` overloads whose
+      // `parameterTypes=['T']` would otherwise collide.
+      const tConstraints = (props as { templateConstraints?: unknown }).templateConstraints;
+      if (tConstraints !== undefined && (node.label === 'Function' || node.label === 'Method')) {
+        const cKey = qualifiedKey(
+          props.filePath,
+          node.label,
+          `${qualified}${templateConstraintsIdTag(tConstraints)}`,
+        );
+        lookup.set(cKey, node.id);
+      }
       if (
         (node.label === 'Class' ||
           node.label === 'Struct' ||
@@ -143,6 +159,12 @@ export function isLinkableLabel(label: NodeLabel): boolean {
     // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
     // ACCESSES edge to User's `name` Variable/Property node).
     label === 'Variable' ||
-    label === 'Property'
+    label === 'Property' ||
+    // Const is linkable so the value-receiver-owner bridge in
+    // `receiver-bound-calls.ts` Case 5 can translate the scope-resolution
+    // `Variable` def for `export const fooService = {...}` to the canonical
+    // `Const:filePath:name` graph node id, against which object-literal
+    // method symbols register their `ownerId` (PR #1718 / issue #1358).
+    label === 'Const'
   );
 }

gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts

@@ -17,12 +17,19 @@
  * generalization plan.
  */
 
-import type { ParsedFile, Reference, ScopeId, SymbolDefinition } from 'gitnexus-shared';
+import type {
+  ParameterTypeClass,
+  ParsedFile,
+  Reference,
+  ScopeId,
+  SymbolDefinition,
+} from 'gitnexus-shared';
 import type { KnowledgeGraph } from '../../../graph/types.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import type { SemanticModel } from '../../model/semantic-model.js';
 import type { WorkspaceResolutionIndex } from '../workspace-index.js';
 import type { GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import type { ScopeResolver } from '../contract/scope-resolver.js';
 import { resolveCallerGraphId, resolveDefGraphId } from '../graph-bridge/ids.js';
 import {
   findAllCallableBindingsInScope,
@@ -66,11 +73,23 @@ export function emitFreeCallFallback(
       parsedFiles: readonly ParsedFile[],
     ) => readonly SymbolDefinition[] | undefined;
     readonly conversionRankFn?: ConversionRankFn;
+    /** Optional per-language constraint hook threaded into
+     *  `narrowOverloadCandidates`. Drops candidates whose template
+     *  constraints (e.g. C++ `enable_if_t`, C++20 `requires`) provably
+     *  fail at the call site. Three-valued; `'unknown'` keeps the
+     *  candidate (monotonicity). */
+    readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
   } = {},
 ): number {
   let emitted = 0;
   const seen = new Set<string>();
 
+  // Build an O(1) simple-name -> callable defs index over scopes.defs once
+  // per pass so pickUniqueGlobalCallable doesn't re-scan defs.byId.values()
+  // per call site. Same name + callable-kind filter that the previous scan
+  // applied (see pickUniqueGlobalCallable JSDoc). Cost: O(|defs|) once.
+  const globalCallablesBySimpleName = buildGlobalCallableIndex(scopes);
+
   for (const parsed of parsedFiles) {
     for (const site of parsed.referenceSites) {
       if (site.kind !== 'call') continue;
@@ -93,13 +112,10 @@ export function emitFreeCallFallback(
       // the same name in a single class, choose the best match by
       // arity + argument types.
       if (fnDef === undefined) {
-        fnDef = pickImplicitThisOverload(
-          site,
-          scopes,
-          workspaceIndex,
-          model,
-          options.conversionRankFn,
-        );
+        fnDef = pickImplicitThisOverload(site, scopes, workspaceIndex, model, {
+          conversionRankFn: options.conversionRankFn,
+          constraintCompatibility: options.constraintCompatibility,
+        });
       }
       // Scope-chain callable lookup. First-match preserves scope-chain
       // precedence (local shadows import). When a conversion-rank function
@@ -121,7 +137,11 @@ export function emitFreeCallFallback(
                 allCallables,
                 site.arity,
                 site.argumentTypes,
-                options.conversionRankFn,
+                {
+                  argumentTypeClasses: site.argumentTypeClasses,
+                  conversionRankFn: options.conversionRankFn,
+                  constraintCompatibility: options.constraintCompatibility,
+                },
               );
               if (narrowed.length === 1) {
                 fnDef = narrowed[0];
@@ -166,37 +186,46 @@ export function emitFreeCallFallback(
                 parsedFiles,
               );
 
-          // When ADL contributed no candidates, narrow ordinary candidates
-          // with conversion-rank scoring when multiple overloads exist.
-          // Single candidate or empty falls through to first-match.
+          const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
           if (adl === undefined || adl.length === 0) {
-            if (ordinary.length <= 1 || options.conversionRankFn === undefined) {
+            // No ADL contribution. Default behavior: `ordinary[0]` —
+            // scope-chain walk preserves local-shadows-import precedence.
+            //
+            // Narrowing kicks in when either disambiguation signal is
+            // present: any candidate carries `templateConstraints`
+            // (SFINAE / `requires`-clause guarded templates, #1579), OR
+            // a conversion-rank function is provided (#1606 / #1578).
+            // Both hooks are threaded into `narrowOverloadCandidates`
+            // via the unified `OverloadNarrowingHookCtx`.
+            const hasConstraints = ordinary.some((d) => d.templateConstraints !== undefined);
+            const canNarrow = hasConstraints || options.conversionRankFn !== undefined;
+            if (ordinary.length <= 1 || !canNarrow) {
               fnDef = ordinary[0];
             } else {
-              const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
-              const narrowed = narrowOverloadCandidates(
-                ordinary,
-                site.arity,
-                site.argumentTypes,
-                options.conversionRankFn,
-              );
+              const narrowed = narrowOverloadCandidates(ordinary, site.arity, site.argumentTypes, {
+                argumentTypeClasses: site.argumentTypeClasses,
+                conversionRankFn: options.conversionRankFn,
+                constraintCompatibility: options.constraintCompatibility,
+              });
               if (narrowed.length === 1) {
                 fnDef = narrowed[0];
-              } else if (narrowed.length > 1) {
-                // Multiple survivors — suppress when same-file (true
-                // overloads), mirrors ADL merged-candidate behavior.
+              } else if (narrowed.length === 0) {
+                handledSites.add(siteKey);
+                continue;
+              } else {
+                // >1 survivors: same-file → suppress (true overloads,
+                // "degrade not lie" — no edge beats a wrong one, and
+                // SFINAE-ambiguous calls land here). Cross-file →
+                // first-match (shadowing semantics).
                 const sameFile = narrowed.every((d) => d.filePath === narrowed[0]!.filePath);
                 if (sameFile) {
                   handledSites.add(siteKey);
                   continue;
                 }
-                fnDef = ordinary[0]; // cross-file shadowing → first-match
-              } else {
-                fnDef = ordinary[0]; // narrowed empty → first-match
+                fnDef = ordinary[0];
               }
             }
           } else {
-            const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`;
             const merged: SymbolDefinition[] = [];
             const seenMerge = new Set<string>();
             const push = (defs: readonly SymbolDefinition[]): void => {
@@ -209,12 +238,11 @@ export function emitFreeCallFallback(
             push(ordinary);
             push(adl);
 
-            const narrowed = narrowOverloadCandidates(
-              merged,
-              site.arity,
-              site.argumentTypes,
-              options.conversionRankFn,
-            );
+            const narrowed = narrowOverloadCandidates(merged, site.arity, site.argumentTypes, {
+              argumentTypeClasses: site.argumentTypeClasses,
+              conversionRankFn: options.conversionRankFn,
+              constraintCompatibility: options.constraintCompatibility,
+            });
             if (narrowed.length === 1) {
               fnDef = narrowed[0];
             } else if (narrowed.length === 0) {
@@ -241,7 +269,7 @@ export function emitFreeCallFallback(
         fnDef = pickUniqueGlobalCallable(
           site.name,
           model,
-          scopes,
+          globalCallablesBySimpleName,
           parsed.filePath,
           options.isFileLocalDef,
           site.arity,
@@ -255,6 +283,7 @@ export function emitFreeCallFallback(
                 })
             : undefined,
           site.argumentTypes,
+          site.argumentTypeClasses,
           options.conversionRankFn,
         );
       }
@@ -286,23 +315,46 @@ export function emitFreeCallFallback(
   return emitted;
 }
 
+/**
+ * Build a `simpleName -> callable defs` index from `scopes.defs` once per
+ * pass. Mirrors the filter the old per-site scan applied: Function /
+ * Method / Constructor, keyed by the last `.`-segment of `qualifiedName`
+ * (falling back to the qualifiedName itself when undotted). Used by
+ * `pickUniqueGlobalCallable` so every free-call fallback site is O(1)
+ * instead of O(|defs|).
+ */
+function buildGlobalCallableIndex(
+  scopes: ScopeResolutionIndexes,
+): ReadonlyMap<string, readonly SymbolDefinition[]> {
+  const out = new Map<string, SymbolDefinition[]>();
+  for (const def of scopes.defs.byId.values()) {
+    if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') continue;
+    const qualified = def.qualifiedName;
+    if (qualified === undefined || qualified.length === 0) continue;
+    const dot = qualified.lastIndexOf('.');
+    const simple = dot === -1 ? qualified : qualified.slice(dot + 1);
+    const bucket = out.get(simple);
+    if (bucket) bucket.push(def);
+    else out.set(simple, [def]);
+  }
+  return out;
+}
+
 function pickUniqueGlobalCallable(
   name: string,
   model: SemanticModel,
-  scopes: ScopeResolutionIndexes,
+  globalCallablesBySimpleName: ReadonlyMap<string, readonly SymbolDefinition[]>,
   callerFilePath: string,
   isFileLocalDef?: (def: SymbolDefinition) => boolean,
   callArity?: number,
   isCallerVisible?: (candidate: SymbolDefinition) => boolean,
   callArgTypes?: readonly string[],
+  callArgTypeClasses?: readonly ParameterTypeClass[],
   conversionRankFn?: ConversionRankFn,
 ): SymbolDefinition | undefined {
   const scopeDefs: SymbolDefinition[] = [];
   const scopeSeen = new Set<string>();
-  for (const def of scopes.defs.byId.values()) {
-    const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName;
-    if (simple !== name) continue;
-    if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') continue;
+  for (const def of globalCallablesBySimpleName.get(name) ?? []) {
     // Skip file-local defs (e.g. C `static` functions) that live in a
     // different file from the caller — they are logically invisible.
     if (isFileLocalDef !== undefined && def.filePath !== callerFilePath && isFileLocalDef(def)) {
@@ -335,7 +387,10 @@ function pickUniqueGlobalCallable(
   // best-rank candidate when exact-type or conversion-rank scoring can
   // disambiguate (e.g., `f(int)` vs `f(double)` called with `f(2.5)`).
   if (scopeDefs.length > 1) {
-    const narrowed = narrowOverloadCandidates(scopeDefs, callArity, callArgTypes, conversionRankFn);
+    const narrowed = narrowOverloadCandidates(scopeDefs, callArity, callArgTypes, {
+      argumentTypeClasses: callArgTypeClasses,
+      conversionRankFn,
+    });
     if (narrowed.length === 1) return narrowed[0];
   }
 
@@ -373,7 +428,10 @@ function pickUniqueGlobalCallable(
   }
   // Same argument-type + conversion-rank narrowing for the model pool.
   if (defs.length > 1) {
-    const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, conversionRankFn);
+    const narrowed = narrowOverloadCandidates(defs, callArity, callArgTypes, {
+      argumentTypeClasses: callArgTypeClasses,
+      conversionRankFn,
+    });
     if (narrowed.length === 1) return narrowed[0];
   }
 
@@ -445,11 +503,15 @@ export function pickImplicitThisOverload(
     readonly name: string;
     readonly arity?: number;
     readonly argumentTypes?: readonly string[];
+    readonly argumentTypeClasses?: readonly import('gitnexus-shared').ParameterTypeClass[];
   },
   scopes: ScopeResolutionIndexes,
   workspaceIndex: WorkspaceResolutionIndex,
   model: SemanticModel,
-  conversionRankFn?: ConversionRankFn,
+  hookCtx?: {
+    readonly conversionRankFn?: ConversionRankFn;
+    readonly constraintCompatibility?: ScopeResolver['constraintCompatibility'];
+  },
 ): SymbolDefinition | undefined {
   // Find the enclosing Class scope by walking parents.
   let curId: ScopeId | null = site.inScope;
@@ -477,12 +539,11 @@ export function pickImplicitThisOverload(
   // ambiguous narrowing (multiple compatible candidates with no
   // disambiguating signal) leaves the call unresolved rather than
   // routing to an arbitrary first overload by registration order.
-  const candidates = narrowOverloadCandidates(
-    overloads,
-    site.arity,
-    site.argumentTypes,
-    conversionRankFn,
-  );
+  const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes, {
+    argumentTypeClasses: site.argumentTypeClasses,
+    conversionRankFn: hookCtx?.conversionRankFn,
+    constraintCompatibility: hookCtx?.constraintCompatibility,
+  });
   if (candidates.length !== 1) return undefined;
   return candidates[0];
 }

gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts

@@ -25,15 +25,26 @@
  *      counts as a match. Mismatches disqualify. A non-empty typed
  *      result wins; otherwise return the arity-filtered candidates.
  *   4b. When the exact-type filter from step 4 returns empty AND a
- *       `conversionRankFn` is provided, rank candidates via pairwise
- *       dominance comparison (ISO C++ [over.ics.rank]): F1 beats F2
- *       only when F1 is not worse for every arg and better for at
- *       least one. Non-dominated candidates are returned; multiple
- *       survivors are genuinely ambiguous.
+ *       `conversionRankFn` is provided (via `hookCtx`), rank candidates
+ *       via pairwise dominance comparison (ISO C++ [over.ics.rank]):
+ *       F1 beats F2 only when F1 is not worse for every arg and better
+ *       for at least one. Non-dominated candidates are returned;
+ *       multiple survivors are genuinely ambiguous.
+ *   4c. Final per-candidate constraint filter (SFINAE / `requires`).
+ *       When `constraintCompatibility` is provided via `hookCtx`, drop
+ *       candidates whose template constraints provably fail at the
+ *       call site. Three-valued; `'unknown'` keeps the candidate
+ *       (monotonicity).
  *   5. Empty input returns empty output.
  */
 
-import type { SymbolDefinition } from 'gitnexus-shared';
+import type {
+  ArityVerdict,
+  Callsite,
+  ConstraintContext,
+  ParameterTypeClass,
+  SymbolDefinition,
+} from 'gitnexus-shared';
 
 /**
  * Per-slot conversion-rank function. Returns a numeric cost for
@@ -46,13 +57,43 @@ import type { SymbolDefinition } from 'gitnexus-shared';
  * Each language provides its own implementation. The function operates
  * on normalized type strings (output of the language's type normalizer).
  */
-export type ConversionRankFn = (argType: string, paramType: string) => number;
+export type ConversionRankFn = (
+  argType: string,
+  paramType: string,
+  argTypeClass?: ParameterTypeClass,
+  paramTypeClass?: ParameterTypeClass,
+) => number;
+
+/**
+ * Optional hook bundle for narrowing extension points. Threaded in
+ * from `pickOverload` / `pickImplicitThisOverload` so per-language
+ * narrowing can layer in conversion-rank scoring (#1606) and
+ * constraint filtering (#1579) without changing the call signature
+ * at every site. Each hook is independently optional — leaving both
+ * undefined preserves the legacy arity + exact-type behavior.
+ */
+export interface OverloadNarrowingHookCtx {
+  /** Shape-preserving per-argument sidecar aligned with `argTypes`. */
+  readonly argumentTypeClasses?: ConstraintContext['argumentTypeClasses'];
+  /** Conversion-rank scoring fallback (step 4b). Engages when the
+   *  exact-type filter rejects every candidate. */
+  readonly conversionRankFn?: ConversionRankFn;
+  /** Constraint filter (step 4c). Drops candidates whose template
+   *  guards (SFINAE `enable_if_t`, C++20 `requires`, future Rust
+   *  trait bounds, etc.) provably fail at the call site. Three-valued
+   *  — `'unknown'` keeps the candidate (monotonicity). */
+  readonly constraintCompatibility?: (
+    callsite: Callsite,
+    def: SymbolDefinition,
+    ctx: ConstraintContext,
+  ) => ArityVerdict;
+}
 
 export function narrowOverloadCandidates(
   overloads: readonly SymbolDefinition[],
   argCount: number | undefined,
   argTypes: readonly string[] | undefined,
-  conversionRankFn?: ConversionRankFn,
+  hookCtx?: OverloadNarrowingHookCtx,
 ): readonly SymbolDefinition[] {
   if (overloads.length === 0) return [];
 
@@ -93,31 +134,99 @@ export function narrowOverloadCandidates(
   const candidates: readonly SymbolDefinition[] =
     arityMatches.length > 0 ? arityMatches : anyUnknownBounds ? overloads : [];
 
+  let result: readonly SymbolDefinition[] = candidates;
   if (argTypes !== undefined && argTypes.length > 0) {
     const typed = candidates.filter((d) => {
       const params = d.parameterTypes;
       if (params === undefined) return false;
       for (let i = 0; i < argTypes.length && i < params.length; i++) {
         if (argTypes[i] === '') continue;
-        if (argTypes[i] !== params[i]) return false;
+        if (
+          !exactTypeSlotMatches(
+            argTypes[i],
+            params[i],
+            hookCtx?.argumentTypeClasses?.[i],
+            d.parameterTypeClasses?.[i],
+          )
+        ) {
+          return false;
+        }
       }
       return true;
     });
-    if (typed.length > 0) return typed;
-
-    // ── Conversion-rank scoring (step 4b) ──────────────────────────
-    // The exact-type filter above rejected every candidate. When a
-    // per-language conversion-rank function is available, rank via
-    // pairwise dominance: F1 beats F2 only when F1 is not worse for
-    // every arg and better for at least one. Non-dominated candidates
-    // are returned; multiple survivors are genuinely ambiguous.
-    if (conversionRankFn !== undefined) {
-      const ranked = rankByConversion(candidates, argTypes, conversionRankFn);
-      if (ranked.length > 0) return ranked;
+    if (typed.length > 0) {
+      result = typed;
+    } else if (hookCtx?.conversionRankFn !== undefined) {
+      // ── Conversion-rank scoring (step 4b) ──────────────────────────
+      // The exact-type filter rejected every candidate. Rank via
+      // pairwise dominance: F1 beats F2 only when F1 is not worse for
+      // every arg and better for at least one. Non-dominated candidates
+      // are returned; multiple survivors are genuinely ambiguous. When
+      // ranking also yields empty, fall through to the arity-filtered
+      // `candidates` set — matches pre-#1606 behavior.
+      const ranked = rankByConversion(
+        candidates,
+        argTypes,
+        hookCtx.conversionRankFn,
+        hookCtx.argumentTypeClasses,
+      );
+      if (ranked.length > 0) result = ranked;
     }
   }
 
-  return candidates;
+  // Constraint filter (step 4c; Tier-A — SFINAE / `requires` clauses).
+  // Runs after arity, exact-type, and conversion-rank filters so the
+  // hook only sees candidates already viable on the other axes.
+  // Three-valued: `'compatible'` and `'unknown'` keep the candidate
+  // (monotonicity — adding a predicate must never cause a wrong edge);
+  // only `'incompatible'` drops it. Candidates without
+  // `templateConstraints` are always kept.
+  //
+  // No fallback to the unconstrained set when this filter empties the
+  // candidate list: a fully-`'incompatible'` verdict is authoritative.
+  // The downstream `OVERLOAD_AMBIGUOUS` sentinel still guards the empty
+  // case, so a buggy hook that wrongly returns `'incompatible'` for
+  // every candidate degrades to today's "suppress edge" behavior rather
+  // than emitting a wrong edge.
+  if (hookCtx?.constraintCompatibility !== undefined && argCount !== undefined) {
+    const callsite: Callsite = { arity: argCount };
+    const ctx: ConstraintContext =
+      argTypes !== undefined
+        ? {
+            argumentTypes: argTypes,
+            ...(hookCtx.argumentTypeClasses !== undefined
+              ? { argumentTypeClasses: hookCtx.argumentTypeClasses }
+              : {}),
+          }
+        : {};
+    result = result.filter((def) => {
+      if (def.templateConstraints === undefined) return true;
+      return hookCtx.constraintCompatibility!(callsite, def, ctx) !== 'incompatible';
+    });
+  }
+
+  return result;
+}
+
+function exactTypeSlotMatches(
+  argType: string,
+  paramType: string,
+  argTypeClass?: ParameterTypeClass,
+  paramTypeClass?: ParameterTypeClass,
+): boolean {
+  if (argType !== paramType) return false;
+  // C++ normalizes away pointer markers (`int*` -> `int`). When both sides
+  // provide shape sidecars, do not let that collapse make `int` exactly match
+  // `int*`. Unknown sidecar evidence preserves the previous string-only path.
+  if (argTypeClass === undefined || paramTypeClass === undefined) return true;
+  if (argTypeClass.indirection === 'unknown' || paramTypeClass.indirection === 'unknown') {
+    return true;
+  }
+  return isPointerShape(argTypeClass) === isPointerShape(paramTypeClass);
+}
+
+function isPointerShape(typeClass: ParameterTypeClass): boolean {
+  return typeClass.indirection === 'pointer' && typeClass.pointerDepth > 0;
 }
 
 /**
@@ -136,6 +245,7 @@ function rankByConversion(
   candidates: readonly SymbolDefinition[],
   argTypes: readonly string[],
   rankFn: ConversionRankFn,
+  argTypeClasses?: readonly ParameterTypeClass[],
 ): readonly SymbolDefinition[] {
   // Step 1: compute per-slot ranks and exclude non-viable candidates.
   const viable: Array<{ def: SymbolDefinition; ranks: number[] }> = [];
@@ -144,12 +254,22 @@ function rankByConversion(
     if (params === undefined) continue;
     const ranks: number[] = [];
     let ok = true;
-    for (let i = 0; i < argTypes.length && i < params.length; i++) {
+    for (let i = 0; i < argTypes.length; i++) {
+      const paramType = parameterTypeAt(params, i);
+      if (paramType === undefined) {
+        ok = false;
+        break;
+      }
       if (argTypes[i] === '') {
         ranks.push(0); // unknown arg → any-match (rank 0)
         continue;
       }
-      const r = rankFn(argTypes[i], params[i]);
+      const r = rankFn(
+        argTypes[i],
+        paramType,
+        argTypeClasses?.[i],
+        parameterTypeClassAt(d.parameterTypeClasses, i),
+      );
       if (!isFinite(r)) {
         ok = false;
         break;
@@ -176,6 +296,20 @@ function rankByConversion(
   return viable.filter((_, idx) => !dominated.has(idx)).map((v) => v.def);
 }
 
+function parameterTypeAt(params: readonly string[], argIndex: number): string | undefined {
+  if (argIndex < params.length) return params[argIndex];
+  return params[params.length - 1] === '...' ? '...' : undefined;
+}
+
+function parameterTypeClassAt(
+  params: readonly ParameterTypeClass[] | undefined,
+  argIndex: number,
+): ParameterTypeClass | undefined {
+  if (params === undefined) return undefined;
+  if (argIndex < params.length) return params[argIndex];
+  return params[params.length - 1]?.base === '...' ? params[params.length - 1] : undefined;
+}
+
 /**
  * Compare two per-slot rank vectors.
  * Returns  -1 if `a` dominates `b` (not worse everywhere, better somewhere),

gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts

@@ -21,6 +21,11 @@
  *      but not a namespace prefix → compound resolver
  *   7. **Case 4 (simple typeBinding)** — `typeRef.rawName` has no dot →
  *      MRO walk + `findOwnedMember`
+ *   8. **Case 5 (value-receiver bridge)** — receiver is a `Const`/`Variable`
+ *      whose `nodeId` is referenced as an `ownerId` in `model.methods`
+ *      (object-literal services). Last-resort fallback for lowercase
+ *      receivers with no class-like or type-binding match. Mirrors
+ *      the legacy DAG bridge in `call-processor.ts`.
  *
  * Reordering or merging cases changes resolution semantics.
  *
@@ -46,9 +51,10 @@ import {
   findExportedDef,
   findOwnedMember,
   findReceiverTypeBinding,
+  findValueBindingInScope,
   isClassLike,
 } from '../scope/walkers.js';
-import { tryEmitEdge } from '../graph-bridge/edges.js';
+import { tryEmitEdge, tryEmitEdgeWithExplicitTargetId } from '../graph-bridge/edges.js';
 import { resolveCompoundReceiverClass } from '../passes/compound-receiver.js';
 import { resolveDefGraphId } from '../graph-bridge/ids.js';
 import {
@@ -74,6 +80,7 @@ type ReceiverBoundProviderSubset = Pick<
   | 'resolveQualifiedReceiverMember'
   | 'resolveThisViaEnclosingClass'
   | 'conversionRankFn'
+  | 'constraintCompatibility'
 >;
 
 function normalizeTemplateArgToken(value: string): string {
@@ -344,7 +351,11 @@ export function emitReceiverBoundCalls(
                 methodOverloads,
                 site.arity,
                 site.argumentTypes,
-                provider.conversionRankFn,
+                {
+                  argumentTypeClasses: site.argumentTypeClasses,
+                  conversionRankFn: provider.conversionRankFn,
+                  constraintCompatibility: provider.constraintCompatibility,
+                },
               );
               if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) {
                 ambiguous = true;
@@ -648,13 +659,7 @@ export function emitReceiverBoundCalls(
           let memberDef: SymbolDefinition | undefined;
           let ambiguous = false;
           for (const ownerId of chain) {
-            const picked = pickOverload(
-              ownerId,
-              memberName,
-              site,
-              model,
-              provider.conversionRankFn,
-            );
+            const picked = pickOverload(ownerId, memberName, site, model, provider);
             if (picked === OVERLOAD_AMBIGUOUS) {
               ambiguous = true;
               break;
@@ -707,6 +712,61 @@ export function emitReceiverBoundCalls(
           }
         }
       }
+
+      // ── Case 5: value-receiver bridge (object-literal services) ──
+      // When prior cases couldn't resolve the receiver as a class or
+      // type binding, fall back to value-binding resolution. Covers:
+      //
+      //   export const fooService = { getUser(id) {...} };
+      //   import { fooService } from './service';
+      //   fooService.getUser(id);   // ← resolve here
+      //
+      // `fooService` is a `Const`/`Variable` (not class-like, no typeBinding
+      // for unannotated literals), so Cases 2-4 skip it. Scope-resolution
+      // defs for non-class values carry a synthetic id, so we translate to
+      // the canonical graph node ID via `resolveDefGraphId` before owner-
+      // indexed lookup — the parser writes the graph node ID as `ownerId`
+      // on the method symbol-table entry to match.
+      //
+      // Object-literal methods do not carry a `qualifiedName` (no class
+      // owner to seed it), so the picked def cannot round-trip through
+      // `tryEmitEdge` → `resolveDefGraphId`. We use
+      // `tryEmitEdgeWithExplicitTargetId` instead, passing `picked.nodeId`
+      // directly — same dedup-key shape, collapse-flag honoring, and
+      // caller resolution as `tryEmitEdge`.
+      const valueDef = findValueBindingInScope(site.inScope, receiverName, scopes);
+      if (valueDef !== undefined) {
+        const ownerGraphId =
+          resolveDefGraphId(valueDef.filePath, valueDef, nodeLookup) ?? valueDef.nodeId;
+        const picked = pickOverload(ownerGraphId, memberName, site, model, provider);
+        if (picked === OVERLOAD_AMBIGUOUS) {
+          handledSites.add(siteKey);
+          continue;
+        }
+        if (picked !== undefined) {
+          const reason =
+            site.kind === 'write' || site.kind === 'read'
+              ? site.kind
+              : picked.filePath !== parsed.filePath
+                ? 'import-resolved'
+                : 'global';
+          const confidence = site.kind === 'write' || site.kind === 'read' ? 1.0 : 0.85;
+          const ok = tryEmitEdgeWithExplicitTargetId(
+            graph,
+            scopes,
+            nodeLookup,
+            site,
+            picked.nodeId,
+            reason,
+            seen,
+            confidence,
+            collapse,
+          );
+          if (ok) emitted++;
+          handledSites.add(siteKey);
+          continue;
+        }
+      }
     }
   }
 
@@ -722,7 +782,7 @@ function pickOverload(
   memberName: string,
   site: ParsedFile['referenceSites'][number],
   model: SemanticModel,
-  conversionRankFn?: (argType: string, paramType: string) => number,
+  provider: ReceiverBoundProviderSubset,
 ): SymbolDefinition | typeof OVERLOAD_AMBIGUOUS | undefined {
   const overloads = model.methods.lookupAllByOwner(ownerId, memberName);
   if (overloads.length === 0) {
@@ -733,12 +793,11 @@ function pickOverload(
   }
   if (overloads.length === 1) return overloads[0];
 
-  const candidates = narrowOverloadCandidates(
-    overloads,
-    site.arity,
-    site.argumentTypes,
-    conversionRankFn,
-  );
+  const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes, {
+    argumentTypeClasses: site.argumentTypeClasses,
+    conversionRankFn: provider.conversionRankFn,
+    constraintCompatibility: provider.constraintCompatibility,
+  });
   // When narrowing leaves >1 candidate that share identical normalized
   // parameter-types (e.g., C++ `f(int)` vs `f(long)` both collapsed to
   // `['int']` by `normalizeCppParamType`), suppress the edge entirely.