diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml
new file mode 100644
index 0000000..ced9065
--- /dev/null
+++ b/.github/workflows/bench.yml
@@ -0,0 +1,122 @@
+# Performance benchmarks -- INFORMATIONAL ONLY.
+#
+# This workflow never fails on a timing. There are deliberately no thresholds,
+# no regression gates and no "must not be slower than" comparisons, because
+# GitHub's shared runners cannot support one: the CPU model varies between jobs,
+# the host is shared with other tenants, and run-to-run noise on the same commit
+# routinely reaches tens of percent. A gate built on that would either fire
+# constantly on noise or be set so loose it catches nothing, and either way the
+# first thing anyone would do is start ignoring it.
+#
+# What it IS for: producing a benchmark artifact on demand, from a known commit,
+# with a known input, so a human can download two of them and compare. When a
+# number matters, run `benchmarks/run_all.sh` on one machine against both
+# branches back to back -- see docs/features/benchmarking.md.
+
+name: bench
+
+on:
+  workflow_dispatch:
+    inputs:
+      preset:
+        description: "Synthetic repo size for the harness"
+        required: false
+        default: medium
+        type: choice
+        options: [small, medium, large]
+  pull_request:
+    types: [labeled, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  bench:
+    # On a PR, only when it carries the `bench` label; always on manual dispatch.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      contains(github.event.pull_request.labels.*.name, 'bench')
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ". -> target"
+
+      - name: Build harness
+        run: cargo build --release --example perf_harness -p cc-core
+
+      - name: Generate synthetic repo
+        env:
+          PRESET: ${{ github.event.inputs.preset || 'medium' }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/bench-repos"
+          python3 benchmarks/gen_repo.py \
+            --preset "$PRESET" \
+            --out "$RUNNER_TEMP/bench-repos/cc-$PRESET" \
+            --force
+
+      - name: Run end-to-end harness
+        env:
+          PRESET: ${{ github.event.inputs.preset || 'medium' }}
+        run: |
+          mkdir -p bench-results
+          ./target/release/examples/perf_harness \
+            --repo "$RUNNER_TEMP/bench-repos/cc-$PRESET" \
+            --label "${GITHUB_REF_NAME}/${PRESET}" \
+            --out bench-results/harness-synthetic.json
+
+      - name: Run end-to-end harness on this repo
+        run: |
+          ./target/release/examples/perf_harness \
+            --repo . \
+            --label "${GITHUB_REF_NAME}/self" \
+            --out bench-results/harness-self.json
+
+      # Reduced sampling: enough to see an order of magnitude, cheap enough to
+      # finish inside the job timeout. Not enough for a small-percentage claim --
+      # which is fine, because this workflow does not make one.
+      - name: Run criterion
+        run: |
+          cargo bench -p cc-core -- \
+            --warm-up-time 1 --measurement-time 2 --sample-size 10 \
+            | tee bench-results/criterion.txt
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install frontend deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Run edge-routing benchmark
+        working-directory: packages/app
+        run: |
+          node benchmarks/edgeRouting.bench.ts \
+            --label "${GITHUB_REF_NAME}" \
+            --sizes 300x200,800x500 \
+            --reps 3 \
+            --json ../../bench-results/edge-routing.json
+
+      - name: Collect criterion raw estimates
+        if: always()
+        run: |
+          if [ -d target/criterion ]; then
+            tar -czf bench-results/criterion-raw.tar.gz target/criterion
+          fi
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: bench-${{ github.sha }}
+          path: bench-results/
+          retention-days: 30
diff --git a/benchmarks/RESULTS.md b/benchmarks/RESULTS.md
new file mode 100644
index 0000000..1a168c9
--- /dev/null
+++ b/benchmarks/RESULTS.md
@@ -0,0 +1,360 @@
+# `main` vs `feat/perf-integration` -- measured
+
+One machine, sequential runs, same inputs. Method and caveats are stated before
+the numbers because several of them change what the numbers mean.
+
+- **Baseline**: `origin/main` @ `30ab9b5` (2026-08-02)
+- **Branch**: `origin/feat/perf-integration` @ `1e8903e` (2026-08-11), PR #51
+- **Measured from**: `test/perf-benchmarks` @ `ab94907`, whose benchmark files
+  were copied UNCOMMITTED into a detached `main` worktree so both sides run
+  byte-identical measurement code. No source patch was needed: the harness and
+  both bench files compile unchanged on `main`. The only extra file copied in was
+  `crates/cc-core/Cargo.toml`, for its `[lib] bench = false` line (without it
+  `cargo bench -p cc-core -- <criterion flags>` fails before running anything).
+
+## Environment
+
+| | |
+| --- | --- |
+| CPU | AMD Ryzen 7 7840U (8 cores / 16 threads, 3.30 GHz max) |
+| Memory | 60 GiB |
+| OS | Ubuntu 26.04 LTS, Linux 7.0.0-29-generic x86_64 |
+| Rust | rustc 1.99.0-nightly (8ab9fdff5 2026-07-30) |
+| Node | v24.10.0 |
+| Python | 3.14.4 |
+
+Laptop CPU with boost and thermal headroom in play: treat sub-5% differences as
+noise. The frontend control scenario below shows the actual run-to-run agreement
+achieved (under 1%).
+
+## Build profiles -- read this before the criterion table
+
+`cargo bench` inherits from `[profile.release]`, and the branch changes it:
+
+| | `main` | `feat/perf-integration` |
+| --- | --- | --- |
+| `[profile.release]` | cargo defaults (`lto = false`, `codegen-units = 16`) | `lto = "thin"`, `codegen-units = 1` |
+
+That asymmetry is real shipping behaviour, so the primary comparison keeps it.
+But it inflates every number, including ones the branch did not touch, so there
+is also a **profile-matched** column: the branch re-benched with
+`CARGO_PROFILE_BENCH_LTO=false CARGO_PROFILE_BENCH_CODEGEN_UNITS=16`. The gap
+between the two columns is the build flags; what survives in the matched column
+is the algorithm.
+
+The matched column reads as a control: every benchmark the branch did not touch
+lands within ±2% (`add_edge_unique`, `add_edge_mixed`, `rebuild_adjacency`,
+`extract_many_files`, `full_pipeline`), while the targeted ones keep their full
+win. The 5-8% that those untouched benchmarks show in the shipping column is
+thin LTO, not a change in the code.
+
+## Exact commands
+
+```bash
+# Inputs, generated once, outside both checkouts
+for p in small medium large; do
+  python3 benchmarks/gen_repo.py --preset $p --out "$BENCH/cc-$p" --force
+done
+
+# Baseline
+git worktree add --detach "$BENCH/main-baseline" origin/main
+#   ... copy benchmarks/, crates/cc-core/examples/, crates/cc-core/benches/,
+#       packages/app/benchmarks/ and crates/cc-core/Cargo.toml in, uncommitted
+cd "$BENCH/main-baseline" && pnpm install --dir packages/app
+bash benchmarks/run_all.sh main "$BENCH/results/main" "$BENCH" "$BENCH/main-baseline"
+
+# Branch
+bash benchmarks/run_all.sh perf-integration "$BENCH/results/integration" \
+  "$BENCH" "$BENCH/main-baseline"
+
+# Profile-matched criterion re-run on the branch
+CARGO_PROFILE_BENCH_LTO=false CARGO_PROFILE_BENCH_CODEGEN_UNITS=16 \
+  cargo bench -p cc-core -- --warm-up-time 1 --measurement-time 3 --sample-size 20
+```
+
+Both harness runs point at the SAME real-repo path (`$BENCH/main-baseline`), so
+the "real repo" case reads an identical source tree on both sides. Synthetic
+repos come from the same seed (`20240611`) and are byte-identical.
+
+Criterion: `--warm-up-time 1 --measurement-time 3 --sample-size 20`; groups that
+set their own sampling (the newer, heavier ones) keep it at 20 samples / 3 s.
+
+---
+
+# Headline
+
+| Metric | `main` | `feat/perf-integration` | Delta |
+| --- | --- | --- | --- |
+| Open a 10k-file repo, full pipeline | 10 750 ms | 3 068 ms | **-71.5%** |
+| ...of which symbol resolution | 8 435 ms | 789 ms | **-90.6%** |
+| 200 neighborhood queries (10k-file repo) | 24 147 ms | 6 170 ms | **-74.4%** |
+| Subgraph battery, 24 extractions (10k-file repo) | 14 021 ms | 11 331 ms | -19.2% |
+| 50 edge-detail drill-ins (10k-file repo) | 12 686 ms | 7 185 ms | -43.4% |
+| Parse payload, 10k-file repo | 69.61 MB | 64.21 MB | -7.8% |
+| Canvas redraw, 1500 nodes / 1200 edges | 3 643 ms | ~0 ms (routing skipped) | **-100%** |
+| Canvas redraw, 800 nodes / 500 edges | 789 ms | 136 ms | **-82.7%** |
+
+---
+
+## 1. End-to-end harness
+
+`crates/cc-core/examples/perf_harness.rs`, release build, seed 20240611.
+Subgraph render sets are measured 6x each; `steady` is the mean of samples 2-6.
+
+### 1a. Synthetic `large` -- 11 365 files, 142 730 nodes, 374 703 edges, 950 000 raw refs
+
+| Metric | `main` | branch | Delta |
+| --- | --- | --- | --- |
+| scan | 131.5 ms | 128.8 ms | -2.1% |
+| parse files (rayon) | 741.9 ms | 676.4 ms | -8.8% |
+| merge blocks | 238.9 ms | 228.3 ms | -4.5% |
+| build symbol table | 533.9 ms | 567.4 ms | +6.3% |
+| resolve imports | 104.4 ms | 118.0 ms | +12.9% |
+| insert import edges | 46.3 ms | 49.9 ms | +7.8% |
+| **resolve symbols** | **8 434.7 ms** | **789.2 ms** | **-90.6%** |
+| insert symbol edges | 518.4 ms | 509.8 ms | -1.7% |
+| **pipeline total** | **10 750.1 ms** | **3 067.8 ms** | **-71.5%** |
+| payload bytes | 69.61 MB | 64.21 MB | -7.8% |
+| payload build | 285.7 ms | 174.4 ms | -39.0% |
+| payload serialize | 144.0 ms | 217.4 ms | **+51.0%** |
+| payload build + serialize | 429.7 ms | 391.8 ms | -8.8% |
+| subgraph battery (4 render sets x 6) | 14 021.2 ms | 11 330.7 ms | -19.2% |
+| &nbsp;&nbsp;directories_only (1 365 render nodes), steady | 591.7 ms | 481.9 ms | -18.6% |
+| &nbsp;&nbsp;directories_and_files (12 730), steady | 558.4 ms | 446.0 ms | -20.1% |
+| &nbsp;&nbsp;quarter_of_files_expanded (32 770), steady | 651.4 ms | 512.2 ms | -21.4% |
+| &nbsp;&nbsp;fully_expanded (142 730), steady | 538.6 ms | 436.0 ms | -19.1% |
+| neighborhood x200, depth 2 | 24 146.5 ms | 6 169.9 ms | **-74.4%** |
+| edge_detail x50 | 12 685.8 ms | 7 184.5 ms | -43.4% |
+
+### 1b. Synthetic `medium` -- 2 333 files, 28 666 nodes, 75 451 edges
+
+| Metric | `main` | branch | Delta |
+| --- | --- | --- | --- |
+| resolve symbols | 331.4 ms | 143.0 ms | -56.8% |
+| pipeline total | 744.4 ms | 542.2 ms | -27.2% |
+| payload bytes | 12.73 MB | 11.66 MB | -8.4% |
+| payload build + serialize | 52.2 ms | 51.9 ms | -0.6% |
+| subgraph battery | 2 061.7 ms | 1 620.4 ms | -21.4% |
+| neighborhood x200 | 3 151.4 ms | 1 080.7 ms | -65.7% |
+| edge_detail x50 | 1 656.0 ms | 1 095.3 ms | -33.9% |
+
+### 1c. Synthetic `small` -- 233 files, 2 666 nodes, 3 880 edges
+
+| Metric | `main` | branch | Delta |
+| --- | --- | --- | --- |
+| pipeline total | 33.1 ms | 27.2 ms | -17.9% |
+| payload bytes | 0.99 MB | 0.89 MB | -9.8% |
+| subgraph battery | 61.7 ms | 47.1 ms | -23.5% |
+| neighborhood x200 | 142.3 ms | 37.0 ms | -74.0% |
+| edge_detail x50 | 56.2 ms | 29.6 ms | -47.4% |
+
+### 1d. The CodeCartographer repo itself -- 120 files, 1 317 nodes, 4 147 edges
+
+The realistic small-repo case: mixed Rust/TypeScript, real symbol distribution.
+
+| Metric | `main` | branch | Delta |
+| --- | --- | --- | --- |
+| pipeline total | 48.2 ms | 41.7 ms | -13.4% |
+| payload bytes | 0.70 MB | 0.64 MB | -9.1% |
+| payload build + serialize | 2.0 ms | 1.7 ms | -15.4% |
+| subgraph battery | 81.9 ms | 66.5 ms | -18.8% |
+| neighborhood x200 | 142.3 ms | 76.8 ms | -46.0% |
+| edge_detail x50 | 60.0 ms | 43.7 ms | -27.2% |
+
+Note how flat the branch's subgraph times are across render-set sizes in every
+table: on `main` the cost is dominated by rebuilding the parent map, which
+depends on the GRAPH size, not the render set, so all four render sets cost about
+the same. Removing that rebuild is what makes the numbers start tracking the work
+the query actually does.
+
+## 2. Criterion microbenchmarks
+
+Median of 20 samples. "shipping" is each branch's own release profile; "matched"
+is the branch rebuilt with `main`'s LTO/codegen-units.
+
+### Targeted by the perf work
+
+| Benchmark | `main` | branch (shipping) | branch (matched) | Delta (matched) |
+| --- | --- | --- | --- | --- |
+| `resolve_hub_ambiguity/ambiguous_resolve/1000` | 1.222 s | 3.77 ms | 4.53 ms | **-99.6%** |
+| `resolve_hub_ambiguity/ambiguous_resolve/500` | 282.7 ms | 1.94 ms | 2.23 ms | **-99.2%** |
+| `neighborhood_bfs/50000` | 1.021 s | 26.08 ms | 24.67 ms | **-97.6%** |
+| `neighborhood_bfs/10000` | 101.1 ms | 3.90 ms | 3.77 ms | **-96.3%** |
+| `subgraph_fully_expanded/50000` | 46.26 ms | 17.07 ms | 16.92 ms | -63.4% |
+| `subgraph_fully_expanded/10000` | 5.49 ms | 1.88 ms | 2.00 ms | -63.6% |
+| `subgraph_nested_collapsed/directories_only/10000` | 9.43 ms | 4.46 ms | 4.25 ms | -55.0% |
+| `subgraph_nested_collapsed/directories_only/2000` | 1.066 ms | 532.6 us | 545.4 us | -48.8% |
+| `subgraph_nested_collapsed/dirs_and_files/2000` | 1.037 ms | 524.0 us | 535.3 us | -48.4% |
+| `subgraph_nested_collapsed/dirs_and_files/10000` | 7.98 ms | 4.17 ms | 4.18 ms | -47.6% |
+| `subgraph_nested_collapsed/dirs_and_files/50000` | 71.05 ms | 39.06 ms | 40.02 ms | -43.7% |
+| `subgraph_nested_collapsed/directories_only/50000` | 66.36 ms | 38.59 ms | 39.35 ms | -40.7% |
+| `add_edge_all_duplicates/1000` | 112.3 us | 65.8 us | 72.6 us | -35.4% |
+| `parse_result_serialize/10000` | 14.17 ms | 9.94 ms | 9.79 ms | -30.9% |
+| `parse_result_serialize/50000` | 92.63 ms | 81.00 ms | 79.10 ms | -14.6% |
+
+### Not targeted -- the control
+
+| Benchmark | `main` | branch (shipping) | branch (matched) | Delta (matched) |
+| --- | --- | --- | --- | --- |
+| `add_edge_unique/5000` | 4.101 ms | 3.773 ms | 4.069 ms | -0.8% |
+| `add_edge_mixed/5000` | 3.397 ms | 3.116 ms | 3.371 ms | -0.7% |
+| `rebuild_adjacency/5000` | 4.223 ms | 4.177 ms | 4.156 ms | -1.6% |
+| `subgraph_flat_no_hierarchy/nodes/2000` | 426.3 us | 401.2 us | 410.1 us | -3.8% |
+| `extract_many_files/100` | 47.17 ms | 46.48 ms | 47.42 ms | +0.5% |
+| `full_pipeline/50` | 26.45 ms | 25.76 ms | 26.34 ms | -0.4% |
+| `resolve_hub_ambiguity/unique_control_resolve/1000` | 2.662 ms | 2.405 ms | 2.639 ms | -0.9% |
+| `resolve_hub_ambiguity/ambiguous_build_table/1000` | 5.518 ms | 5.451 ms | 5.737 ms | +4.0% |
+
+`subgraph_flat_no_hierarchy` is the OLD subgraph fixture. It moves -3.8%, and
+that is the entire point: on a flat graph the parent map is empty, the ancestor
+walk never runs, and the change under test is invisible. The same code path on
+the nested fixture moves -40% to -55%. A fixture that skips the hot path reports
+a confident zero.
+
+## 3. Frontend edge routing
+
+`packages/app/benchmarks/edgeRouting.bench.ts`, mean of 5 reps, Node v24.10.0.
+
+| Layout | Scenario | `main` | branch | Delta |
+| --- | --- | --- | --- | --- |
+| 300n / 200e | `full_scan_routing` (control) | 134.5 ms | 133.2 ms | -1.0% |
+| | `indexed_routing` | n/a (no `obstacleIndex.ts`) | 47.6 ms | |
+| | **`shipped_redraw`** | **127.8 ms** | **45.4 ms** (mode `full`) | **-64.5%** |
+| 800n / 500e | `full_scan_routing` (control) | 794.1 ms | 785.3 ms | -1.1% |
+| | `indexed_routing` | n/a | 252.1 ms | |
+| | **`shipped_redraw`** | **789.4 ms** | **136.3 ms** (mode `obstacles`) | **-82.7%** |
+| 1500n / 1200e | `full_scan_routing` (control) | 3 721.6 ms | 3 718.9 ms | -0.1% |
+| | `indexed_routing` | n/a | 1 223.8 ms | |
+| | **`shipped_redraw`** | **3 643.1 ms** | **~0 ms** (mode `none`) | **-100%** |
+
+The control scenario -- obstacle collection by full scan, reimplemented inside
+the bench so it is identical on both branches -- agrees to within 1.1% at every
+size. That is the evidence that the two runs are comparable and that the other
+rows are the code, not the machine.
+
+Reading the branch's own two rows against each other separates the two
+mechanisms: the R-tree obstacle index alone is a 2.8x-3.0x win
+(`full_scan_routing` -> `indexed_routing`), and the budget gate contributes the
+rest by dropping crossing-aware scoring above 250 edges and skipping routing
+entirely above 500 edges or 2000 nodes.
+
+`main` never took 3.6 s of main-thread time in one go for a 1200-edge view in
+practice, because it hit ELK's own node-count guard first -- but nothing bounded
+the redraw pass itself, which is what these numbers measure.
+
+---
+
+# Claims: confirmed and contradicted
+
+## Confirmed
+
+1. **Cached parent map (`get_subgraph` / `neighborhood` / `edge_detail`).**
+   Strongly confirmed, and larger than advertised for BFS. `neighborhood_bfs` at
+   50k nodes drops 97.6%, because `main` rebuilt a 50k-entry `HashMap<NodeId,
+   NodeId>` -- two `String` clones per child link -- on every single query. In the
+   harness, 200 neighborhood queries on the 10k-file repo go from 24.1 s to 6.2 s
+   (-74.4%), and 50 edge-detail drill-ins from 12.7 s to 7.2 s (-43.4%).
+   Subgraph extraction is -19% to -21% end to end and -41% to -55% in the
+   microbenchmark.
+
+2. **Ambiguity early-bail in symbol resolution.** Strongly confirmed, and the
+   single biggest win in the suite. On the synthetic 10k-file repo (half the
+   modules defining the same hub names), symbol resolution drops from 8.43 s to
+   0.79 s (-90.6%), taking the whole pipeline from 10.75 s to 3.07 s (-71.5%).
+   The microbenchmark isolates it: with 1000 files defining `__init__`/`new`/
+   `get`/`run`/`handle`, resolving 10 000 references goes from 1.22 s to 3.8 ms.
+   `main` was cloning hundreds of `NodeId`s per reference and then discarding all
+   of them at the 5-candidate cap. The matching `unique_control` benchmark, same
+   volume with unique names, is unchanged (-0.9%) -- so nothing was traded away
+   for it.
+
+3. **Obstacle-indexed edge routing plus budget gates.** Confirmed. The index
+   alone is 2.8x-3.0x; the shipped redraw is -64.5% at 300n/200e, -82.7% at
+   800n/500e and -100% at 1500n/1200e where the budget skips routing outright.
+   The 250/500-edge gates behave exactly as documented.
+
+4. **`into_iter` edge insertion.** Real but small: `add_edge_all_duplicates/1000`
+   is -35% and edge insertion in the harness is within noise (-1.7% at the large
+   size). It removes a clone per edge; edge insertion was never the bottleneck.
+
+## Contradicted or overstated
+
+5. **"~-22% payload" for the slim `ParseResult`. Not reproduced.** Measured
+   payload reduction is **-7.8%** (synthetic large), **-8.4%** (medium), **-9.8%**
+   (small) and **-9.1%** (the CodeCartographer repo itself). Dumping the `main`
+   payload for this repo and measuring per field explains why:
+
+   | field | bytes | share of payload |
+   | --- | --- | --- |
+   | `children` | 103 362 | 14.7% |
+   | `id` | 90 610 | 12.9% |
+   | node-map keys | 84 025 | 11.9% |
+   | `span` | 81 003 | 11.5% |
+   | **`signature`** | **64 206** | **9.1%** |
+   | `parent` | 63 917 | 9.1% |
+   | `name` | 38 025 | 5.4% |
+   | everything else | ~79 000 | ~11% |
+
+   So the docstring in `graph.rs` (and `docs/features/server_side_graph_state.md`)
+   calling `signature` "the single largest contributor to the payload" is wrong
+   for this repo: it is the fifth largest, behind `children`, `id`, the node-map
+   keys and `span`. The node id is in fact paid for **three times** -- as the map
+   key, as the `id` field, and again as each child's entry in its parent's
+   `children` array -- which together are 39.5% of the payload. That is where the
+   next payload win is, not in dropping more per-node fields.
+
+6. **"Serialization without the node-map deep clone" is a clear time win.**
+   Half right, and worth knowing. Building the `ParseResult` IS much cheaper
+   (-39.0% at the large size, -35.9% at small: no deep clone). But SERIALIZING
+   the slim borrowed form is **slower** -- +51.0% at the large size, +71.2% at
+   medium -- despite emitting fewer bytes. Net build+serialize is -8.8% (large),
+   -0.6% (medium), -15.4% (this repo): somewhere between neutral and modest, not
+   the step change the build-side number alone suggests. The plausible mechanism
+   is locality: `main` serializes a freshly written contiguous clone, the branch
+   walks the live node map and constructs a `SlimNode` per entry. Worth a look if
+   payload time ever matters; the memory saving (no second copy of the node map)
+   stands regardless.
+
+7. **Import resolution and symbol-table construction got slightly slower** on
+   the largest input (+12.9% and +6.3% respectively at the 10k-file size, though
+   -16% to -33% at the small size). This is a few hundred milliseconds against a
+   7.7-second win elsewhere, and the direction flips with size, so it is most
+   likely allocator/cache behaviour at the new working-set size rather than a
+   real regression. Flagged rather than explained.
+
+## Where the numbers came from
+
+Raw output (harness JSON per size, criterion text for all three profiles,
+frontend JSON) is not committed -- rerun `benchmarks/run_all.sh` to regenerate
+it. The procedure is documented in `docs/features/benchmarking.md`.
+
+## Real repo: Megatron-LM (2026-08-11)
+
+The repo that originally motivated the performance work
+(https://github.com/nvidia/megatron-lm, shallow clone): 1,279 parsed Python
+files, 22,368 nodes, 59,056 edges, 149,219 raw references. `perf_harness`
+release builds on both branches, sequential runs on the same machine, seed
+20240611, **median of 3 runs per side**. Both sides produced byte-identical
+graph statistics (same node/edge/resolution counts).
+
+| Metric | main | feat/perf-integration | delta |
+| --- | --- | --- | --- |
+| Full pipeline (scan -> parse -> resolve) | 922 ms | 912 ms | -1.2% (noise band) |
+| Neighborhood battery (200 queries, depth 2) | 2,989 ms | 1,117 ms | **-62.6%** |
+| Edge-detail battery (50 drill-ins) | 1,343 ms | 828 ms | **-38.3%** |
+| Subgraph battery (24 render sets x 6 reps) | 1,831 ms | 1,531 ms | -16.4% |
+| ParseResult build (steady mean) | 35.0 ms | 19.6 ms | -43.9% |
+| ParseResult serialize (steady mean) | 18.7 ms | 26.8 ms | +43.0% |
+| Payload bytes | 13.75 MB | 12.65 MB | -8.0% |
+
+Run-to-run spread (min-max of 3): neighborhood main 2,936-3,081 ms vs branch
+1,047-1,124 ms (non-overlapping); full pipeline overlaps across sides
+(798-958 ms), hence "noise band".
+
+Reading: at this size ingestion was never the bottleneck (~0.9 s either way) --
+Megatron-LM's pain is interactive, and the per-interaction backend paths are
+16-63% faster. The serialize regression (finding 6) reproduces here; net
+build+serialize is still -14%. The larger felt improvement should come from the
+frontend changes this harness cannot measure (routing budget, one-rebuild
+layouts, trigger policy): at 59k edges, symbol-view redraws previously entered
+the unbounded O(E x N) routing regime measured in the frontend bench.
diff --git a/benchmarks/gen_repo.py b/benchmarks/gen_repo.py
new file mode 100644
index 0000000..bf92e16
--- /dev/null
+++ b/benchmarks/gen_repo.py
@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""Deterministically generate a synthetic Python (+ optional TypeScript) repo.
+
+The end-to-end harness (`crates/cc-core/examples/perf_harness.rs`) needs an
+input repo that is (a) big enough for the pipeline costs to dominate noise and
+(b) BYTE-IDENTICAL between two checkouts, so the same harness run on `main` and
+on a feature branch is comparing the same work. Everything here is driven by a
+single seeded `random.Random`, and the file order is fixed, so a given
+(seed, files, depth, hub_fraction, ts_fraction) tuple always produces the same
+tree.
+
+Shape knobs that matter for what the benchmarks measure:
+
+- `--files` / `--depth`: node and directory-chain counts, which drive scan cost,
+  the size of the child -> parent map, and how far edge endpoints have to be
+  lifted when containers are collapsed.
+- `--hub-fraction`: the share of modules that define the SAME hub names
+  (`get`, `run`, `handle`, `new`, `__init__`). Those names are what push symbol
+  resolution into its ambiguous tiers, which is the path the early-bail change
+  in the perf work targets. At 0.0 every symbol is unique and resolution is
+  trivially cheap; at 0.6 a hub name has hundreds of global definitions.
+- `--imports-per-file`: cross-module import + call density, i.e. edge count.
+
+Usage:
+
+    python3 benchmarks/gen_repo.py --preset medium --out "$TMPDIR/cc-bench-medium"
+    python3 benchmarks/gen_repo.py --files 500 --depth 3 --hub-fraction 0.5 \
+        --out /path/to/repo
+
+Never generates into the repository itself: `--out` is required (the presets
+only pick sizes, not locations).
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+# Names deliberately shared by many modules. These are the ones that make a
+# global symbol lookup return hundreds of candidates.
+HUB_FUNCTIONS = ["run", "build", "handle", "process"]
+HUB_METHODS = ["__init__", "get", "new", "update", "close"]
+
+PRESETS = {
+    "small": dict(files=200, depth=3, imports_per_file=3, hub_fraction=0.5),
+    "medium": dict(files=2000, depth=4, imports_per_file=4, hub_fraction=0.5),
+    "large": dict(files=10000, depth=5, imports_per_file=4, hub_fraction=0.5),
+}
+
+
+@dataclass(frozen=True)
+class Module:
+    """One generated module: where it lives and whether it defines hub names."""
+
+    index: int
+    package: tuple[str, ...]
+    name: str
+    is_hub: bool
+    is_ts: bool
+
+    @property
+    def rel_path(self) -> Path:
+        suffix = ".ts" if self.is_ts else ".py"
+        return Path(*self.package) / f"{self.name}{suffix}"
+
+    @property
+    def dotted(self) -> str:
+        """Python import path (`pkg_0.pkg_3.mod_17`)."""
+        return ".".join([*self.package, self.name])
+
+
+def build_package_tree(rng: random.Random, depth: int, count: int) -> list[tuple[str, ...]]:
+    """Return `count` package paths, at most `depth` levels deep.
+
+    Built breadth-first from a fixed branching factor so the directory tree is
+    bushy rather than a single chain: real repos have a handful of top-level
+    packages and progressively fewer deep ones.
+    """
+    packages: list[tuple[str, ...]] = [()]
+    frontier: list[tuple[str, ...]] = [()]
+    branching = 4
+    next_id = 0
+
+    while len(packages) < count and frontier:
+        parent = frontier.pop(0)
+        if len(parent) >= depth:
+            continue
+        for _ in range(branching):
+            if len(packages) >= count:
+                break
+            child = (*parent, f"pkg_{next_id}")
+            next_id += 1
+            packages.append(child)
+            frontier.append(child)
+
+    # Shuffle only the ORDER modules are assigned to packages, not the set, so
+    # the tree shape is stable while file placement still looks irregular.
+    rng.shuffle(packages)
+    return packages
+
+
+def plan_modules(
+    rng: random.Random, files: int, depth: int, hub_fraction: float, ts_fraction: float
+) -> list[Module]:
+    package_count = max(1, files // 6)
+    packages = build_package_tree(rng, depth, package_count)
+
+    modules: list[Module] = []
+    for i in range(files):
+        package = packages[i % len(packages)]
+        is_hub = rng.random() < hub_fraction
+        is_ts = rng.random() < ts_fraction
+        modules.append(
+            Module(index=i, package=package, name=f"mod_{i}", is_hub=is_hub, is_ts=is_ts)
+        )
+    return modules
+
+
+def pick_imports(rng: random.Random, modules: list[Module], me: Module, k: int) -> list[Module]:
+    """`k` distinct other modules for `me` to import, chosen deterministically."""
+    if len(modules) <= 1 or k <= 0:
+        return []
+    picked: list[Module] = []
+    seen = {me.index}
+    for _ in range(k * 3):
+        if len(picked) >= k:
+            break
+        candidate = modules[rng.randrange(len(modules))]
+        if candidate.index in seen or candidate.is_ts != me.is_ts:
+            continue
+        seen.add(candidate.index)
+        picked.append(candidate)
+    return picked
+
+
+def python_module_source(module: Module, imports: list[Module]) -> str:
+    i = module.index
+    lines: list[str] = [f'"""Generated module {module.dotted}."""', "", "import os", "import sys"]
+
+    for dep in imports:
+        lines.append(f"from {dep.dotted} import Widget{dep.index}, make_{dep.index}")
+    lines.append("")
+    lines.append("")
+
+    # Class with either hub method names or module-unique ones.
+    methods = HUB_METHODS if module.is_hub else [f"{m}_{i}" for m in HUB_METHODS]
+    lines.append(f"class Widget{i}:")
+    lines.append(f'    """Widget defined by {module.dotted}."""')
+    lines.append("")
+    for method in methods:
+        if method == "__init__":
+            lines.append("    def __init__(self, name=None):")
+            lines.append("        self.name = name")
+            lines.append("        self.items = []")
+        elif method.startswith("__init__"):
+            # Unique-name variant of the constructor for non-hub modules.
+            lines.append("    def __init__(self, name=None):")
+            lines.append("        self.name = name")
+            lines.append("        self.items = []")
+        else:
+            lines.append(f"    def {method}(self, value=None):")
+            lines.append("        if value is not None:")
+            lines.append("            self.items.append(value)")
+            lines.append("        return self.items")
+        lines.append("")
+
+    # Free functions: hub-named for hub modules, unique otherwise.
+    functions = HUB_FUNCTIONS if module.is_hub else [f"{f}_{i}" for f in HUB_FUNCTIONS]
+    for func in functions:
+        lines.append(f"def {func}(source=None):")
+        lines.append(f"    widget = Widget{i}(source)")
+        lines.append("    widget.items.append(source)")
+        lines.append("    return widget")
+        lines.append("")
+
+    # A unique factory every importer can call, so imports produce call edges
+    # rather than dangling names.
+    lines.append(f"def make_{i}(source=None):")
+    lines.append(f"    return Widget{i}(source)")
+    lines.append("")
+
+    # Call sites into the imported modules: this is what makes the resolver do
+    # real work, and (for hub names) what drives it into the ambiguous tiers.
+    lines.append(f"def wire_{i}(payload):")
+    lines.append("    results = []")
+    for dep in imports:
+        lines.append(f"    results.append(make_{dep.index}(payload))")
+        lines.append(f"    results.append(Widget{dep.index}(payload))")
+    for func in HUB_FUNCTIONS:
+        lines.append(f"    results.append({func}(payload))")
+    lines.append("    return results")
+    lines.append("")
+
+    # Hub-name call sites. In a HUB module these resolve same-file (tier 1, the
+    # cheap path); everywhere else they hit the global tiers, where a name with
+    # hundreds of definitions is exactly the ambiguity the resolver has to bail
+    # out of. `--hub-fraction` therefore sets the ambiguous/cheap ratio.
+    lines.append(f"def dispatch_{i}(payload):")
+    lines.append("    out = []")
+    for func in HUB_FUNCTIONS:
+        lines.append(f"    out.append({func}(payload))")
+    for dep in imports:
+        for method in ("get", "update", "close"):
+            lines.append(f"    out.append(make_{dep.index}(payload).{method}(payload))")
+    lines.append("    return out")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def typescript_module_source(module: Module, imports: list[Module]) -> str:
+    i = module.index
+    lines: list[str] = [f"// Generated module {module.dotted}.", ""]
+
+    for dep in imports:
+        rel = relative_ts_import(module, dep)
+        lines.append(f'import {{ Widget{dep.index}, make{dep.index} }} from "{rel}";')
+    lines.append("")
+
+    methods = HUB_METHODS if module.is_hub else [f"{m}_{i}" for m in HUB_METHODS]
+    lines.append(f"export interface Spec{i} {{")
+    lines.append("  name: string;")
+    lines.append("  items: string[];")
+    lines.append("}")
+    lines.append("")
+    lines.append(f"export class Widget{i} {{")
+    lines.append("  items: string[] = [];")
+    lines.append("")
+    for method in methods:
+        safe = method.replace("__init__", "init")
+        lines.append(f"  {safe}(value?: string): string[] {{")
+        lines.append("    if (value) this.items.push(value);")
+        lines.append("    return this.items;")
+        lines.append("  }")
+        lines.append("")
+    lines.append("}")
+    lines.append("")
+
+    functions = HUB_FUNCTIONS if module.is_hub else [f"{f}_{i}" for f in HUB_FUNCTIONS]
+    for func in functions:
+        lines.append(f"export function {func}(source: string): Widget{i} {{")
+        lines.append(f"  const widget = new Widget{i}();")
+        lines.append("  widget.items.push(source);")
+        lines.append("  return widget;")
+        lines.append("}")
+        lines.append("")
+
+    lines.append(f"export function make{i}(source: string): Widget{i} {{")
+    lines.append(f"  const widget = new Widget{i}();")
+    lines.append("  widget.items.push(source);")
+    lines.append("  return widget;")
+    lines.append("}")
+    lines.append("")
+
+    lines.append(f"export function wire{i}(payload: string): unknown[] {{")
+    lines.append("  const results: unknown[] = [];")
+    for dep in imports:
+        lines.append(f"  results.push(make{dep.index}(payload));")
+        lines.append(f"  results.push(new Widget{dep.index}());")
+    lines.append("  return results;")
+    lines.append("}")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def relative_ts_import(module: Module, dep: Module) -> str:
+    """A `./`-prefixed relative specifier from `module` to `dep` (no extension)."""
+    from_dir = Path(*module.package)
+    to_path = Path(*dep.package) / dep.name
+    up = len(from_dir.parts)
+    rel = Path(*([".."] * up)) / to_path if up else to_path
+    text = rel.as_posix()
+    return text if text.startswith(".") else f"./{text}"
+
+
+def generate(
+    out: Path,
+    files: int,
+    depth: int,
+    imports_per_file: int,
+    hub_fraction: float,
+    ts_fraction: float,
+    seed: int,
+    force: bool,
+) -> dict[str, int]:
+    if out.exists():
+        if not force:
+            raise SystemExit(
+                f"{out} already exists; pass --force to regenerate it from scratch"
+            )
+        shutil.rmtree(out)
+
+    rng = random.Random(seed)
+    modules = plan_modules(rng, files, depth, hub_fraction, ts_fraction)
+
+    # A second generator for import edges, seeded off the same seed, so changing
+    # `--imports-per-file` does not perturb module placement.
+    edge_rng = random.Random(seed ^ 0x5EED)
+
+    packages_written: set[tuple[str, ...]] = set()
+    hub_modules = 0
+    ts_modules = 0
+
+    for module in modules:
+        target = out / module.rel_path
+        target.parent.mkdir(parents=True, exist_ok=True)
+
+        # Every Python package level needs an __init__.py to be importable.
+        if not module.is_ts:
+            for level in range(len(module.package) + 1):
+                package = module.package[:level]
+                if package in packages_written:
+                    continue
+                packages_written.add(package)
+                init = out / Path(*package) / "__init__.py"
+                init.parent.mkdir(parents=True, exist_ok=True)
+                init.write_text(f'"""Package {".".join(package) or "root"}."""\n')
+
+        imports = pick_imports(edge_rng, modules, module, imports_per_file)
+        source = (
+            typescript_module_source(module, imports)
+            if module.is_ts
+            else python_module_source(module, imports)
+        )
+        target.write_text(source)
+
+        hub_modules += int(module.is_hub)
+        ts_modules += int(module.is_ts)
+
+    return {
+        "modules": len(modules),
+        "hub_modules": hub_modules,
+        "ts_modules": ts_modules,
+        "packages": len(packages_written),
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--out", required=True, type=Path, help="destination directory (must be outside the repo)")
+    parser.add_argument("--preset", choices=sorted(PRESETS), help="size preset: small/medium/large")
+    parser.add_argument("--files", type=int, help="number of modules to generate")
+    parser.add_argument("--depth", type=int, help="maximum package nesting depth")
+    parser.add_argument("--imports-per-file", type=int, help="cross-module imports per module")
+    parser.add_argument(
+        "--hub-fraction",
+        type=float,
+        help="share of modules defining the shared hub names (0.0-1.0)",
+    )
+    parser.add_argument(
+        "--ts-fraction",
+        type=float,
+        default=0.0,
+        help="share of modules emitted as TypeScript instead of Python",
+    )
+    parser.add_argument("--seed", type=int, default=20240611, help="RNG seed (default: 20240611)")
+    parser.add_argument("--force", action="store_true", help="delete --out first if it exists")
+    args = parser.parse_args(argv)
+
+    settings = dict(PRESETS[args.preset]) if args.preset else dict(PRESETS["small"])
+    for key in ("files", "depth", "imports_per_file", "hub_fraction"):
+        value = getattr(args, key)
+        if value is not None:
+            settings[key] = value
+
+    stats = generate(
+        out=args.out,
+        files=int(settings["files"]),
+        depth=int(settings["depth"]),
+        imports_per_file=int(settings["imports_per_file"]),
+        hub_fraction=float(settings["hub_fraction"]),
+        ts_fraction=args.ts_fraction,
+        seed=args.seed,
+        force=args.force,
+    )
+
+    print(
+        f"generated {stats['modules']} modules "
+        f"({stats['hub_modules']} hub-named, {stats['ts_modules']} TypeScript) "
+        f"across {stats['packages']} packages into {args.out}"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/benchmarks/run_all.sh b/benchmarks/run_all.sh
new file mode 100644
index 0000000..02a1304
--- /dev/null
+++ b/benchmarks/run_all.sh
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# Run every benchmark layer once and drop the raw output in one directory.
+#
+#   benchmarks/run_all.sh <label> <output-dir> <synthetic-repos-dir>
+#
+# `label` goes into the harness JSON so two runs can be told apart. The
+# synthetic repos directory is expected to already contain cc-small/cc-medium/
+# cc-large, generated by:
+#
+#   for p in small medium large; do
+#     python3 benchmarks/gen_repo.py --preset $p --out "$REPOS/cc-$p" --force
+#   done
+#
+# The point of this script is that the SAME commands run on both sides of a
+# comparison. Anything conditional or interactive belongs somewhere else.
+#
+# Criterion is invoked with explicit, uniform sampling parameters (rather than
+# each group's own defaults) so the two runs sample identically regardless of
+# what the bench files ask for.
+
+set -euo pipefail
+
+if [ $# -lt 3 ]; then
+  echo "usage: $0 <label> <output-dir> <synthetic-repos-dir> [real-repo-path]" >&2
+  exit 2
+fi
+
+LABEL="$1"
+OUT="$(mkdir -p "$2" && cd "$2" && pwd)"
+REPOS="$3"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# The "real repo" case. Defaults to this checkout, but when comparing two
+# branches pass the SAME path to both runs: the two checkouts differ in content,
+# and a difference in input is not a difference in speed.
+REAL_REPO="${4:-$ROOT}"
+
+CRITERION_ARGS=(--warm-up-time 1 --measurement-time 3 --sample-size 20)
+
+echo "== [$LABEL] building release harness =="
+cargo build --release --example perf_harness -p cc-core --manifest-path "$ROOT/Cargo.toml"
+
+HARNESS="$ROOT/target/release/examples/perf_harness"
+
+for size in small medium large; do
+  repo="$REPOS/cc-$size"
+  if [ ! -d "$repo" ]; then
+    echo "-- skipping $size: $repo does not exist" >&2
+    continue
+  fi
+  echo "== [$LABEL] harness on synthetic $size =="
+  "$HARNESS" --repo "$repo" --label "$LABEL/$size" --out "$OUT/harness-$size.json" \
+    > /dev/null 2> "$OUT/harness-$size.log"
+done
+
+echo "== [$LABEL] harness on the real repo ($REAL_REPO) =="
+"$HARNESS" --repo "$REAL_REPO" --label "$LABEL/self" --out "$OUT/harness-self.json" \
+  > /dev/null 2> "$OUT/harness-self.log"
+
+echo "== [$LABEL] criterion =="
+# Requires `[lib] bench = false` in crates/cc-core/Cargo.toml: without it cargo
+# builds a libtest bench harness for the lib and runs it first, and that harness
+# rejects criterion's CLI flags, failing the invocation before a single benchmark
+# runs. A baseline checkout predating that line needs it copied in too.
+(cd "$ROOT" && cargo bench -p cc-core -- "${CRITERION_ARGS[@]}") \
+  > "$OUT/criterion.txt" 2>&1 || echo "criterion exited non-zero; see $OUT/criterion.txt" >&2
+
+echo "== [$LABEL] frontend edge routing =="
+if [ -d "$ROOT/packages/app/node_modules" ]; then
+  (cd "$ROOT/packages/app" && node benchmarks/edgeRouting.bench.ts \
+      --label "$LABEL" --json "$OUT/edge-routing.json") \
+    > /dev/null 2> "$OUT/edge-routing.log"
+else
+  echo "-- skipping frontend bench: run pnpm install in packages/app first" >&2
+fi
+
+echo "== [$LABEL] done: $OUT =="
diff --git a/crates/cc-core/Cargo.toml b/crates/cc-core/Cargo.toml
index 37f5140..776c476 100644
--- a/crates/cc-core/Cargo.toml
+++ b/crates/cc-core/Cargo.toml
@@ -21,6 +21,14 @@ tree-sitter-javascript = "0.23"
 tempfile = "3"
 criterion = { workspace = true }
 
+# The lib has no `#[bench]` functions, but cargo still builds a libtest bench
+# harness for it and runs it as part of `cargo bench -p cc-core`. That harness
+# rejects criterion's CLI flags, so `cargo bench -p cc-core -- --sample-size 20`
+# fails before reaching a single benchmark. Opting the lib out leaves the two
+# criterion targets as the only bench targets.
+[lib]
+bench = false
+
 [[bench]]
 name = "graph_bench"
 harness = false
diff --git a/crates/cc-core/benches/common/mod.rs b/crates/cc-core/benches/common/mod.rs
new file mode 100644
index 0000000..1491cda
--- /dev/null
+++ b/crates/cc-core/benches/common/mod.rs
@@ -0,0 +1,313 @@
+//! Shared fixtures for the cc-core criterion benches.
+//!
+//! Lives in a SUBDIRECTORY on purpose: cargo auto-discovers `benches/*.rs` as
+//! bench targets, so a top-level `benches/common.rs` would be compiled as a
+//! bench of its own (and fail, having no `main`). `benches/common/mod.rs` is
+//! only ever pulled in by an explicit `mod common;`.
+//!
+//! The fixtures here exist because the ones they replace measured the wrong
+//! thing. See [`nested_graph`] for the specific trap.
+
+#![allow(dead_code)]
+
+use std::collections::HashSet;
+
+use cc_core::model::{
+    BlockKind, CodeEdge, CodeGraph, CodeNode, EdgeKind, Language, NodeId, Resolution, Span,
+    Visibility,
+};
+
+/// Deterministic SplitMix64 stream, so every fixture is byte-identical on every
+/// run and on every branch. (Nothing here may depend on `HashMap` iteration
+/// order, which is randomized per process.)
+pub struct Rng(u64);
+
+impl Rng {
+    pub fn new(seed: u64) -> Self {
+        Rng(seed)
+    }
+
+    pub fn next_u64(&mut self) -> u64 {
+        self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15);
+        let mut z = self.0;
+        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+        z ^ (z >> 31)
+    }
+
+    pub fn below(&mut self, n: usize) -> usize {
+        if n == 0 {
+            0
+        } else {
+            (self.next_u64() % n as u64) as usize
+        }
+    }
+}
+
+/// Every edge kind: the toolbar's default state, and the most expensive filter.
+pub fn all_edge_kinds() -> HashSet<EdgeKind> {
+    [
+        EdgeKind::Import,
+        EdgeKind::FunctionCall,
+        EdgeKind::MethodCall,
+        EdgeKind::TypeReference,
+        EdgeKind::Inheritance,
+        EdgeKind::TraitImpl,
+        EdgeKind::VariableUsage,
+    ]
+    .into_iter()
+    .collect()
+}
+
+fn span(line: usize) -> Span {
+    Span {
+        start_line: line,
+        start_col: 0,
+        end_line: line + 12,
+        end_col: 1,
+    }
+}
+
+/// A nested graph plus the id groups a bench needs to build render sets.
+pub struct NestedGraph {
+    pub graph: CodeGraph,
+    /// Directory ids, sorted.
+    pub dirs: Vec<NodeId>,
+    /// File ids, sorted.
+    pub files: Vec<NodeId>,
+    /// Code-block ids (both levels), sorted.
+    pub blocks: Vec<NodeId>,
+    /// Ids that are an endpoint of at least one edge, sorted.
+    pub edge_endpoints: Vec<NodeId>,
+}
+
+impl NestedGraph {
+    /// Render set: directories only. Every edge endpoint is a code block whose
+    /// nearest rendered ancestor is 3-8 links up the chain.
+    pub fn render_dirs(&self) -> Vec<NodeId> {
+        self.dirs.clone()
+    }
+
+    /// Render set: directories + files, i.e. every container expanded down to
+    /// file level with the files themselves collapsed. Endpoints lift 1-2 links.
+    pub fn render_dirs_files(&self) -> Vec<NodeId> {
+        let mut ids = self.dirs.clone();
+        ids.extend(self.files.iter().cloned());
+        ids
+    }
+
+    /// Render set: everything. No lifting happens at all -- the parent map is
+    /// built (on `main`, rebuilt per call) and then never walked, which isolates
+    /// the map's construction cost from the walk's.
+    pub fn render_all(&self) -> Vec<NodeId> {
+        let mut ids = self.render_dirs_files();
+        ids.extend(self.blocks.iter().cloned());
+        ids
+    }
+}
+
+/// Shape of the directory tree every nested fixture is built on: 3-way fanout,
+/// 5 levels, so a leaf directory sits 5 links below the root and a nested code
+/// block sits 8 links below it.
+const TREE_DEPTH: usize = 5;
+const TREE_FANOUT: usize = 3;
+/// Top-level blocks per file, each carrying `NESTED_BLOCKS` children (a class
+/// with methods, a module with functions).
+const BLOCKS_PER_FILE: usize = 5;
+const NESTED_BLOCKS: usize = 2;
+/// Nodes contributed by one file: itself plus its block subtree.
+const NODES_PER_FILE: usize = 1 + BLOCKS_PER_FILE * (1 + NESTED_BLOCKS);
+
+/// Build a nested `Directory > File > CodeBlock > CodeBlock` graph of roughly
+/// `target_nodes` nodes, with cross-file edges between the DEEPEST blocks.
+///
+/// # Why this shape
+///
+/// The fixture this replaces built `target_nodes` flat `File` nodes with empty
+/// `children` arrays and put every edge between two of them. That graph has an
+/// EMPTY parent map, so `find_render_ancestor` returned on its first probe and
+/// the aggregation path -- the entire reason `SubGraph::from_graph` needs a
+/// parent map -- never ran. It benchmarked the one input for which the parent
+/// map does not matter, and would report "no change" for any amount of work
+/// saved building or reusing it.
+///
+/// Here every edge endpoint is a leaf code block, and the render sets used by
+/// the benches keep the containers COLLAPSED, so both endpoints of every edge
+/// have to be walked up a real ancestor chain before the edge can be
+/// aggregated. That is the shape the app is in whenever a repo is first opened.
+pub fn nested_graph(target_nodes: usize, seed: u64) -> NestedGraph {
+    let mut rng = Rng::new(seed);
+    let mut graph = CodeGraph::new(NodeId("root".into()));
+
+    // --- directory tree ---------------------------------------------------
+    // Breadth-first so the ids are assigned level by level; `children` is filled
+    // in as each level is created.
+    let mut dir_paths: Vec<String> = vec!["root".to_string()];
+    let mut dir_children: Vec<Vec<NodeId>> = vec![Vec::new()];
+    let mut dir_of_depth: Vec<usize> = vec![0];
+    let mut level: Vec<usize> = vec![0];
+
+    for _ in 0..TREE_DEPTH {
+        let mut next = Vec::new();
+        for parent_idx in level {
+            for k in 0..TREE_FANOUT {
+                let path = format!("{}/dir_{}", dir_paths[parent_idx], k);
+                let idx = dir_paths.len();
+                dir_paths.push(path);
+                dir_children.push(Vec::new());
+                dir_of_depth.push(dir_of_depth[parent_idx] + 1);
+                dir_children[parent_idx].push(NodeId(dir_paths[idx].clone()));
+                next.push(idx);
+            }
+        }
+        level = next;
+    }
+
+    // --- files, distributed round-robin over every non-root directory ------
+    let placeable: Vec<usize> = (1..dir_paths.len()).collect();
+    let file_count = target_nodes
+        .saturating_sub(dir_paths.len())
+        .div_ceil(NODES_PER_FILE)
+        .max(1);
+
+    let mut files: Vec<NodeId> = Vec::with_capacity(file_count);
+    let mut blocks: Vec<NodeId> = Vec::new();
+    // Deepest blocks only: these are the edge endpoints, so every edge has the
+    // full ancestor chain above it.
+    let mut leaf_blocks: Vec<NodeId> = Vec::new();
+
+    for f in 0..file_count {
+        let dir_idx = placeable[f % placeable.len()];
+        let file_path = format!("{}/file_{f}.py", dir_paths[dir_idx]);
+        let file_id = NodeId::file(&file_path);
+        dir_children[dir_idx].push(file_id.clone());
+
+        let mut file_children = Vec::with_capacity(BLOCKS_PER_FILE);
+        for b in 0..BLOCKS_PER_FILE {
+            let block_id = NodeId::code_block(&file_path, &format!("Class_{f}_{b}"), b * 40);
+            let mut nested = Vec::with_capacity(NESTED_BLOCKS);
+            for m in 0..NESTED_BLOCKS {
+                let method_id =
+                    NodeId::code_block(&file_path, &format!("method_{f}_{b}_{m}"), b * 40 + m * 10);
+                graph.add_node(CodeNode::CodeBlock {
+                    id: method_id.clone(),
+                    name: format!("method_{f}_{b}_{m}"),
+                    kind: BlockKind::Function,
+                    span: span(b * 40 + m * 10),
+                    signature: Some(format!("def method_{f}_{b}_{m}(self, value=None):")),
+                    visibility: Some(Visibility::Public),
+                    parent: block_id.clone(),
+                    children: Vec::new(),
+                });
+                nested.push(method_id.clone());
+                blocks.push(method_id.clone());
+                leaf_blocks.push(method_id);
+            }
+            graph.add_node(CodeNode::CodeBlock {
+                id: block_id.clone(),
+                name: format!("Class_{f}_{b}"),
+                kind: BlockKind::Class,
+                span: span(b * 40),
+                signature: Some(format!("class Class_{f}_{b}:")),
+                visibility: Some(Visibility::Public),
+                parent: file_id.clone(),
+                children: nested,
+            });
+            file_children.push(block_id.clone());
+            blocks.push(block_id);
+        }
+
+        graph.add_node(CodeNode::File {
+            id: file_id.clone(),
+            name: format!("file_{f}.py"),
+            path: file_path,
+            language: Some(Language::Python),
+            children: file_children,
+        });
+        files.push(file_id);
+    }
+
+    for (idx, path) in dir_paths.iter().enumerate() {
+        graph.add_node(CodeNode::Directory {
+            id: NodeId::directory(path),
+            name: path.rsplit('/').next().unwrap_or(path).to_string(),
+            path: path.clone(),
+            children: std::mem::take(&mut dir_children[idx]),
+        });
+    }
+
+    // --- edges between leaf blocks in DIFFERENT files ----------------------
+    // ~4 per file, mixed kinds, so aggregation has several kinds to key on.
+    let kinds = [
+        EdgeKind::FunctionCall,
+        EdgeKind::MethodCall,
+        EdgeKind::Import,
+        EdgeKind::TypeReference,
+    ];
+    let edge_count = file_count * 4;
+    for e in 0..edge_count {
+        let source = leaf_blocks[rng.below(leaf_blocks.len())].clone();
+        let target = leaf_blocks[rng.below(leaf_blocks.len())].clone();
+        if source == target {
+            continue;
+        }
+        graph.add_edge(CodeEdge {
+            source,
+            target,
+            kind: kinds[e % kinds.len()].clone(),
+            weight: 1,
+            resolution: Resolution::GlobalUnique,
+        });
+    }
+
+    let mut dirs: Vec<NodeId> = dir_paths.iter().map(|p| NodeId::directory(p)).collect();
+    dirs.sort_by(|a, b| a.0.cmp(&b.0));
+    files.sort_by(|a, b| a.0.cmp(&b.0));
+    blocks.sort_by(|a, b| a.0.cmp(&b.0));
+
+    let mut edge_endpoints: Vec<NodeId> = graph
+        .edges
+        .iter()
+        .flat_map(|e| [e.source.clone(), e.target.clone()])
+        .collect::<HashSet<NodeId>>()
+        .into_iter()
+        .collect();
+    edge_endpoints.sort_by(|a, b| a.0.cmp(&b.0));
+
+    NestedGraph {
+        graph,
+        dirs,
+        files,
+        blocks,
+        edge_endpoints,
+    }
+}
+
+/// Build a flat graph of `n` `File` nodes with empty `children` and one edge per
+/// node -- the OLD subgraph fixture, kept for what it genuinely measures.
+///
+/// With no containment hierarchy the parent map is empty, so this isolates the
+/// direct-edge scan and render-set membership test with zero ancestor walking.
+pub fn flat_graph(n: usize) -> (CodeGraph, Vec<NodeId>) {
+    let mut graph = CodeGraph::new(NodeId("root".into()));
+    for i in 0..n {
+        graph.add_node(CodeNode::File {
+            id: NodeId(format!("file_{i}")),
+            name: format!("file_{i}.py"),
+            path: format!("src/file_{i}.py"),
+            language: Some(Language::Python),
+            children: Vec::new(),
+        });
+    }
+    for i in 0..n {
+        graph.add_edge(CodeEdge {
+            source: NodeId(format!("file_{i}")),
+            target: NodeId(format!("file_{}", (i + 1) % n)),
+            kind: EdgeKind::Import,
+            weight: 1,
+            resolution: Resolution::GlobalUnique,
+        });
+    }
+    let visible: Vec<NodeId> = (0..n / 2).map(|i| NodeId(format!("file_{i}"))).collect();
+    (graph, visible)
+}
diff --git a/crates/cc-core/benches/graph_bench.rs b/crates/cc-core/benches/graph_bench.rs
index d04c70c..cd1cdb8 100644
--- a/crates/cc-core/benches/graph_bench.rs
+++ b/crates/cc-core/benches/graph_bench.rs
@@ -1,6 +1,28 @@
+//! Criterion benches for the graph model: edge insertion, adjacency rebuild,
+//! subgraph extraction, neighborhood BFS and parse-payload serialization.
+//!
+//! The subgraph/neighborhood benches run on the NESTED fixture from
+//! [`common::nested_graph`] with containers collapsed. That matters: on a flat
+//! graph the child -> parent map is empty and the ancestor walk that aggregation
+//! exists for never runs, so a flat fixture reports "no change" no matter what
+//! happens to the parent map. See the doc comment on `common::nested_graph`.
+
+use std::collections::HashSet;
+use std::time::Duration;
+
 use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion};
 
-use cc_core::model::{CodeEdge, CodeGraph, EdgeKind, NodeId, Resolution};
+use cc_core::model::{
+    CodeEdge, CodeGraph, EdgeKind, FocusDirection, NodeId, ParseResult, Resolution, SubGraph,
+};
+
+mod common;
+
+use common::{all_edge_kinds, flat_graph, nested_graph, NestedGraph, Rng};
+
+/// Seed shared by every fixture in this file, so two runs (or two branches)
+/// build byte-identical graphs.
+const SEED: u64 = 20_240_611;
 
 /// Build a graph pre-loaded with `n` unique edges so we can benchmark add_edge
 /// against a populated graph (the hot path for duplicate checking).
@@ -126,55 +148,175 @@ fn bench_rebuild_adjacency(c: &mut Criterion) {
     group.finish();
 }
 
-/// Benchmark SubGraph::from_graph extraction with varying visible-node counts.
-fn bench_subgraph_extraction(c: &mut Criterion) {
-    use cc_core::model::SubGraph;
+/// `SubGraph::from_graph` on a FLAT graph: no containment hierarchy at all.
+///
+/// Kept from the original suite, renamed to say what it actually covers. With
+/// an empty parent map this measures the direct-edge scan and the render-set
+/// membership test ONLY -- no ancestor walking, no aggregation. It is the floor,
+/// not the representative case; `subgraph_nested_collapsed` is that.
+fn bench_subgraph_flat_no_hierarchy(c: &mut Criterion) {
+    let mut group = c.benchmark_group("subgraph_flat_no_hierarchy");
+    let kinds = all_edge_kinds();
 
-    let mut group = c.benchmark_group("subgraph_extraction");
     for total in [500, 2000] {
-        // Build a graph with nodes and edges
-        let mut graph = CodeGraph::new(NodeId("root".into()));
-        for i in 0..total {
-            graph.add_node(cc_core::model::CodeNode::File {
-                id: NodeId(format!("file_{i}")),
-                name: format!("file_{i}.py"),
-                path: format!("src/file_{i}.py"),
-                language: Some(cc_core::model::Language::Python),
-                children: Vec::new(),
-            });
-        }
-        for i in 0..total {
-            graph.add_edge(CodeEdge {
-                source: NodeId(format!("file_{i}")),
-                target: NodeId(format!("file_{}", (i + 1) % total)),
-                kind: EdgeKind::Import,
-                weight: 1,
-                resolution: Resolution::GlobalUnique,
-            });
+        let (graph, visible) = flat_graph(total);
+        group.bench_with_input(
+            BenchmarkId::new("nodes", total),
+            &(&graph, &visible),
+            |b, &(graph, visible)| {
+                b.iter(|| {
+                    black_box(SubGraph::from_graph(graph, visible, &kinds));
+                });
+            },
+        );
+    }
+    group.finish();
+}
+
+/// `SubGraph::from_graph` on the NESTED fixture with containers COLLAPSED --
+/// the representative case, and the one that needs the child -> parent map.
+///
+/// Two render sets per size:
+/// - `directories_only`: nothing but the directory tree is on screen, so both
+///   endpoints of every edge walk 3-8 links up (block -> class -> file -> dirs).
+/// - `dirs_and_files`: files on screen but collapsed, so endpoints walk 1-2
+///   links. This is the state a freshly-opened repo is in.
+///
+/// Sample counts are cut at the larger sizes to keep the suite a few minutes.
+fn bench_subgraph_nested_collapsed(c: &mut Criterion) {
+    let mut group = c.benchmark_group("subgraph_nested_collapsed");
+    group.sample_size(20);
+    group.warm_up_time(Duration::from_millis(500));
+    group.measurement_time(Duration::from_secs(3));
+    let kinds = all_edge_kinds();
+
+    for target in [2_000usize, 10_000, 50_000] {
+        let fixture = nested_graph(target, SEED);
+        let dirs = fixture.render_dirs();
+        let dirs_files = fixture.render_dirs_files();
+
+        group.bench_with_input(
+            BenchmarkId::new("directories_only", target),
+            &(&fixture.graph, &dirs),
+            |b, &(graph, render)| {
+                b.iter(|| black_box(SubGraph::from_graph(graph, render, &kinds)));
+            },
+        );
+
+        group.bench_with_input(
+            BenchmarkId::new("dirs_and_files", target),
+            &(&fixture.graph, &dirs_files),
+            |b, &(graph, render)| {
+                b.iter(|| black_box(SubGraph::from_graph(graph, render, &kinds)));
+            },
+        );
+    }
+    group.finish();
+}
+
+/// `SubGraph::from_graph` with EVERY node rendered.
+///
+/// No endpoint ever needs lifting, so this isolates the cost of having a parent
+/// map available at all from the cost of walking it: any delta here is the map's
+/// construction, not its use.
+fn bench_subgraph_fully_expanded(c: &mut Criterion) {
+    let mut group = c.benchmark_group("subgraph_fully_expanded");
+    group.sample_size(20);
+    group.warm_up_time(Duration::from_millis(500));
+    group.measurement_time(Duration::from_secs(3));
+    let kinds = all_edge_kinds();
+
+    for target in [10_000usize, 50_000] {
+        let fixture = nested_graph(target, SEED);
+        let all = fixture.render_all();
+        group.bench_with_input(
+            BenchmarkId::from_parameter(target),
+            &(&fixture.graph, &all),
+            |b, &(graph, render)| {
+                b.iter(|| black_box(SubGraph::from_graph(graph, render, &kinds)));
+            },
+        );
+    }
+    group.finish();
+}
+
+/// Neighborhood BFS (depth 2, both directions) on the nested fixture.
+///
+/// Each iteration runs a batch of 32 queries against deterministically chosen
+/// focus nodes, which is closer to a user's click-through than a single query
+/// and keeps per-iteration time above timer noise. The container-chain walk at
+/// the end of `neighborhood` also needs the parent map, so this is the second
+/// query type the caching change touches.
+fn bench_neighborhood(c: &mut Criterion) {
+    let mut group = c.benchmark_group("neighborhood_bfs");
+    group.sample_size(20);
+    group.warm_up_time(Duration::from_millis(500));
+    group.measurement_time(Duration::from_secs(3));
+    let kinds = all_edge_kinds();
+
+    for target in [10_000usize, 50_000] {
+        let fixture = nested_graph(target, SEED);
+        let focuses = pick_focus_nodes(&fixture, 32);
+
+        group.bench_with_input(
+            BenchmarkId::from_parameter(target),
+            &(&fixture.graph, &focuses),
+            |b, &(graph, focuses)| {
+                b.iter(|| {
+                    for focus in focuses {
+                        black_box(graph.neighborhood(focus, 2, &kinds, FocusDirection::Both));
+                    }
+                });
+            },
+        );
+    }
+    group.finish();
+}
+
+/// Deterministically choose `count` focus nodes from the fixture's edge
+/// endpoints (which are sorted, so the choice does not depend on hash order).
+fn pick_focus_nodes(fixture: &NestedGraph, count: usize) -> Vec<NodeId> {
+    let mut rng = Rng::new(SEED ^ 0x0F0C);
+    let mut seen: HashSet<usize> = HashSet::new();
+    let mut out = Vec::with_capacity(count);
+    while out.len() < count && seen.len() < fixture.edge_endpoints.len() {
+        let idx = rng.below(fixture.edge_endpoints.len());
+        if seen.insert(idx) {
+            out.push(fixture.edge_endpoints[idx].clone());
         }
+    }
+    out
+}
 
-        // Visible = half the nodes
-        let visible: Vec<NodeId> = (0..total / 2)
-            .map(|i| NodeId(format!("file_{i}")))
-            .collect();
-        let all_kinds: std::collections::HashSet<EdgeKind> = [
-            EdgeKind::Import,
-            EdgeKind::FunctionCall,
-            EdgeKind::MethodCall,
-            EdgeKind::TypeReference,
-            EdgeKind::Inheritance,
-            EdgeKind::TraitImpl,
-            EdgeKind::VariableUsage,
-        ]
-        .into_iter()
-        .collect();
+/// Build + serialize the parse payload (`ParseResult` -> JSON).
+///
+/// This is the IPC cost of opening a repo. The payload SIZE is printed once per
+/// fixture to stderr (criterion only reports time), because the shipped win here
+/// is as much about bytes crossing the IPC boundary as about the clock.
+fn bench_parse_result_serialization(c: &mut Criterion) {
+    let mut group = c.benchmark_group("parse_result_serialize");
+    group.sample_size(20);
+    group.warm_up_time(Duration::from_millis(500));
+    group.measurement_time(Duration::from_secs(3));
+
+    for target in [10_000usize, 50_000] {
+        let fixture = nested_graph(target, SEED);
+        let bytes = serde_json::to_string(&ParseResult::from_graph(&fixture.graph))
+            .expect("parse result serializes")
+            .len();
+        eprintln!(
+            "parse_result_serialize/{target}: {} nodes, {} edges, payload {bytes} bytes",
+            fixture.graph.node_count(),
+            fixture.graph.edge_count()
+        );
 
         group.bench_with_input(
-            BenchmarkId::new("nodes", total),
-            &(&graph, &visible, &all_kinds),
-            |b, &(graph, visible, kinds)| {
+            BenchmarkId::from_parameter(target),
+            &fixture.graph,
+            |b, graph| {
                 b.iter(|| {
-                    black_box(SubGraph::from_graph(graph, visible, kinds));
+                    let result = ParseResult::from_graph(graph);
+                    black_box(serde_json::to_string(&result).unwrap());
                 });
             },
         );
@@ -188,6 +330,10 @@ criterion_group!(
     bench_add_edge_all_duplicates,
     bench_add_edge_mixed,
     bench_rebuild_adjacency,
-    bench_subgraph_extraction,
+    bench_subgraph_flat_no_hierarchy,
+    bench_subgraph_nested_collapsed,
+    bench_subgraph_fully_expanded,
+    bench_neighborhood,
+    bench_parse_result_serialization,
 );
 criterion_main!(benches);
diff --git a/crates/cc-core/benches/parse_bench.rs b/crates/cc-core/benches/parse_bench.rs
index dbdd65c..8a9866b 100644
--- a/crates/cc-core/benches/parse_bench.rs
+++ b/crates/cc-core/benches/parse_bench.rs
@@ -368,10 +368,157 @@ fn bench_full_pipeline(c: &mut Criterion) {
     group.finish();
 }
 
+// ---------------------------------------------------------------------------
+// Symbol resolution under hub-name ambiguity
+// ---------------------------------------------------------------------------
+
+/// Names a real repo defines in hundreds of files. Every reference to one of
+/// these matches every definition, which is what drives resolution into its
+/// ambiguous tiers.
+const HUB_NAMES: &[&str] = &["__init__", "new", "get", "run", "handle"];
+
+/// Build a graph where `definers` files each define every hub name, plus a set
+/// of caller files that reference those names.
+///
+/// The callers deliberately define NOTHING, so their references cannot resolve
+/// same-file (tier 1) or via an import (tier 3) and fall all the way through to
+/// the global tiers. With `definers` well above the 5-candidate cap, every one
+/// of those references lands in tier 6 -- matched by hundreds of symbols and
+/// then dropped. That tier is pure waste by construction, and how cheaply the
+/// resolver reaches the decision to drop is exactly what this measures.
+///
+/// `unique` swaps the hub names for per-file unique ones, giving the tier-4
+/// (single global match) control: same number of references, same table size,
+/// no ambiguity.
+fn hub_ambiguity_fixture(
+    definers: usize,
+    callers: usize,
+    refs_per_caller: usize,
+    unique: bool,
+) -> (cc_core::model::CodeGraph, Vec<cc_core::parser::RawReference>) {
+    use cc_core::model::{BlockKind, CodeGraph, CodeNode, Language, NodeId, Span};
+    use cc_core::parser::{RawRefKind, RawReference};
+
+    let span = |line: usize| Span {
+        start_line: line,
+        start_col: 0,
+        end_line: line + 8,
+        end_col: 1,
+    };
+
+    let mut graph = CodeGraph::new(NodeId("root".into()));
+
+    for f in 0..definers {
+        let path = format!("pkg_{}/mod_{f}.py", f % 32);
+        let file_id = NodeId::file(&path);
+        let mut children = Vec::new();
+        for (i, base) in HUB_NAMES.iter().enumerate() {
+            let name = if unique {
+                format!("{base}_{f}")
+            } else {
+                (*base).to_string()
+            };
+            let block_id = NodeId::code_block(&path, &name, i * 20);
+            graph.add_node(CodeNode::CodeBlock {
+                id: block_id.clone(),
+                name,
+                kind: BlockKind::Function,
+                span: span(i * 20),
+                signature: Some("def f(self):".to_string()),
+                visibility: None,
+                parent: file_id.clone(),
+                children: Vec::new(),
+            });
+            children.push(block_id);
+        }
+        graph.add_node(CodeNode::File {
+            id: file_id,
+            name: format!("mod_{f}.py"),
+            path,
+            language: Some(Language::Python),
+            children,
+        });
+    }
+
+    let mut refs = Vec::with_capacity(callers * refs_per_caller);
+    for c in 0..callers {
+        let path = format!("callers/caller_{c}.py");
+        let file_id = NodeId::file(&path);
+        graph.add_node(CodeNode::File {
+            id: file_id.clone(),
+            name: format!("caller_{c}.py"),
+            path,
+            language: Some(Language::Python),
+            children: Vec::new(),
+        });
+        for r in 0..refs_per_caller {
+            let base = HUB_NAMES[r % HUB_NAMES.len()];
+            let name = if unique {
+                // Point at a definer that exists, so the control resolves to
+                // exactly one symbol instead of missing entirely.
+                format!("{base}_{}", r % definers.max(1))
+            } else {
+                base.to_string()
+            };
+            refs.push(RawReference {
+                from_node: file_id.clone(),
+                kind: RawRefKind::FunctionCall,
+                name,
+                span: span(r * 3),
+            });
+        }
+    }
+
+    (graph, refs)
+}
+
+/// Symbol-table build + reference resolution on repos full of hub names.
+///
+/// `ambiguous` is the case the early-bail change targets: hundreds of candidates
+/// per name, all discarded. `unique_control` is the same volume of work with one
+/// candidate per name; the gap between them is the price of ambiguity.
+fn bench_resolve_hub_ambiguity(c: &mut Criterion) {
+    use cc_core::resolver::{ImportMap, SymbolTable};
+
+    let mut group = c.benchmark_group("resolve_hub_ambiguity");
+    group.sample_size(10);
+    group.warm_up_time(std::time::Duration::from_millis(500));
+    group.measurement_time(std::time::Duration::from_secs(4));
+
+    for definers in [500usize, 1000] {
+        let callers = definers / 2;
+        let refs_per_caller = 20;
+
+        for (label, unique) in [("ambiguous", false), ("unique_control", true)] {
+            let (graph, refs) = hub_ambiguity_fixture(definers, callers, refs_per_caller, unique);
+            let table = SymbolTable::build_from_graph(&graph);
+            let imports = ImportMap::new();
+
+            group.bench_with_input(
+                BenchmarkId::new(format!("{label}_resolve"), definers),
+                &(&table, &refs),
+                |b, &(table, refs)| {
+                    b.iter(|| black_box(table.resolve_references(refs, &imports)));
+                },
+            );
+
+            group.bench_with_input(
+                BenchmarkId::new(format!("{label}_build_table"), definers),
+                &graph,
+                |b, graph| {
+                    b.iter(|| black_box(SymbolTable::build_from_graph(graph)));
+                },
+            );
+        }
+    }
+    group.finish();
+}
+
 criterion_group!(
     benches,
     bench_extract_file,
     bench_extract_many_files,
     bench_full_pipeline,
+    bench_resolve_hub_ambiguity,
 );
 criterion_main!(benches);
diff --git a/crates/cc-core/examples/perf_harness.rs b/crates/cc-core/examples/perf_harness.rs
new file mode 100644
index 0000000..4fb863f
--- /dev/null
+++ b/crates/cc-core/examples/perf_harness.rs
@@ -0,0 +1,670 @@
+//! End-to-end performance harness: scan -> parse -> resolve, then the query
+//! battery the UI actually issues, printed as one JSON object on stdout.
+//!
+//! Criterion benches measure single functions on synthetic fixtures. This
+//! measures the thing a user waits for: opening a repo, and then interacting
+//! with it (expanding/collapsing containers, focusing nodes, drilling into an
+//! aggregated edge). It is the most representative number in the suite, and the
+//! one to quote when comparing two branches.
+//!
+//! # Portability across branches
+//!
+//! This file must compile UNCHANGED on `main` and on the perf branches so the
+//! same measurement runs on both. It therefore restricts itself to the cc-core
+//! public API that is identical on both sides:
+//!
+//! - `RepoScanner::scan`, `Extractor::extract_file`
+//! - `SymbolTable::build_from_graph`, `SymbolTable::resolve_references`
+//! - `ImportResolver::resolve`
+//! - `SubGraph::from_graph`, `CodeGraph::neighborhood`, `CodeGraph::edge_detail`
+//! - `ParseResult::from_graph` (owned on `main`, borrowing on the perf branch --
+//!   the CALL is identical, which is the point: the harness measures the
+//!   difference without naming it)
+//!
+//! It deliberately does NOT touch `build_parent_map` (main-only) or
+//! `CodeGraph::parent_map` (perf-branch-only), and never names `ParseResult` as
+//! a type.
+//!
+//! # Determinism
+//!
+//! Every choice the harness makes -- which nodes go in a render set, which nodes
+//! get focused, which aggregated edges get expanded -- is derived from a sorted
+//! id list indexed by a seeded SplitMix64 stream. Two runs on the same input
+//! therefore do the same work in the same order, so a delta between branches is
+//! a delta in cost, not in workload.
+//!
+//! # Usage
+//!
+//! ```text
+//! cargo run --release --example perf_harness -- --repo /path/to/repo --label main
+//! ```
+//!
+//! Flags: `--repo PATH` (required), `--label NAME`, `--seed N`,
+//! `--subgraph-reps N`, `--neighborhood-queries N`, `--edge-detail-queries N`,
+//! `--out FILE` (also write the JSON there).
+
+use std::collections::HashSet;
+use std::hint::black_box;
+use std::path::PathBuf;
+use std::time::{Duration, Instant};
+
+use cc_core::model::{
+    CodeGraph, CodeNode, EdgeKind, FocusDirection, Language, NodeId, ParseResult, SubGraph,
+};
+use cc_core::parser::Extractor;
+use cc_core::repo::RepoScanner;
+use cc_core::resolver::{ImportResolver, SymbolTable};
+use rayon::prelude::*;
+use serde_json::{json, Value};
+
+// ---------------------------------------------------------------------------
+// Deterministic RNG (SplitMix64) -- no rand dependency, identical on both
+// branches, and stable across Rust versions.
+// ---------------------------------------------------------------------------
+
+struct Rng(u64);
+
+impl Rng {
+    fn new(seed: u64) -> Self {
+        Rng(seed)
+    }
+
+    fn next_u64(&mut self) -> u64 {
+        self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15);
+        let mut z = self.0;
+        z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+        z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+        z ^ (z >> 31)
+    }
+
+    fn below(&mut self, n: usize) -> usize {
+        if n == 0 {
+            0
+        } else {
+            (self.next_u64() % n as u64) as usize
+        }
+    }
+}
+
+/// Pick `count` distinct items from `items` deterministically (sorted input +
+/// seeded stream), preserving the sampled order.
+fn sample<T: Clone>(rng: &mut Rng, items: &[T], count: usize) -> Vec<T> {
+    if items.is_empty() {
+        return Vec::new();
+    }
+    let count = count.min(items.len());
+    let mut taken: HashSet<usize> = HashSet::with_capacity(count);
+    let mut out = Vec::with_capacity(count);
+    // Bounded attempts: with count <= len this terminates quickly, and the
+    // fallback sweep guarantees it terminates at all.
+    let mut attempts = 0;
+    while out.len() < count && attempts < count * 8 {
+        attempts += 1;
+        let idx = rng.below(items.len());
+        if taken.insert(idx) {
+            out.push(items[idx].clone());
+        }
+    }
+    for (idx, item) in items.iter().enumerate() {
+        if out.len() >= count {
+            break;
+        }
+        if taken.insert(idx) {
+            out.push(item.clone());
+        }
+    }
+    out
+}
+
+// ---------------------------------------------------------------------------
+// Timing helpers
+// ---------------------------------------------------------------------------
+
+fn ms(d: Duration) -> f64 {
+    d.as_secs_f64() * 1000.0
+}
+
+/// Summary of a repeated measurement, in milliseconds.
+struct Samples {
+    values: Vec<f64>,
+}
+
+impl Samples {
+    fn new() -> Self {
+        Samples { values: Vec::new() }
+    }
+
+    fn push(&mut self, d: Duration) {
+        self.values.push(ms(d));
+    }
+
+    fn first(&self) -> f64 {
+        self.values.first().copied().unwrap_or(0.0)
+    }
+
+    /// Mean of every sample AFTER the first. On a branch that caches derived
+    /// state on the graph, the first call pays for the cache and the rest do
+    /// not; reporting both separates "cold" from "steady state" instead of
+    /// smearing them together.
+    fn steady_mean(&self) -> f64 {
+        if self.values.len() < 2 {
+            return self.first();
+        }
+        self.values[1..].iter().sum::<f64>() / (self.values.len() - 1) as f64
+    }
+
+    fn total(&self) -> f64 {
+        self.values.iter().sum()
+    }
+
+    fn min(&self) -> f64 {
+        self.values.iter().copied().fold(f64::INFINITY, f64::min)
+    }
+
+    fn to_json(&self) -> Value {
+        json!({
+            "samples": self.values.len(),
+            "first_ms": self.first(),
+            "steady_mean_ms": self.steady_mean(),
+            "min_ms": self.min(),
+            "total_ms": self.total(),
+        })
+    }
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+struct Args {
+    repo: PathBuf,
+    label: String,
+    seed: u64,
+    subgraph_reps: usize,
+    neighborhood_queries: usize,
+    edge_detail_queries: usize,
+    out: Option<PathBuf>,
+    dump_payload: Option<PathBuf>,
+}
+
+fn parse_args() -> Result<Args, String> {
+    let mut repo: Option<PathBuf> = None;
+    let mut label = "unlabelled".to_string();
+    let mut seed = 20_240_611u64;
+    let mut subgraph_reps = 6usize;
+    let mut neighborhood_queries = 200usize;
+    let mut edge_detail_queries = 50usize;
+    let mut out: Option<PathBuf> = None;
+    let mut dump_payload: Option<PathBuf> = None;
+
+    let mut argv = std::env::args().skip(1);
+    while let Some(arg) = argv.next() {
+        let mut value = || {
+            argv.next()
+                .ok_or_else(|| format!("{arg} requires a value"))
+        };
+        match arg.as_str() {
+            "--repo" => repo = Some(PathBuf::from(value()?)),
+            "--label" => label = value()?,
+            "--seed" => seed = value()?.parse().map_err(|e| format!("--seed: {e}"))?,
+            "--subgraph-reps" => {
+                subgraph_reps = value()?.parse().map_err(|e| format!("--subgraph-reps: {e}"))?
+            }
+            "--neighborhood-queries" => {
+                neighborhood_queries = value()?
+                    .parse()
+                    .map_err(|e| format!("--neighborhood-queries: {e}"))?
+            }
+            "--edge-detail-queries" => {
+                edge_detail_queries = value()?
+                    .parse()
+                    .map_err(|e| format!("--edge-detail-queries: {e}"))?
+            }
+            "--out" => out = Some(PathBuf::from(value()?)),
+            "--dump-payload" => dump_payload = Some(PathBuf::from(value()?)),
+            "--help" | "-h" => {
+                eprintln!(
+                    "perf_harness --repo PATH [--label NAME] [--seed N] \
+                     [--subgraph-reps N] [--neighborhood-queries N] \
+                     [--edge-detail-queries N] [--out FILE] \
+                     [--dump-payload FILE]"
+                );
+                std::process::exit(0);
+            }
+            other => return Err(format!("unknown argument: {other}")),
+        }
+    }
+
+    Ok(Args {
+        repo: repo.ok_or("--repo is required")?,
+        label,
+        seed,
+        subgraph_reps: subgraph_reps.max(2),
+        neighborhood_queries,
+        edge_detail_queries,
+        out,
+        dump_payload,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline
+// ---------------------------------------------------------------------------
+
+/// Every edge kind, i.e. the toolbar's default "show everything" state, which is
+/// the most expensive filter and the one the app starts in.
+fn all_edge_kinds() -> HashSet<EdgeKind> {
+    [
+        EdgeKind::Import,
+        EdgeKind::FunctionCall,
+        EdgeKind::MethodCall,
+        EdgeKind::TypeReference,
+        EdgeKind::Inheritance,
+        EdgeKind::TraitImpl,
+        EdgeKind::VariableUsage,
+    ]
+    .into_iter()
+    .collect()
+}
+
+struct Pipeline {
+    graph: CodeGraph,
+    timings: Value,
+    stats: Value,
+}
+
+/// Scan + parse + resolve, mirroring `cc_tauri::commands::parse_repo` phase for
+/// phase (minus the IPC progress events, which are not part of the cost being
+/// compared here).
+fn run_pipeline(root: &PathBuf) -> anyhow::Result<Pipeline> {
+    let t_scan = Instant::now();
+    let mut graph = RepoScanner::scan(root)?;
+    let scan_ms = ms(t_scan.elapsed());
+
+    let dir_count = graph.nodes.values().filter(|n| n.is_directory()).count();
+
+    // File nodes with a known language, in a deterministic order so the parallel
+    // parse is fed identically on every run.
+    let mut file_nodes: Vec<(NodeId, String, Language)> = graph
+        .nodes
+        .iter()
+        .filter_map(|(id, node)| match node {
+            CodeNode::File {
+                path,
+                language: Some(lang),
+                ..
+            } => Some((id.clone(), path.clone(), lang.clone())),
+            _ => None,
+        })
+        .collect();
+    file_nodes.sort_by(|a, b| a.1.cmp(&b.1));
+
+    // Phase 1: parse in parallel (I/O + tree-sitter).
+    let t_parse = Instant::now();
+    let parsed: Vec<(NodeId, Option<(Vec<CodeNode>, Vec<_>)>)> = file_nodes
+        .par_iter()
+        .map(|(file_id, rel_path, language)| {
+            let abs = root.join(rel_path);
+            let source = match std::fs::read_to_string(&abs) {
+                Ok(s) => s,
+                Err(_) => return (file_id.clone(), None),
+            };
+            match Extractor::extract_file(rel_path, &source, language) {
+                Ok(pair) => (file_id.clone(), Some(pair)),
+                Err(_) => (file_id.clone(), None),
+            }
+        })
+        .collect();
+    let parse_ms = ms(t_parse.elapsed());
+
+    // Phase 2: merge block nodes into the graph and collect raw references.
+    let t_merge = Instant::now();
+    let mut all_refs = Vec::new();
+    let mut total_blocks = 0usize;
+    let mut failed_files = 0usize;
+    for (file_id, result) in parsed {
+        let (nodes, refs) = match result {
+            Some(pair) => pair,
+            None => {
+                failed_files += 1;
+                continue;
+            }
+        };
+        total_blocks += nodes.len();
+        for node in nodes {
+            let is_top_level = matches!(&node, CodeNode::CodeBlock { parent, .. } if *parent == file_id);
+            let block_id = node.id().clone();
+            graph.add_node(node);
+            if is_top_level {
+                if let Some(file_node) = graph.nodes.get_mut(&file_id) {
+                    file_node.children_mut().push(block_id);
+                }
+            }
+        }
+        all_refs.extend(refs);
+    }
+    let merge_ms = ms(t_merge.elapsed());
+    let raw_refs = all_refs.len();
+
+    // Phase 3: resolution.
+    let t_symbols = Instant::now();
+    let symbol_table = SymbolTable::build_from_graph(&graph);
+    let symbol_table_ms = ms(t_symbols.elapsed());
+    let symbol_count = symbol_table.symbols.len();
+
+    let t_imports = Instant::now();
+    let (import_edges, import_map) = ImportResolver::resolve(&graph, &all_refs);
+    let import_resolve_ms = ms(t_imports.elapsed());
+    let import_edge_count = import_edges.len();
+
+    let t_import_insert = Instant::now();
+    for edge in import_edges {
+        graph.add_edge(edge);
+    }
+    let import_insert_ms = ms(t_import_insert.elapsed());
+
+    let t_resolve = Instant::now();
+    let edges = symbol_table.resolve_references(&all_refs, &import_map);
+    let symbol_resolve_ms = ms(t_resolve.elapsed());
+    let symbol_edge_count = edges.len();
+
+    let t_insert = Instant::now();
+    for edge in edges {
+        graph.add_edge(edge);
+    }
+    let symbol_insert_ms = ms(t_insert.elapsed());
+
+    let pipeline_total_ms = scan_ms
+        + parse_ms
+        + merge_ms
+        + symbol_table_ms
+        + import_resolve_ms
+        + import_insert_ms
+        + symbol_resolve_ms
+        + symbol_insert_ms;
+
+    let stats = json!({
+        "files_parsed": file_nodes.len(),
+        "files_failed": failed_files,
+        "directories": dir_count,
+        "blocks": total_blocks,
+        "nodes": graph.node_count(),
+        "edges": graph.edge_count(),
+        "raw_refs": raw_refs,
+        "symbols": symbol_count,
+        "import_edges_resolved": import_edge_count,
+        "symbol_edges_resolved": symbol_edge_count,
+    });
+
+    let timings = json!({
+        "scan_ms": scan_ms,
+        "parse_files_ms": parse_ms,
+        "merge_ms": merge_ms,
+        "symbol_table_ms": symbol_table_ms,
+        "import_resolve_ms": import_resolve_ms,
+        "import_edge_insert_ms": import_insert_ms,
+        "symbol_resolve_ms": symbol_resolve_ms,
+        "symbol_edge_insert_ms": symbol_insert_ms,
+        "pipeline_total_ms": pipeline_total_ms,
+    });
+
+    Ok(Pipeline {
+        graph,
+        timings,
+        stats,
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Render sets
+// ---------------------------------------------------------------------------
+
+/// One render set plus the label describing what the UI state it stands for.
+struct RenderSet {
+    name: &'static str,
+    ids: Vec<NodeId>,
+}
+
+/// Build the render sets the query battery runs against.
+///
+/// These are the states the canvas is actually in, ordered from "everything
+/// collapsed" to "everything expanded". The COLLAPSED ones are the interesting
+/// ones: every edge endpoint is a code block that is not in the render set, so
+/// aggregation has to walk block -> block -> file -> directory chains for both
+/// endpoints of every edge. That walk is what needs a child -> parent map, and
+/// it is the work the old flat bench fixture accidentally skipped entirely.
+fn build_render_sets(graph: &CodeGraph, rng: &mut Rng) -> Vec<RenderSet> {
+    let mut dirs: Vec<NodeId> = Vec::new();
+    let mut files: Vec<NodeId> = Vec::new();
+    let mut blocks: Vec<NodeId> = Vec::new();
+
+    for (id, node) in graph.nodes.iter() {
+        match node {
+            CodeNode::Directory { .. } => dirs.push(id.clone()),
+            CodeNode::File { .. } => files.push(id.clone()),
+            CodeNode::CodeBlock { .. } => blocks.push(id.clone()),
+        }
+    }
+    dirs.sort_by(|a, b| a.0.cmp(&b.0));
+    files.sort_by(|a, b| a.0.cmp(&b.0));
+    blocks.sort_by(|a, b| a.0.cmp(&b.0));
+
+    // Directories + a quarter of the files expanded to their blocks: the state
+    // a user lands in after drilling into a couple of packages.
+    let expanded_files: HashSet<NodeId> = sample(rng, &files, files.len() / 4)
+        .into_iter()
+        .collect();
+    let mut partial: Vec<NodeId> = dirs.iter().chain(files.iter()).cloned().collect();
+    for (id, node) in graph.nodes.iter() {
+        if let CodeNode::CodeBlock { parent, .. } = node {
+            if expanded_files.contains(parent) {
+                partial.push(id.clone());
+            }
+        }
+    }
+    partial.sort_by(|a, b| a.0.cmp(&b.0));
+
+    let mut dirs_files: Vec<NodeId> = dirs.iter().chain(files.iter()).cloned().collect();
+    dirs_files.sort_by(|a, b| a.0.cmp(&b.0));
+
+    let mut everything: Vec<NodeId> = dirs_files.iter().chain(blocks.iter()).cloned().collect();
+    everything.sort_by(|a, b| a.0.cmp(&b.0));
+
+    vec![
+        RenderSet {
+            name: "directories_only",
+            ids: dirs,
+        },
+        RenderSet {
+            name: "directories_and_files",
+            ids: dirs_files,
+        },
+        RenderSet {
+            name: "quarter_of_files_expanded",
+            ids: partial,
+        },
+        RenderSet {
+            name: "fully_expanded",
+            ids: everything,
+        },
+    ]
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+fn main() -> anyhow::Result<()> {
+    let args = match parse_args() {
+        Ok(args) => args,
+        Err(err) => {
+            eprintln!("error: {err}");
+            std::process::exit(2);
+        }
+    };
+
+    eprintln!("[perf_harness] label={} repo={}", args.label, args.repo.display());
+
+    let Pipeline {
+        graph,
+        timings,
+        stats,
+    } = run_pipeline(&args.repo)?;
+
+    eprintln!(
+        "[perf_harness] parsed: {} nodes, {} edges",
+        graph.node_count(),
+        graph.edge_count()
+    );
+
+    let kinds = all_edge_kinds();
+    let mut rng = Rng::new(args.seed);
+
+    // --- Payload: build + serialize the parse response -------------------
+    //
+    // Both branches expose `ParseResult::from_graph`; on `main` it deep-clones
+    // the node map, on the perf branch it borrows it and serializes slim nodes.
+    // The call site is identical, so the difference lands entirely in these two
+    // numbers plus the byte count.
+    let mut payload_build = Samples::new();
+    let mut payload_serialize = Samples::new();
+    let mut payload_bytes = 0usize;
+    for _ in 0..3 {
+        let t_build = Instant::now();
+        let result = ParseResult::from_graph(&graph);
+        payload_build.push(t_build.elapsed());
+
+        let t_ser = Instant::now();
+        let json = serde_json::to_string(&result)?;
+        payload_serialize.push(t_ser.elapsed());
+        payload_bytes = json.len();
+        if let Some(path) = &args.dump_payload {
+            // For inspecting WHAT the payload is made of (which fields carry the
+            // bytes), not just how many there are. Written once, not per rep.
+            std::fs::write(path, &json)?;
+        }
+        black_box(&json);
+    }
+
+    // --- Subgraph battery -------------------------------------------------
+    let render_sets = build_render_sets(&graph, &mut rng);
+    let mut subgraph_report = Vec::new();
+    let mut subgraph_total_ms = 0.0f64;
+
+    for set in &render_sets {
+        let mut samples = Samples::new();
+        let mut direct = 0usize;
+        let mut aggregated = 0usize;
+        for _ in 0..args.subgraph_reps {
+            let t = Instant::now();
+            let sub = SubGraph::from_graph(&graph, &set.ids, &kinds);
+            samples.push(t.elapsed());
+            direct = sub.edges.len();
+            aggregated = sub.aggregated_edges.len();
+            black_box(&sub);
+        }
+        subgraph_total_ms += samples.total();
+        let mut entry = samples.to_json();
+        entry["render_nodes"] = json!(set.ids.len());
+        entry["direct_edges"] = json!(direct);
+        entry["aggregated_edges"] = json!(aggregated);
+        entry["name"] = json!(set.name);
+        subgraph_report.push(entry);
+        eprintln!(
+            "[perf_harness] subgraph {:<26} {:>8} nodes  first {:>8.2}ms  steady {:>8.2}ms",
+            set.name,
+            set.ids.len(),
+            samples.first(),
+            samples.steady_mean()
+        );
+    }
+
+    // --- Neighborhood battery --------------------------------------------
+    //
+    // Focus nodes are drawn from actual edge endpoints (sorted, then sampled)
+    // so every query has something to walk.
+    let mut endpoints: Vec<NodeId> = graph
+        .edges
+        .iter()
+        .flat_map(|e| [e.source.clone(), e.target.clone()])
+        .collect::<HashSet<NodeId>>()
+        .into_iter()
+        .collect();
+    endpoints.sort_by(|a, b| a.0.cmp(&b.0));
+    let focus_nodes = sample(&mut rng, &endpoints, args.neighborhood_queries);
+
+    let mut neighborhood_nodes = 0usize;
+    let mut neighborhood_edges = 0usize;
+    let t_neighborhood = Instant::now();
+    for focus in &focus_nodes {
+        if let Some(n) = graph.neighborhood(focus, 2, &kinds, FocusDirection::Both) {
+            neighborhood_nodes += n.node_ids.len();
+            neighborhood_edges += n.edges.len();
+            black_box(&n);
+        }
+    }
+    let neighborhood_ms = ms(t_neighborhood.elapsed());
+
+    // --- Edge-detail battery ----------------------------------------------
+    //
+    // Drills into the aggregated edges of the most collapsed view -- the exact
+    // pairs a user can click on there.
+    let collapsed = SubGraph::from_graph(&graph, &render_sets[0].ids, &kinds);
+    let pairs: Vec<(NodeId, NodeId)> = collapsed
+        .aggregated_edges
+        .iter()
+        .take(args.edge_detail_queries)
+        .map(|e| (e.source.clone(), e.target.clone()))
+        .collect();
+
+    let mut edge_detail_edges = 0usize;
+    let t_edge_detail = Instant::now();
+    for (source, target) in &pairs {
+        if let Some(detail) = graph.edge_detail(source, target, &kinds) {
+            edge_detail_edges += detail.edges.len();
+            black_box(&detail);
+        }
+    }
+    let edge_detail_ms = ms(t_edge_detail.elapsed());
+
+    // --- Report ------------------------------------------------------------
+    let report = json!({
+        "label": args.label,
+        "repo": args.repo.display().to_string(),
+        "seed": args.seed,
+        "profile": if cfg!(debug_assertions) { "debug" } else { "release" },
+        "stats": stats,
+        "pipeline_ms": timings,
+        "payload": {
+            "bytes": payload_bytes,
+            "build": payload_build.to_json(),
+            "serialize": payload_serialize.to_json(),
+        },
+        "subgraph": {
+            "reps_per_render_set": args.subgraph_reps,
+            "battery_total_ms": subgraph_total_ms,
+            "render_sets": subgraph_report,
+        },
+        "neighborhood": {
+            "queries": focus_nodes.len(),
+            "depth": 2,
+            "total_ms": neighborhood_ms,
+            "mean_ms": if focus_nodes.is_empty() { 0.0 } else { neighborhood_ms / focus_nodes.len() as f64 },
+            "nodes_returned": neighborhood_nodes,
+            "edges_returned": neighborhood_edges,
+        },
+        "edge_detail": {
+            "queries": pairs.len(),
+            "total_ms": edge_detail_ms,
+            "mean_ms": if pairs.is_empty() { 0.0 } else { edge_detail_ms / pairs.len() as f64 },
+            "edges_returned": edge_detail_edges,
+        },
+    });
+
+    let rendered = serde_json::to_string_pretty(&report)?;
+    if let Some(path) = &args.out {
+        std::fs::write(path, format!("{rendered}\n"))?;
+    }
+    println!("{rendered}");
+    Ok(())
+}
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index 2090b68..b639225 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -142,6 +142,28 @@ Features Index:
         depends_on: [state-management, graph-model, zoom-views, palette]
         doc: docs/features/details-panel.md
 
+    benchmarking:
+        description: >
+            Performance measurement across all three layers, with no pass/fail gate anywhere.
+            Criterion benches cover cc-core's hot functions on fixtures shaped like real data --
+            nested Directory > File > CodeBlock trees rendered with containers COLLAPSED, so
+            aggregation actually walks ancestor chains (the previous flat fixture had an empty
+            parent map and skipped that path entirely). An end-to-end harness
+            (cc-core example perf_harness) runs scan -> parse -> resolve plus the UI's query
+            battery -- subgraph extraction at four render-set sizes, neighborhood BFS,
+            edge-detail drill-in, parse-payload build + serialize -- and prints one JSON object
+            of timings, graph stats and payload bytes; it is written against only the cc-core
+            API that is identical across compared branches, so the same binary source measures
+            both sides. A seeded Python generator produces byte-identical synthetic repos
+            (200/2000/10000 modules, configurable hub-name collision fraction driving resolver
+            ambiguity). A node script benchmarks the canvas edge-routing pass, degrading
+            gracefully where the obstacle index and routing budget do not exist. run_all.sh
+            drives every layer in one pass; the bench workflow uploads the same artifacts on
+            demand.
+        entry_points: [crates/cc-core/benches/graph_bench.rs, crates/cc-core/benches/parse_bench.rs, crates/cc-core/benches/common/mod.rs, crates/cc-core/examples/perf_harness.rs, benchmarks/gen_repo.py, benchmarks/run_all.sh, packages/app/benchmarks/edgeRouting.bench.ts, .github/workflows/bench.yml]
+        depends_on: [graph-model, parsing, resolution_precision, repo-scanning, canvas-rendering]
+        doc: docs/features/benchmarking.md
+
     error-handling:
         description: React ErrorBoundary components wrapping major UI sections for graceful error recovery.
         entry_points: [packages/app/src/components/ErrorBoundary.tsx, packages/app/src/App.tsx]
diff --git a/docs/features/benchmarking.md b/docs/features/benchmarking.md
new file mode 100644
index 0000000..4059baa
--- /dev/null
+++ b/docs/features/benchmarking.md
@@ -0,0 +1,241 @@
+# Benchmarking
+
+## Scope
+
+Everything needed to answer "is this branch faster, and by how much" with a
+number rather than an argument:
+
+- **Criterion microbenchmarks** over cc-core's hot functions, on fixtures shaped
+  like the data the app actually holds.
+- **An end-to-end harness** that runs the whole backend pipeline plus the query
+  battery the UI issues, and prints one JSON object of timings and graph stats.
+- **A synthetic repo generator** so both sides of a comparison see byte-identical
+  input at a chosen size and ambiguity level.
+- **A frontend routing benchmark** for the canvas redraw's edge-routing pass.
+- **A runner** that drives all four in one pass, and **a CI workflow** that
+  produces the same artifacts on demand.
+
+## Non-scope
+
+- **No pass/fail gate anywhere.** Nothing in this feature fails a build on a
+  timing. CI runs on shared, noisy hardware where a threshold would either fire
+  on noise or catch nothing; see the comment at the top of
+  `.github/workflows/bench.yml`.
+- **No historical tracking.** There is no time-series database and no
+  "compare against the last run on main" step. A comparison is two runs on ONE
+  machine, back to back, by a human who wants an answer.
+- **Not correctness.** Benches are not tests: they assert nothing, and
+  `cargo test -p cc-core` does not run them. Fixtures here may be changed freely
+  when they measure the wrong thing (and one of them did -- see below).
+- **Not the Tauri IPC boundary.** The harness measures cc-core, including
+  building and serializing the parse payload, but not Tauri's own transport.
+
+## Layers
+
+### 1. Criterion benches -- `crates/cc-core/benches/`
+
+| File | Groups |
+| --- | --- |
+| `graph_bench.rs` | `add_edge_*`, `rebuild_adjacency`, `subgraph_flat_no_hierarchy`, `subgraph_nested_collapsed`, `subgraph_fully_expanded`, `neighborhood_bfs`, `parse_result_serialize` |
+| `parse_bench.rs` | `extract_file`, `extract_many_files`, `full_pipeline`, `resolve_hub_ambiguity` |
+| `common/mod.rs` | shared fixtures: `nested_graph`, `flat_graph`, seeded `Rng`, `all_edge_kinds` |
+
+```bash
+cargo bench -p cc-core                       # full suite, default sampling
+cargo bench -p cc-core -- --quick            # smoke check that everything runs
+cargo bench -p cc-core --bench graph_bench -- subgraph_nested   # one group
+cargo bench -p cc-core -- --warm-up-time 1 --measurement-time 3 --sample-size 20
+```
+
+`common/mod.rs` lives in a subdirectory because cargo auto-discovers
+`benches/*.rs` as bench targets; a top-level `common.rs` would be compiled as a
+bench with no `main`.
+
+cc-core sets `[lib] bench = false`. Without it cargo builds a libtest bench
+harness for the lib (which contains no `#[bench]` functions) and runs it FIRST,
+and that harness rejects criterion's CLI flags -- so `cargo bench -p cc-core --
+--sample-size 20` failed before reaching a benchmark. A baseline checkout
+predating that line needs it copied in along with the bench files.
+
+#### The fixture trap this layer exists to avoid
+
+The original `bench_subgraph_extraction` built N flat `File` nodes with empty
+`children` arrays and ran `SubGraph::from_graph` over half of them. That graph
+has an EMPTY child -> parent map, so `find_render_ancestor` returned on its first
+probe and the aggregation path -- the only reason `SubGraph::from_graph` needs a
+parent map at all -- never executed. It measured precisely the input for which
+the parent map is irrelevant, and would have reported "no change" for any amount
+of work saved building or reusing it.
+
+`common::nested_graph` builds `Directory > File > CodeBlock > CodeBlock` trees
+(5 directory levels, 3-way fanout, 5 classes per file with 2 methods each) and
+puts every edge between two LEAF blocks. The benches then render with containers
+COLLAPSED, so both endpoints of every edge walk a real ancestor chain. The flat
+case is kept as `subgraph_flat_no_hierarchy` -- renamed to say what it is, a
+floor rather than a representative case.
+
+When adding a bench, ask what shape of input makes the code under test do its
+work, and build THAT. A fixture that skips the hot path is worse than no bench:
+it reports a confident zero.
+
+### 2. End-to-end harness -- `crates/cc-core/examples/perf_harness.rs`
+
+The most representative number in the suite. Runs scan -> parse -> resolve
+(mirroring `cc_tauri::commands::parse_repo` phase for phase, minus IPC), then:
+
+- builds and serializes the parse payload, reporting bytes and time;
+- runs `SubGraph::from_graph` over four render sets, from `directories_only`
+  (everything collapsed, maximum lifting) to `fully_expanded` (no lifting);
+- runs 200 `neighborhood` queries at depth 2;
+- runs 50 `edge_detail` drill-ins on the collapsed view's aggregated edges.
+
+```bash
+cargo run --release --example perf_harness -- --repo /path/to/repo --label main
+```
+
+Flags: `--repo` (required), `--label`, `--seed`, `--subgraph-reps`,
+`--neighborhood-queries`, `--edge-detail-queries`, `--out FILE`,
+`--dump-payload FILE`. JSON goes to stdout, progress to stderr.
+
+`--dump-payload` writes the serialized `ParseResult` itself, for answering "what
+is the payload MADE of" rather than just how big it is. Measuring per-field byte
+shares that way is what showed `signature` to be the fifth-largest contributor,
+not the first (see `benchmarks/RESULTS.md`).
+
+Two properties are load-bearing and must be preserved:
+
+- **It compiles unchanged on every branch being compared.** It uses only the
+  cc-core public API that is identical across them, and never names
+  `ParseResult` as a type (it is owned on `main`, borrowing on the perf branch --
+  the call is the same, which is exactly what makes the difference measurable).
+  It does not reference `build_parent_map` (main-only) or `CodeGraph::parent_map`
+  (perf-branch-only).
+- **Its workload is deterministic.** Every choice -- render-set membership, focus
+  nodes, drilled edges -- comes from a sorted id list indexed by a seeded
+  SplitMix64 stream. Nothing depends on `HashMap` iteration order, which is
+  randomized per process. A delta between runs is a delta in cost, not workload.
+
+Each measurement reports `first_ms` and `steady_mean_ms` separately. On a branch
+that caches derived state on the graph, the first call pays for the cache and the
+rest do not; averaging them together would hide both facts.
+
+### 3. Synthetic repo generator -- `benchmarks/gen_repo.py`
+
+```bash
+python3 benchmarks/gen_repo.py --preset medium --out "$TMPDIR/cc-bench-medium" --force
+python3 benchmarks/gen_repo.py --files 500 --depth 3 --hub-fraction 0.8 --out /tmp/hubby
+```
+
+Presets: `small` (200 modules), `medium` (2000), `large` (10000). Everything is
+driven by one seeded `random.Random`, so a given
+(seed, files, depth, hub-fraction, ts-fraction) tuple always produces the same
+tree -- which is what lets two checkouts be fed identical input.
+
+`--hub-fraction` is the knob that matters most for the resolver: it sets the
+share of modules defining the SAME names (`get`, `run`, `new`, `__init__`, ...).
+Non-hub modules call those names without defining them, so their references fall
+through to the global tiers where hundreds of candidates match. At `0.0` every
+symbol is unique and resolution is trivially cheap.
+
+`--out` is required and there is no default: generated trees never land inside
+the repository.
+
+### 4. Frontend routing bench -- `packages/app/benchmarks/edgeRouting.bench.ts`
+
+```bash
+cd packages/app
+node benchmarks/edgeRouting.bench.ts
+node benchmarks/edgeRouting.bench.ts --sizes 300x200,1500x1200 --reps 5 --json out.json
+```
+
+Deliberately NOT matched by the `tests/*.test.ts` glob: it is a stopwatch, not an
+assertion, and it takes minutes at the larger sizes.
+
+Three scenarios per size:
+
+| Scenario | What it is | Comparable across branches? |
+| --- | --- | --- |
+| `full_scan_routing` | obstacles collected per edge by scanning every node, then routed crossing-aware | Yes -- reimplemented inside the bench, so identical everywhere. Should come out EQUAL; a gap means the environments differ and the other numbers are suspect. |
+| `indexed_routing` | obstacles indexed once per redraw, queried per edge via `obstacleIndex.ts` | Only where that module exists; reported as `skipped` otherwise |
+| `shipped_redraw` | what this branch actually does at this size, budget gate included | Yes -- this is the user-visible number |
+
+The script degrades gracefully: `obstacleIndex.ts` and `edgeRoutingBudget.ts` are
+loaded through a `try`/`catch` dynamic import, and their absence turns
+`shipped_redraw` into "route everything, crossing-aware", which is the older
+shipped behaviour. Runtime imports use explicit `.ts` specifiers so the module
+chain loads under plain `node` (tsconfig sets `allowImportingTsExtensions`).
+
+### 5. Runner -- `benchmarks/run_all.sh`
+
+```bash
+benchmarks/run_all.sh <label> <output-dir> <synthetic-repos-dir> [real-repo-path]
+```
+
+Runs all four layers with fixed, uniform parameters and drops the raw output in
+one directory. The point is that the SAME commands run on both sides of a
+comparison; anything conditional belongs elsewhere.
+
+### 6. CI -- `.github/workflows/bench.yml`
+
+`workflow_dispatch` (with a size input), or a PR labelled `bench`. Builds the
+harness, generates a synthetic repo, runs the harness and a reduced-sampling
+criterion pass plus the frontend bench, and uploads everything as an artifact.
+No thresholds, by design.
+
+## Comparing two branches
+
+Results from one such comparison are recorded in `benchmarks/RESULTS.md`.
+
+1. **One machine, sequential runs.** Never compare a number from one machine
+   against a number from another, and never run the two passes concurrently.
+2. **Second checkout for the baseline.** `git worktree add --detach <path> origin/main`.
+3. **Copy the harness, generator, runner and frontend bench into the baseline
+   checkout UNCOMMITTED.** They are branch-independent by construction; copying
+   them in is what makes the older branch measurable at all.
+4. **Generate the synthetic repos once**, outside both checkouts, and point both
+   runs at them. Same for the real-repo case: pass the SAME `[real-repo-path]` to
+   both runs, or the two passes will be reading different source trees.
+5. **Run `benchmarks/run_all.sh` in each checkout** with different labels and
+   output directories.
+6. **State the build profile for each side.** `cargo bench` inherits from
+   `[profile.release]`, which branches can and do change. If one side has LTO
+   configured and the other does not, that asymmetry is real shipping behaviour
+   and should be reported as such -- but to separate an ALGORITHMIC win from a
+   build-flag win, re-run the faster side with the other's flags:
+
+   ```bash
+   CARGO_PROFILE_BENCH_LTO=false CARGO_PROFILE_BENCH_CODEGEN_UNITS=16 \
+     cargo bench -p cc-core -- --sample-size 20
+   ```
+
+7. **Report deltas as percentages with the absolute numbers next to them**, and
+   say how many samples each came from.
+
+## Files
+
+| Path | Role |
+| --- | --- |
+| `crates/cc-core/benches/common/mod.rs` | Shared fixtures. Exports `nested_graph`, `flat_graph`, `NestedGraph` (with `render_dirs` / `render_dirs_files` / `render_all`), `Rng`, `all_edge_kinds` |
+| `crates/cc-core/benches/graph_bench.rs` | Graph-model criterion benches |
+| `crates/cc-core/benches/parse_bench.rs` | Parser + resolver criterion benches, incl. `hub_ambiguity_fixture` |
+| `crates/cc-core/examples/perf_harness.rs` | End-to-end harness binary |
+| `benchmarks/gen_repo.py` | Synthetic repo generator |
+| `benchmarks/run_all.sh` | One-pass runner over every layer |
+| `benchmarks/RESULTS.md` | Recorded main-vs-branch comparison |
+| `packages/app/benchmarks/edgeRouting.bench.ts` | Canvas edge-routing benchmark |
+| `.github/workflows/bench.yml` | On-demand CI artifact producer |
+
+## Invariants and constraints
+
+- **The harness compiles on every branch under comparison.** Adding an API that
+  only exists on one of them breaks the comparison, not just the build. If a
+  needed signature genuinely diverges, keep the shared subset in the committed
+  file and apply a documented patch to the baseline checkout.
+- **Every fixture is seeded and order-independent.** No fixture, render set or
+  query list may depend on `HashMap`/`HashSet` iteration order.
+- **Benches are excluded from `cargo test`.** They carry `harness = false` and
+  must never gain assertions; a bench that can fail is a test in the wrong place.
+- **Generated repos never land in the working tree.** `--out` is mandatory.
+- **The frontend bench stays out of the test glob** (`benchmarks/`, not `tests/`)
+  and out of `tsconfig.json`'s `include` (which covers `src` only).
+- **CI has no timing thresholds.** Adding one requires dedicated hardware first.
diff --git a/packages/app/benchmarks/edgeRouting.bench.ts b/packages/app/benchmarks/edgeRouting.bench.ts
new file mode 100644
index 0000000..257fa6a
--- /dev/null
+++ b/packages/app/benchmarks/edgeRouting.bench.ts
@@ -0,0 +1,459 @@
+/**
+ * Edge-routing benchmark for the canvas redraw path.
+ *
+ *   cd packages/app && node benchmarks/edgeRouting.bench.ts
+ *   node benchmarks/edgeRouting.bench.ts --json out.json --sizes 300x200,800x500
+ *
+ * NOT part of the `node --test "tests/*.test.ts"` glob: it is a stopwatch, not
+ * an assertion, and it takes minutes at the larger sizes.
+ *
+ * # What it measures
+ *
+ * The per-redraw cost of turning laid-out edges into routed polylines. Three
+ * scenarios, each on the same synthetic layout:
+ *
+ * 1. `full_scan_routing` -- obstacles collected PER EDGE by scanning every
+ *    visible node, then `routePolylineAroundObstacles` with crossing-aware
+ *    scoring. This is what the renderer did before the obstacle index, and it is
+ *    reimplemented HERE rather than imported, so it is byte-identical on every
+ *    branch and can serve as the common yardstick.
+ * 2. `indexed_routing` -- obstacles indexed ONCE per redraw and queried per edge
+ *    via `src/canvas/layout/obstacleIndex.ts`. That module only exists on the
+ *    perf branch; where it is missing this scenario is reported as `skipped`.
+ * 3. `shipped_redraw` -- what the branch under test actually does at this size,
+ *    budget gate included. `src/canvas/renderers/edgeRoutingBudget.ts` also only
+ *    exists on the perf branch; without it the scenario falls back to
+ *    "route everything, crossing-aware", which is the older shipped behaviour.
+ *
+ * # Comparing branches
+ *
+ * - `full_scan_routing` is comparable across branches directly, and mostly
+ *   exists to prove the two runs are on comparable hardware/runtime: it should
+ *   come out roughly EQUAL. A large gap there means the environments differ and
+ *   the rest of the numbers should be distrusted.
+ * - `indexed_routing` vs `full_scan_routing` (same run) is the obstacle-index
+ *   win, measurable on the perf branch alone.
+ * - `shipped_redraw` old vs new is the user-visible number, and includes the
+ *   budget gate skipping routing entirely above its thresholds.
+ *
+ * Imports use explicit `.ts` specifiers so the module chain loads under plain
+ * `node` (see tsconfig `allowImportingTsExtensions`).
+ */
+
+import {
+  routePolylineAroundObstacles,
+  type NodeBox,
+  type Point,
+} from "../src/canvas/layout/edgeGeometry.ts";
+
+/** Mirrors `OBSTACLE_QUERY_MARGIN` in edgeDrawing.ts. */
+const OBSTACLE_QUERY_MARGIN = 160;
+
+/** No-reference-polylines sentinel, matching the renderer's shared constant. */
+const NO_REFERENCE_POLYLINES: Point[][] = [];
+
+// ---------------------------------------------------------------------------
+// Optional modules (perf branch only)
+// ---------------------------------------------------------------------------
+
+interface ObstacleIndexModule {
+  ObstacleIndex: new (entries: readonly unknown[]) => {
+    readonly size: number;
+    queryForPolyline(
+      points: readonly Point[],
+      margin: number,
+      excludeOwnerA?: string | null,
+      excludeOwnerB?: string | null
+    ): NodeBox[];
+  };
+  obstacleEntry: (ownerId: string, box: NodeBox) => unknown;
+}
+
+interface BudgetModule {
+  resolveEdgeRoutingMode: (input: {
+    renderedEdges: number;
+    visibleNodes: number;
+    edgesVisible?: boolean;
+  }) => "full" | "obstacles" | "none";
+  routesAroundObstacles: (mode: string) => boolean;
+  scoresEdgeCrossings: (mode: string) => boolean;
+}
+
+async function loadOptional<T>(specifier: string): Promise<T | null> {
+  try {
+    return (await import(specifier)) as T;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deterministic synthetic layout
+// ---------------------------------------------------------------------------
+
+/** SplitMix32: same layout on every run and every branch. */
+function makeRng(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x9e3779b9) >>> 0;
+    let z = state;
+    z = Math.imul(z ^ (z >>> 16), 0x21f0aaad) >>> 0;
+    z = Math.imul(z ^ (z >>> 15), 0x735a2d97) >>> 0;
+    return ((z ^ (z >>> 15)) >>> 0) / 0x100000000;
+  };
+}
+
+interface BenchNode {
+  id: string;
+  box: NodeBox;
+  labelBox: NodeBox;
+}
+
+interface BenchEdge {
+  source: string;
+  target: string;
+  points: Point[];
+}
+
+interface Layout {
+  nodes: BenchNode[];
+  nodesById: Map<string, BenchNode>;
+  edges: BenchEdge[];
+}
+
+/**
+ * A grid of boxes with edges between randomly chosen pairs, routed as the
+ * two-bend orthogonal polylines ELK produces. Edge endpoints are anchored on
+ * the box borders, so the polylines start out legal and the routing pass has to
+ * do real detour work where boxes sit in between.
+ */
+function buildLayout(nodeCount: number, edgeCount: number, seed = 20240611): Layout {
+  const rng = makeRng(seed);
+  const columns = Math.max(1, Math.ceil(Math.sqrt(nodeCount)));
+  const cellW = 260;
+  const cellH = 150;
+
+  const nodes: BenchNode[] = [];
+  for (let i = 0; i < nodeCount; i++) {
+    const col = i % columns;
+    const row = Math.floor(i / columns);
+    const x = col * cellW + 20 + Math.floor(rng() * 20);
+    const y = row * cellH + 20 + Math.floor(rng() * 20);
+    const width = 140 + Math.floor(rng() * 60);
+    const height = 48 + Math.floor(rng() * 24);
+    nodes.push({
+      id: `n${i}`,
+      box: { x, y, width, height },
+      labelBox: { x: x + 4, y: y - 18, width: width - 8, height: 14 },
+    });
+  }
+
+  const nodesById = new Map(nodes.map((n) => [n.id, n]));
+
+  const edges: BenchEdge[] = [];
+  for (let i = 0; i < edgeCount; i++) {
+    const a = nodes[Math.floor(rng() * nodes.length)];
+    let b = nodes[Math.floor(rng() * nodes.length)];
+    if (a === b) {
+      b = nodes[(nodes.indexOf(a) + 1) % nodes.length];
+    }
+    const start: Point = {
+      x: a.box.x + a.box.width,
+      y: a.box.y + a.box.height / 2,
+    };
+    const end: Point = { x: b.box.x, y: b.box.y + b.box.height / 2 };
+    const midX = (start.x + end.x) / 2;
+    edges.push({
+      source: a.id,
+      target: b.id,
+      points: [
+        start,
+        { x: midX, y: start.y },
+        { x: midX, y: end.y },
+        end,
+      ],
+    });
+  }
+
+  return { nodes, nodesById, edges };
+}
+
+function boxCenter(box: NodeBox): Point {
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+
+function boxContainsPoint(box: NodeBox, point: Point): boolean {
+  return (
+    point.x >= box.x &&
+    point.x <= box.x + box.width &&
+    point.y >= box.y &&
+    point.y <= box.y + box.height
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Scenario 1: full-scan obstacle collection (the pre-index renderer)
+// ---------------------------------------------------------------------------
+
+function fullScanObstacles(layout: Layout, edge: BenchEdge): NodeBox[] {
+  const source = layout.nodesById.get(edge.source)!;
+  const target = layout.nodesById.get(edge.target)!;
+  const sourceCenter = boxCenter(source.box);
+  const targetCenter = boxCenter(target.box);
+  const obstacles: NodeBox[] = [];
+
+  for (const node of layout.nodes) {
+    if (node.id === edge.source || node.id === edge.target) continue;
+
+    if (
+      !boxContainsPoint(node.labelBox, sourceCenter) &&
+      !boxContainsPoint(node.labelBox, targetCenter)
+    ) {
+      obstacles.push(node.labelBox);
+    }
+    if (
+      !boxContainsPoint(node.box, sourceCenter) &&
+      !boxContainsPoint(node.box, targetCenter)
+    ) {
+      obstacles.push(node.box);
+    }
+  }
+
+  return obstacles;
+}
+
+function routeFullScan(layout: Layout, scoreCrossings: boolean): number {
+  const routed: Point[][] = [];
+  let points = 0;
+  for (const edge of layout.edges) {
+    const result = routePolylineAroundObstacles(
+      edge.points,
+      fullScanObstacles(layout, edge),
+      scoreCrossings ? routed : NO_REFERENCE_POLYLINES
+    );
+    if (scoreCrossings) routed.push(result);
+    points += result.length;
+  }
+  return points;
+}
+
+// ---------------------------------------------------------------------------
+// Scenario 2: indexed obstacle collection (perf branch)
+// ---------------------------------------------------------------------------
+
+function routeIndexed(
+  layout: Layout,
+  mod: ObstacleIndexModule,
+  scoreCrossings: boolean
+): number {
+  const entries = layout.nodes.flatMap((node) => [
+    mod.obstacleEntry(node.id, node.labelBox),
+    mod.obstacleEntry(node.id, node.box),
+  ]);
+  const index = new mod.ObstacleIndex(entries);
+
+  const routed: Point[][] = [];
+  let points = 0;
+  for (const edge of layout.edges) {
+    const source = layout.nodesById.get(edge.source)!;
+    const target = layout.nodesById.get(edge.target)!;
+    const sourceCenter = boxCenter(source.box);
+    const targetCenter = boxCenter(target.box);
+
+    const candidates = index.queryForPolyline(
+      edge.points,
+      OBSTACLE_QUERY_MARGIN,
+      edge.source,
+      edge.target
+    );
+    const obstacles: NodeBox[] = [];
+    for (const box of candidates) {
+      if (boxContainsPoint(box, sourceCenter) || boxContainsPoint(box, targetCenter)) {
+        continue;
+      }
+      obstacles.push(box);
+    }
+
+    const result = routePolylineAroundObstacles(
+      edge.points,
+      obstacles,
+      scoreCrossings ? routed : NO_REFERENCE_POLYLINES
+    );
+    if (scoreCrossings) routed.push(result);
+    points += result.length;
+  }
+  return points;
+}
+
+// ---------------------------------------------------------------------------
+// Timing
+// ---------------------------------------------------------------------------
+
+interface Timing {
+  name: string;
+  status: "ok" | "skipped";
+  reps?: number;
+  meanMs?: number;
+  minMs?: number;
+  totalMs?: number;
+  note?: string;
+}
+
+/**
+ * Run `fn` up to `reps` times, stopping early once `budgetMs` of wall time is
+ * spent. The heavy scenarios take tens of seconds per rep; a fixed rep count
+ * would make the suite unusable at the top size.
+ */
+function time(name: string, reps: number, budgetMs: number, fn: () => unknown): Timing {
+  const samples: number[] = [];
+  const deadline = performance.now() + budgetMs;
+
+  // One untimed warm-up so JIT tiering does not land entirely in sample 1.
+  fn();
+
+  for (let i = 0; i < reps; i++) {
+    const start = performance.now();
+    fn();
+    samples.push(performance.now() - start);
+    if (performance.now() > deadline) break;
+  }
+
+  const total = samples.reduce((a, b) => a + b, 0);
+  return {
+    name,
+    status: "ok",
+    reps: samples.length,
+    meanMs: total / samples.length,
+    minMs: Math.min(...samples),
+    totalMs: total,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+interface SizeSpec {
+  nodes: number;
+  edges: number;
+}
+
+function parseSizes(raw: string | undefined): SizeSpec[] {
+  if (!raw) {
+    return [
+      { nodes: 300, edges: 200 },
+      { nodes: 800, edges: 500 },
+      { nodes: 1500, edges: 1200 },
+    ];
+  }
+  return raw.split(",").map((chunk) => {
+    const [nodes, edges] = chunk.split("x").map((n) => Number.parseInt(n, 10));
+    if (!Number.isFinite(nodes) || !Number.isFinite(edges)) {
+      throw new Error(`bad --sizes entry: ${chunk} (expected e.g. 800x500)`);
+    }
+    return { nodes, edges };
+  });
+}
+
+function flag(name: string): string | undefined {
+  const idx = process.argv.indexOf(`--${name}`);
+  return idx >= 0 ? process.argv[idx + 1] : undefined;
+}
+
+async function main(): Promise<void> {
+  const sizes = parseSizes(flag("sizes"));
+  const label = flag("label") ?? "unlabelled";
+  const reps = Number.parseInt(flag("reps") ?? "5", 10);
+  const budgetMs = Number.parseInt(flag("budget-ms") ?? "20000", 10);
+
+  const obstacleMod = await loadOptional<ObstacleIndexModule>(
+    "../src/canvas/layout/obstacleIndex.ts"
+  );
+  const budgetMod = await loadOptional<BudgetModule>(
+    "../src/canvas/renderers/edgeRoutingBudget.ts"
+  );
+
+  process.stderr.write(
+    `[edgeRouting.bench] label=${label} obstacleIndex=${obstacleMod ? "present" : "absent"} ` +
+      `routingBudget=${budgetMod ? "present" : "absent"}\n`
+  );
+
+  const results: Array<{ nodes: number; edges: number; timings: Timing[] }> = [];
+
+  for (const size of sizes) {
+    const layout = buildLayout(size.nodes, size.edges);
+    const timings: Timing[] = [];
+
+    timings.push(
+      time("full_scan_routing", reps, budgetMs, () => routeFullScan(layout, true))
+    );
+
+    if (obstacleMod) {
+      timings.push(
+        time("indexed_routing", reps, budgetMs, () =>
+          routeIndexed(layout, obstacleMod, true)
+        )
+      );
+    } else {
+      timings.push({
+        name: "indexed_routing",
+        status: "skipped",
+        note: "src/canvas/layout/obstacleIndex.ts does not exist on this branch",
+      });
+    }
+
+    // What this branch actually does for a redraw of this size.
+    if (budgetMod && obstacleMod) {
+      const mode = budgetMod.resolveEdgeRoutingMode({
+        renderedEdges: size.edges,
+        visibleNodes: size.nodes,
+      });
+      const scoreCrossings = budgetMod.scoresEdgeCrossings(mode);
+      const routes = budgetMod.routesAroundObstacles(mode);
+      const timing = time("shipped_redraw", reps, budgetMs, () =>
+        routes ? routeIndexed(layout, obstacleMod, scoreCrossings) : 0
+      );
+      timing.note = `budget mode=${mode}`;
+      timings.push(timing);
+    } else {
+      const timing = time("shipped_redraw", reps, budgetMs, () =>
+        routeFullScan(layout, true)
+      );
+      timing.note = "no routing budget on this branch: always full-scan, crossing-aware";
+      timings.push(timing);
+    }
+
+    for (const t of timings) {
+      process.stderr.write(
+        `  ${size.nodes}n/${size.edges}e ${t.name.padEnd(18)} ` +
+          (t.status === "ok"
+            ? `${t.meanMs!.toFixed(1)}ms mean over ${t.reps} reps${t.note ? ` (${t.note})` : ""}\n`
+            : `skipped (${t.note})\n`)
+      );
+    }
+
+    results.push({ nodes: size.nodes, edges: size.edges, timings });
+  }
+
+  const report = {
+    label,
+    runtime: process.version,
+    obstacleIndexAvailable: Boolean(obstacleMod),
+    routingBudgetAvailable: Boolean(budgetMod),
+    reps,
+    sizes: results,
+  };
+
+  const rendered = `${JSON.stringify(report, null, 2)}\n`;
+  const out = flag("json");
+  if (out) {
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(out, rendered);
+  }
+  process.stdout.write(rendered);
+}
+
+main().catch((error: unknown) => {
+  process.stderr.write(`edgeRouting.bench failed: ${String(error)}\n`);
+  process.exitCode = 1;
+});