chore: import upstream snapshot with attribution

docs/design/value-reference-edges.md

@@ -0,0 +1,469 @@
+# Design + status: same-file value-reference edges
+
+**Status:** SHIPPED (default-on for TS/JS/tsx + Go + Python + Rust + Ruby + C + Java + C# + PHP + Scala + Kotlin + Swift + Dart + Pascal; `CODEGRAPH_VALUE_REFS=0` disables). The
+emitter lives in `TreeSitterExtractor.flushValueRefs` (`src/extraction/tree-sitter.ts`).
+**Motivation:** close the impact-analysis hole for *value consumers*. Static
+extraction edges calls, imports, and inheritance, but never edges a constant to the
+symbols that read it — so changing a config object / lookup table / shared constant
+looked like "nothing depends on this." This is the "change this table, break its
+readers" class of change (the ReScript-PR false positive that motivated the work).
+
+---
+
+## TL;DR for a new session
+
+We emit a `references` edge (`metadata: { valueRef: true }`) from a reader symbol to
+the **file/package-scope `const`/`var` it reads**, same-file only, for TS/JS/tsx + Go + Python + Rust + Ruby + C + Java + C# + PHP + Scala + Kotlin + Swift + Dart + Pascal. Those edges
+flow straight into `getImpactRadius` / `codegraph impact` and the impact trail in
+`codegraph_explore` / `codegraph_node` — no agent-behaviour change required.
+
+The win is **impact-radius correctness**, not agent read-reduction (see "Agent A/B").
+
+## Edge semantics
+
+- **Target:** a file-scope `const`/`var` whose name is "distinctive" (≥3 chars and
+  contains an uppercase letter or `_`) — dodges the local-shadowing precision trap
+  that single-letter / all-lowercase names invite.
+- **Reader (source):** any `function` / `method` / `const` / `var` symbol whose body
+  references the target name.
+- **Same-file only** — resolution is unambiguous without import/scope analysis.
+- **Deduped** per `(reader, target)`. **Additive** — adds edges, never nodes.
+
+## Precision guards (in emission order)
+
+1. **`isGeneratedFile(path)`** — skip suffix-recognised generated files (`.pb.ts`,
+   `.min.js`, …). Path-only; it cannot catch content-minified bundles.
+2. **Shadow prune** — drop a target when its **declarator count exceeds its file-scope node
+   count**, i.e. it's also bound in an *inner* (local) scope. A bundled/Emscripten `const
+   Module` re-declared as an inner `var Module`, a Go package const shadowed by a local `:=`,
+   or a Python module const shadowed by a local `=` all resolve to the inner binding for nested
+   readers — a file-scope edge would be a false positive. Inner re-bindings aren't graph nodes,
+   so declarators are counted at the syntax level (per-grammar node types: `variable_declarator`
+   for TS/JS, `const_spec`/`var_spec`/`short_var_declaration` for Go, `assignment` for Python,
+   `const_item`/`static_item`/`let_declaration` for Rust).
+   Comparing against file-scope node count (not a flat ">1") keeps **conditional module defs**
+   (`try: X=…; except: X=…`), which legitimately bind a name twice at file scope. This catches
+   the content-minified bundles guard #1 misses.
+3. **Distinctive-name + same-file** as above.
+
+## Validation matrix — TS / JS / Go / Python / Rust / Ruby / C / Java / C# / PHP / Scala / Kotlin / Swift / Dart / Pascal
+
+Method per repo: index the same tree twice (value-refs on vs `CODEGRAPH_VALUE_REFS=0`),
+diff node/edge counts, spot-check precision, and measure `codegraph impact` on a few
+file-scope consts. Node count must be **identical** on/off (edges-only feature).
+
+**TypeScript**
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| sindresorhus/ky | small | 54 | 562 (stable) | +29 (0.8%) | all sampled TP | — |
+| excalidraw/excalidraw | medium | 645 | 10,301 (stable) | +717 (1.6%) | TP after shadow prune (#895 removed 23 woff2-bundle FPs) | `tablerIconProps` 1→**170** |
+| microsoft/vscode | large | 11,548 | 333,999 (stable) | +10,605 (0.69%) | all sampled TP; no param-shadow / bundle FPs in top 200 | `LayoutStateKeys` 1→**85**, `CORE_WEIGHT` 1→52 |
+
+**JavaScript** (same extractor; CommonJS, `var`, IIFE/UMD)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| expressjs/express | small | 147 | 1,082 (stable) | +27 (0.75%) | all sampled TP | — |
+| eslint/eslint | medium | 1,420 | 7,167 (stable) | +1,192 (4.2%) | all sampled TP; guard holds; no minified-file FPs | `internalSlotsMap` 1→**32**, `INDEX_MAP` 1→27 |
+| webpack/webpack | large | 9,371 | 28,922 (stable) | +3,521 (4.8%) | all sampled TP; guard holds; no minified-file FPs | `LogType` 1→**89**, `LOG_SYMBOL` 1→90, `UsageState` 2→52 |
+
+**Go** (package-level `const`/`var`; required extending the shadow prune — see below)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| gin-gonic/gin | small | 110 | 2,599 (stable) | +166 (1.9%) | all sampled TP; guard holds | `abortIndex` 1→**24**, `jsonContentType` 1→8 |
+| gohugoio/hugo | medium | 952 | 19,160 (stable) | +1,616 (2.5%) | all sampled TP; guard holds | `filepathSeparator` 2→**26** |
+| prometheus/prometheus | large | 1,329 | 23,322 (stable) | +3,466 (3.3%) | all sampled TP; guard holds | `rdsLabelInstance` 1→**82**, `ec2Label` 1→24 |
+| kubernetes/kubernetes | very large | 19,160 | 251,086 (stable) | +20,574 (1.9%) | all sampled TP; guard holds on 250 targets | `KubeletSubsystem` 3→**138**, `LEVEL_0` 1→102 |
+
+**Python** (module-level `NAME = …`; required extending the prune *and* refining its rule — see below)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| psf/requests | small | 49 | 1,299 (stable) | +85 (2.9%) | all sampled TP; guard holds | `ITER_CHUNK_SIZE` 1→4, `DEFAULT_POOLBLOCK` 1→4 |
+| sqlalchemy/sqlalchemy | medium | 679 | 59,963 (stable) | +1,929 (0.8%) | all sampled TP; guard holds | `COMPARE_FAILED` 1→**26**, `DB_LINK_PLACEHOLDER` 1→19 |
+| django/django | large | 3,005 | 61,748 (stable) | +1,328 (0.7%) | all sampled TP; guard holds | `_trans` 1→**138**, `SEARCH_VAR` 4→8 |
+
+**Rust** (module-level `const`/`static`; declarators added, no rule change needed)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| BurntSushi/ripgrep | small | 107 | 3,731 (stable) | +144 (0.9%) | all sampled TP; guard holds | `SHERLOCK` 7→**113** |
+| tokio-rs/tokio | medium | 795 | 13,281 (stable) | +476 (1.1%) | all sampled TP; `#[cfg]`-conditional consts kept | `PERMIT_SHIFT` 1→**97**, `LOCAL_QUEUE_CAPACITY` 2→46 |
+| rust-lang/rust-analyzer | large | 1,530 | 38,780 (stable) | +475 (0.25%) | all sampled TP; 0 real shadow leaks | `INLINE_CAP` 2→**183**, `SPAN_PARTS_BIT` 2→18 |
+
+**Ruby** (`CONST = …`, almost always **inside a class/module** — needed the class-scope extension)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| sinatra/sinatra | small | 96 | 1,800 (stable) | +73 (2.1%) | ~100% TP (flags are valid nested reads) | `HEADER_PARAM` 1→**5** |
+| jekyll/jekyll | medium | 218 | 1,906 (stable) | +100 (2.4%) | ~100% TP | `DEFAULT_PRIORITY` 1→3, `LOG_LEVELS` 4→5 |
+| rails/rails | large | 1,452 | 61,911 (stable) | +2,255 (1.2%) | ~98% TP (same-file ambiguity 21/1208 targets) | `Post` (Struct const) 75 readers |
+
+**C** (file-scope `static const` scalars + pointer/array lookup tables + mutable globals; required
+extracting the nodes first — see below)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| redis/hiredis | small | 52 | 1,161 (stable) | +29 (2.5%) | all sampled TP; guard holds | `hiredisAllocFns` 1→**71** |
+| curl/curl | large | 994 | 16,124 (stable) | +597 (3.7%) | all sampled TP; guard holds; no minified FPs | `Curl_ssl` 3→**57** |
+| redis/redis | medium | 782 | 19,446 (stable) | +1,634 (8.4%) | all sampled TP after the macro-misparse fix; guard holds | `asmManager` 2→**97**, `keyMetaClass` 1→36, `XXH3_kSecret` 1→27, `helpEntries` 1→13 |
+
+**Java** (class-scope `static final` constants; required emitting them as `constant` kind — see below)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| google/gson | small | 262 | 8,563 (stable) | +387 | all sampled TP; guard holds | `PEEKED_NONE` 1→**31** |
+| apache/commons-lang | medium | 623 | 19,976 (stable) | +2,087 | all sampled TP; guard holds; no minified FPs | `INDEX_NOT_FOUND` 4→**165**, `EMPTY` 5→161 |
+| google/guava | large | 3,227 | 130,945 (stable) | +6,354 | all sampled TP; guard holds; no minified FPs | `APPLICATION_TYPE` 2→**126**, `ABSENT` 4→66 |
+
+**C#** (class-scope `const` / `static readonly`; same `field`→`constant` change as Java)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| AutoMapper/AutoMapper | small | 511 | 19,254 (stable) | +133 | all sampled TP; guard holds | `ContextParameter` 1→**17**, `InstanceFlags` 1→14 |
+| JamesNK/Newtonsoft.Json | medium | 945 | 20,208 (stable) | +344 | all sampled TP; guard holds | `DefaultFlags` 1→**37**, `JsonNamespaceUri` 1→15 |
+| dotnet/efcore | large | 5,731 | 140,847 (stable) | +3,720 | all sampled TP; guard holds; no minified FPs | `_resourceManager` 22→**1664**, `Prefix` 40→237, `Guid77` 2→191 |
+
+**PHP** (top-level `const` + class `const`, both already `constant`; needed only a reader-scan tweak — see below)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| guzzle/guzzle | small | 81 | 1,655 (stable) | +5 (sparse — see note) | all sampled TP; no collisions | `CONNECTION_ERRORS` 1→3 |
+| Seldaek/monolog | medium | 217 | 3,047 (stable) | +79 | all sampled TP; no class/const collisions | `DEFAULT_JSON_FLAGS` 1→**18**, `RFC_5424_LEVELS` 1→17 |
+| laravel/framework | large | 2,956 | 57,519 (stable) | +86 | all sampled TP; no minified/collision FPs | `INVISIBLE_CHARACTERS` 1→**93**, `SESSION_ID_LENGTH` 1→9 |
+
+**Scala** (top-level `val` + `object` val — re-kinded from `field`; `class` instance vals stay `field`)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| com-lihaoyi/upickle | small | 145 | 3,052 (stable) | +82 | all sampled TP; no class/method collisions | `IntegralPattern` 1→**9** |
+| typelevel/cats | medium | 835 | 15,774 (stable) | +89 | sampled TP; flagged val/def name-collisions were real object vals read by siblings | `maxArity` 3→**17**, `fusionMaxStackDepth` 1→13, `minIntValue` 1→7 |
+| apache/pekko | large | 2,720 | 135,041 (stable) | +8,453 (2,065 Scala) | Scala object vals clean; the bulk are valid Java `PARSER`/`DEFAULT_INSTANCE` from generated protobuf `.java` | `ErrorLevel` 5→**33**, `WarningLevel` 5→29 |
+
+**Kotlin** (top-level / `object` / `companion object` `val` → `constant`; `class` instance vals stay `field`)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| square/okio | small | 307 | 8,540 (stable) | +157 | all sampled TP; 0 collisions | `STATE_IN_QUEUE` 1→**32**, `HMAC_KEY` 1→9 |
+| Kotlin/kotlinx.coroutines | medium | 1,039 | 17,058 (stable) | +210 | all sampled TP; 1 cross-file collision | `BLOCKING_SHIFT` 1→**24**, `TERMINATED` 2→22 (companion bit-masks) |
+| ktorio/ktor | large | 2,302 | 43,272 (stable) | +849 | object/companion consts (HTTP header names); flagged collisions are real consts; `TYPE` is a sibling-companion ambiguity | `TYPE` 8→**109**, `FailedPath` 1→22 |
+
+**Swift** (top-level `let` + `static let` in `struct`/`enum`/`class` → `constant`; instance `let` stays `field`; computed properties skipped)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| Alamofire/Alamofire | small | 98 | 4,192 (stable) | +108 | all sampled TP; 0 collisions; computed properties skipped | `defaultRetryLimit` 1→3, `defaultWait` 1→4 |
+| apple/swift-argument-parser | medium | 165 | 4,435 (stable) | +36 | all sampled TP; 1 sibling-type collision (`usageString`) | `usageString` 8→**18**, `labelColumnWidth` 1→2 |
+| apple/swift-nio | large | 554 | 20,136 (stable) | +589 | all sampled TP; 0 collisions; `eventLoop` (static let) verified TP | `CONNECT_DELAYER` 1→**15**, `SINGLE_IPv4_RESULT` 1→12 |
+
+**Dart** (top-level `const`/`final` + class `static const`/`static final` = the `static_final_declaration` node → `constant`)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| dart-lang/http | small | 324 | 4,860 (stable) | +668 | real source TP; numbers skewed by a JNIGEN `_bindings.dart` (sibling-class collapse) | `Finishing` 1→**10**, `CONNECTION_PREFACE` 5→7 |
+| flame-engine/flame | medium | 1,655 | 19,608 (stable) | +465 | all sampled TP; bounded const-vs-getter collisions | `cardWidth` 4→**15**, `tileSize` 3→12 |
+| flutter/packages | large | 3,452 | 116,075 (stable) | +10,015 | real Flutter consts; some `.gen.dart` (pigeon) generated noise | `iconFont` 1→**1790**, `_channel` 6→72, `kMaxId` 1→23 |
+
+**Pascal / Delphi** (unit/class `const` → `constant`; **`constant`-only** targets — the extractor emits params/fields as `variable`)
+
+| Repo | size | files | nodes (on=off) | +value-ref edges | precision | `impact` on→off example |
+|---|---|---|---|---|---|---|
+| HashLoad/horse | small | 74 | 2,464 (stable) | +4 (sparse — cross-unit reads) | all sampled TP | `LOG_NFACILITIES` (Syslog const) |
+| synopse/mORMot2 | medium | 539 | 66,760 (stable) | +2,240 | precision sample 100% TP (font/crypto/DB consts); a few `const`-param misparse FPs in complex Delphi sigs | `LIB_CRYPTO` 1→**358**, `DEFAULT_ECCROUNDS` 1→31 |
+| castle-engine | large | 2,430 | 93,692 (stable) | +6,983 | top targets all real FFI binding consts; 0 collisions | `LazGio2_library` 2→**1880**, `LIB_CAIRO` 1→223 |
+
+Across S/M/L in all fifteen languages: node count never moved, the precision guards held, and
+the `impact` OFF column is the bug — a const that 80–140 symbols read reports "1 affected"
+without value-refs.
+
+**Go required a code change** (unlike JS/tsx, which the existing guards covered unchanged).
+Go puts its constants at package = file scope (good — the target gate fits), but its
+declarators are `const_spec`/`var_spec`/`short_var_declaration`, not `variable_declarator`, so
+the shadow prune was a no-op for Go and a package `const Timeout` shadowed by a local
+`Timeout := …` produced a false positive. Extending the prune's declarator switch to Go's node
+types fixed it (one synthetic repro, then clean across gin/hugo/prometheus). This is the
+template for the next language: **the shadow prune is per-grammar and must be wired per
+language** (see the playbook).
+
+**Python forced a refinement of the prune *rule* — a general improvement.** Python's
+declarator is `assignment` (added to the switch). But Python also **conditionally defines
+module constants** (`try: HAS_SSL = True; except: HAS_SSL = False`) — a very common idiom that
+binds the name twice *at module scope*. The old "bound more than once → drop" rule over-pruned
+these (dropping a real const and its readers). The fix distinguishes a conditional module def
+from a real shadow by comparing declarator count against the number of **file-scope nodes** the
+name has: a conditional def makes them equal (both bindings are file-scope), a local shadow
+makes declarators exceed file-scope nodes (the excess is the local). This is strictly more
+correct for *all* languages. (It also made the two halves of a conditional def cross-reference
+via their own names, so same-name value-ref edges are now suppressed.)
+
+**Rust needed only declarators — the rule was already right.** Rust's are `const_item` /
+`static_item` (module consts) and `let_declaration` (the local that shadows). Adding them to
+the switch fixed the expected shadow FP (a `const TIMEOUT` shadowed by a local `let TIMEOUT`).
+Rust also has the conditional-def pattern — `#[cfg(unix)] const SEP = …; #[cfg(windows)] const
+SEP = …` — and the Python-era file-scope-count rule already keeps those correctly (validated on
+tokio's `io/interest.rs` cfg-gated flags). One nice property fell out: consts written inside a
+config macro (`cfg_aio! { … }`) live in an unparsed token tree, so the prune's syntax walk
+doesn't even see them.
+
+**Ruby is the class-scope case — and required three changes.** Ruby keeps almost all constants
+*inside* a class/module (jekyll's `lib/`: 0 top-level vs 58 class-internal), so the original
+file-scope-only target gate covered ~nothing. Three Ruby-specific fixes: (1) the extractor now
+creates nodes for constant assignments (`CONST = …` has a `constant`-typed LHS, not
+`identifier`, so they were never extracted at all) — including class-internal ones; (2) the
+value-ref target gate accepts `class:`/`module:` parents, not just `file:`; (3) the reader-scan
+matches `constant` nodes, since in Ruby both a constant's definition and its references are
+`constant`-typed. **Effectively Ruby-only:** Rust impl consts are parented to `file:` already
+(so the gate change doesn't touch them — ripgrep stayed at 144 edges), and TS/Python class
+members aren't `constant`/`variable` kind.
+
+The interesting precision question — *which* class does a class-scope target belong to — turns
+out to favor a **file-wide** target map (a name maps to one target per file), because Ruby's
+constant lookup is **lexical + ancestor**: a method in a nested class legitimately reads an
+enclosing class's constant (verified on jekyll's `ERBRenderer→ThemeBuilder::SCAFFOLD_DIRECTORIES`
+and sinatra's `AcceptEntry→Request::HEADER_PARAM`). Strict same-class matching would wrongly drop
+those. The only real false positive is the same constant name defined in *sibling* (un-nested)
+classes in one file — 21 of 1,208 targets (1.7%) on rails, and most of those resolve fine too;
+referencing a sibling class's bare constant is a NameError in real Ruby, so valid code rarely
+hits it. Net precision ~98–100%.
+
+**C was NOT the "easy path" the language tracker first assumed — it needed the extractor to emit
+the nodes first.** C keeps shareable values at file scope (`static const` scalars, and very
+commonly pointer/array **lookup tables** + mutable global state), which fits the file-scope target
+gate. But unlike Go/Rust (whose const nodes already existed), C's file-scope `const`/`var` were
+**never extracted as nodes at all**: a C `declaration` nests its name inside an `init_declarator`
+(through `pointer_declarator`/`array_declarator`), and the generic variable-extraction fallback
+only finds a *direct* `identifier` child — so it produced nothing. Three changes (the same shape as
+Ruby's): (1) a C branch in `extractVariable` that resolves the name through the declarator chain and
+emits file-scope declarations as `constant`/`variable` (skipping function-body locals via an
+ancestor check, and `function_declarator` prototypes); (2) an `isConst` on the C extractor (a
+`const` `type_qualifier` → `constant` kind); (3) the shadow prune's declarator switch extended with
+`init_declarator`. Scoped to **C only** — C++ stays on the generic fallback (its class-scope members
+are the harder bucket).
+
+The one false-positive cluster the sweep surfaced was a **macro-prefixed-prototype misparse**, and
+the fix is the load-bearing C detail: an unknown leading macro (`CURL_EXTERN`, `XXH_PUBLIC_API`)
+makes tree-sitter-c misparse a prototype `MACRO RetType fn(args);` as a declaration whose declared
+"variable" is the **bare return-type identifier** (`XXH_errorcode`/`CURLcode`), splitting `fn(args)`
+off as a bogus expression — minting one spurious type-named global per prototype, then edged by
+every function returning that type (redis's `XXH_errorcode` 1→18 before the fix). These misparses
+*always* yield a **bare `identifier`** declarator (verified across pointer/array/sized return
+variants); real consts/tables always carry an initializer (`init_declarator`) and real
+pointer/array globals carry their own declarator. So the C branch **skips bare-`identifier`
+declarators entirely** — killing the whole FP class at the cost of only uninitialized scalar globals
+(`static int g;`), which are rare and low-value. After the fix: every sampled edge on
+hiredis/redis/curl was a true positive, the guard-invariant leak check found 0 shadows across all
+three, and `impact` deltas confirm the blind→real radius (`asmManager` 2→97, `Curl_ssl` 3→57,
+`hiredisAllocFns` 1→71).
+
+**Java + C# were the cleanest class-scope languages — one kind switch, no new guards.** Both keep
+constants *inside a class* (Java `static final` fields; C# `const` / `static readonly`), so unlike
+C the nodes already existed — but as **`field`** kind, which the value-ref gate (`constant`/
+`variable` only) rejects. The whole change was emitting the constant *subset* as `constant`: an
+`isConst` predicate on each extractor (Java = a `static final` field; C# = a `const`, or a `static
+readonly`) plus a kind switch in `extractField`. Everything else was already in place — the
+class-scope target gate (from Ruby), the `identifier` reader-scan, and crucially the shadow prune:
+a method-local that shadows a class const is a `variable_declarator` in both grammars, *already* in
+the prune switch, so a class const shadowed by a local is dropped with no new wiring (validated by
+the Java/C# shadow tests). Instance fields stay `field` — a Java instance `final` or a C# instance
+`readonly` is per-object state, not a shared constant, so it's never a target. The distinctive-name
+gate fits both conventions cleanly (Java `UPPER_SNAKE`, C# `PascalCase`), so no FP class emerged:
+across S/M/L (gson/commons-lang/guava, automapper/newtonsoft/efcore) every sampled edge was a true
+positive, 0 shadow leaks, no minified-file FPs, node count identical on/off. The `impact` wins are
+the headline — Java's canonical `public static final` constants (`INDEX_NOT_FOUND` 4→165, `EMPTY`
+5→161) and C#'s `const`/`static readonly` (`Prefix` 40→237, a generated `_resourceManager` 22→1664)
+all went from a blind "1 affected" to their real radius. The known sibling-class limitation (the
+same const name in two classes in one file resolves to the file-wide target) is shared with Ruby and
+stayed negligible.
+
+**PHP was a near-pure "easy path" — one reader-scan line, no extractor change, no prune wiring.**
+PHP already extracts both top-level `const X = …` and class `const X = …` as `constant` kind (a
+dedicated `const_declaration` handler), inside the right scope (`file:` / `class:`, both gated). The
+*only* change was the reader-scan: PHP represents a constant *reference* — bare `X`, or the const
+half of `self::X` / `Foo::X` / `static::X` — as a **`name`** node, which the scan (matching
+`identifier` / `constant`) missed, so it found nothing until `name` was added. That's safe across
+languages: `flushValueRefs` only runs for the value-ref set, and `name` is PHP-only among them. **No
+shadow prune was needed at all** — a PHP local is a `$var` (`variable_name`), a different namespace
+from a bare constant, so a local can *never* shadow a constant; there is nothing to prune (the
+cleanest case yet). Precision was excellent: UPPER_SNAKE constants fit the distinctive-name gate, and
+a dedicated check for a target whose name collides with a same-file *class* (PHP's one realistic FP —
+`name` nodes also name classes in `new Foo()` / `Foo::`) found **zero** collisions across
+guzzle/monolog/laravel; every sampled edge was a true positive, node count identical on/off.
+
+**The honest caveat: PHP is lower-yield than the class-scope languages, by design.** PHP idiom reads
+constants *across* files far more than within one (a `Logger::DEBUG` or a config constant consumed
+everywhere), and value-refs is **same-file only** — so laravel (2,956 files) produced only 86 edges
+vs. Ruby rails's 2,255 (1,452 files). This is not a miss: the cross-file reads are out of scope for
+*every* language (resolution would need import/scope analysis), and PHP simply leans on them more.
+The same-file reads it *does* capture are clean and the transitive impact wins are real
+(`INVISIBLE_CHARACTERS` 1→93 from 3 direct readers). Net: correct and additive, just a smaller
+absolute contribution than Java/C#/Go.
+
+**Scala — the `object` is the constant scope.** Scala has no `static`; the idiom for a shared
+constant is a `val` inside a singleton `object` (`object Config { val Timeout = 30 }`). A top-level
+`val` already extracted as `constant`, but `object` and `class` vals both came out as `field` (the
+gate rejects `field`). The fix is a kind refinement in the Scala `val_definition` handler: walk to
+the enclosing definition and treat an `object_definition` (or top level) val as `constant`/`variable`
+— while a `class`/`trait`/`enum` val stays `field`, because it is per-instance immutable state, the
+exact analogue of the Java instance `final` we also keep as `field`. (`object` and `class` both
+extract as `class` *kind*, so the distinction is the enclosing AST node type, not the node kind.)
+The shadow prune gained `val_definition`/`var_definition` (a method-local `val` can shadow an object
+val); the reader-scan needed nothing, since a Scala val reference is a plain `identifier`. Method-local
+vals are not extracted at all, so they're not a target source. The one **known limitation** is
+Scala's interchangeable `val`/`def` for members: a camelCase val can share a name with a method in the
+same file, and same-file name matching can't distinguish them — but it's bounded (like Ruby's
+sibling-class case), and on the sweep every flagged val/def collision turned out to be a real `object`
+val read by sibling vals (cats' typeclass instances: `val flatMap = monad`, read by
+`invariantSemigroupal`). Validated S/M/L (upickle/cats/pekko): node count identical on/off, top
+targets genuine object vals (`maxArity` `val = 22`, `DigitTens` lookup table), impact wins real
+(`maxArity` 3→17). The distinctive-name gate fits Scala's camelCase/PascalCase constants (`maxArity`,
+`IntegralPattern`) via their internal uppercase letter.
+
+**Kotlin combined three already-built techniques.** Kotlin has no `static`: shared constants live at
+top level, in an `object` (singleton), or in a class's `companion object` — all `val`/`const val`. A
+class instance `val` is per-object state. Nothing extracted before because a Kotlin property name
+nests (`property_declaration → variable_declaration → simple_identifier`) and the generic path reads
+only a direct child — the **C** problem. The fix handles `property_declaration` in the Kotlin
+`visitNode` hook (where the existing one already manages `fun interface` misparses): pull the nested
+name, then walk to the enclosing definition to set the kind — `object_declaration`/`companion_object`
+(or top level) → `constant`/`variable` (the **Scala** object-vs-class rule), `class_declaration` →
+`field`, and a property under a `function_body`/`init`/lambda is a local and skipped. The reader-scan
+gained `simple_identifier` (Kotlin's reference node — the **PHP `name`** move; `simple_identifier` is
+Kotlin-only among the value-ref set), and the shadow prune gained `property_declaration` (a method-local
+`val` can shadow an object const). Kotlin's parse fidelity is clean (its one known misparse,
+`fun interface`, is already handled), so unlike C++ no precision tail emerged. It validated as one of
+the *cleanest* languages: companion-object bit-masks and state constants are a heavy, same-file-read
+idiom (coroutines' `BLOCKING_SHIFT` 1→24, `TERMINATED` 2→22 in the scheduler; okio's `STATE_IN_QUEUE`
+1→32; ktor's content-type `TYPE` 8→109). okio had 0 collisions, coroutines 1 (cross-file). The same
+val/def-or-class name-overlap limitation as Scala applies (ktor's HTTP DSL names a header const and a
+class the same), plus the sibling-companion case (several `companion object { const val TYPE }` in one
+file collapse to the file-wide target, like Ruby's sibling-class) — both bounded, and every flagged
+collision investigated was a real object/companion const.
+
+**Swift reused the Kotlin techniques and added two Swift-specific touches.** Swift has no `static`
+keyword for globals; its shared-constant idiom is a top-level `let` or a `static let` inside a type —
+and Swift idiomatically *namespaces* constants in `enum`/`struct` (`enum Constants { static let X }`).
+A property name nests (`property_declaration → <name> pattern → simple_identifier`), the C-style
+problem; the reader-scan already matched `simple_identifier` (added for Kotlin — Swift shares it). The
+kind rule: top-level `let` and `static let` (in any type) → `constant` (`var` → `variable`); an
+*instance* `let`/`var` stays `field` (Swift instance stored properties otherwise aren't own nodes —
+unchanged). The two Swift-specific touches: (1) **the value-ref target gate was widened to `struct:`/
+`enum:` parents**, because Swift namespaces constants in those (every other language's targets sit at
+`file:`/`class:`/`module:`); without it, the heavily-used `enum`/`struct` static consts would all be
+missed. (2) **Computed properties are skipped** — a `var x: Int { … }` has a getter block, no stored
+value, and isn't a constant; the extractor detects the `computed_property` child and emits no node
+(verified: no computed-property leaks across the sweep). The node creation slots into the *existing*
+Swift `property_declaration` handler (which already extracts property-wrapper / type-annotation
+dependencies like `@Published`/`@State`), so that behavior is untouched. Validated S/M/L
+(Alamofire/swift-argument-parser/swift-nio): node count identical on/off, genuine static-let
+constants (`defaultRetryLimit`, swift-nio's `CONNECT_DELAYER`/`SINGLE_IPv4_RESULT` test constants, a
+shared `static let eventLoop` read by 37 methods), computed properties skipped, 0–1 collisions per
+repo (the same sibling-type name-overlap bound as Kotlin/Ruby).
+
+**Dart — the grammar did the scope separation; the catch was a sibling body.** Dart's tree-sitter
+grammar is unusually helpful here: a **`static_final_declaration`** node is *exactly* a top-level or
+class-`static` `const`/`final` — the shared-constant idiom — while instance fields and `var` use
+`initialized_identifier` and method-locals use `initialized_variable_definition`. So a single
+`visitNode` rule (`static_final_declaration` → `constant`, named by its `identifier` child) captures
+all and only the constants, with **no instance/local leaks to guard** and no scope-walk needed (the
+node stack gives `file:` for top-level, `class:` for a static member). The reader-scan was already
+covered (Dart references are plain `identifier`). The non-obvious bug: **Dart attaches a method/function
+`body` as a next *sibling* of the signature node** — and the signature is what gets stored as the
+reader scope — so the scan walked only the signature and produced *zero* edges until it was taught to
+also pull in a `function_body` next-sibling (Dart is the only value-ref language that structures bodies
+this way, so the check is inert elsewhere). The shadow prune counts all three Dart declarator nodes so
+a method-local `const X` correctly drops a file-scope `const X`. Validated S/M/L (http /
+flame-engine/flame / flutter/packages): node count identical on/off, genuine static consts on real
+source (flame's `cardWidth` 4→15, `tileSize` 3→12; HTTP/2's `Finishing` 1→10), the same bounded
+const-vs-getter name overlap as Kotlin/Scala. **The one caveat is generated code:** the common Dart
+codegen suffixes (`.g.dart` / `.freezed.dart` / `.pb.dart`) are already skipped by `isGeneratedFile`,
+but a header-only-marked generator (a JNIGEN `_bindings.dart` with hundreds of `static final _class`)
+isn't suffix-detected, so it collapses to the file-wide target and dominates a small repo's numbers
+(http) — real source stays clean.
+
+**Pascal / Delphi — the easy path plus the Dart sibling-body fix and a `constant`-only restriction.**
+Pascal keeps shared constants in a `const` section at unit (file) or class scope, and those *already*
+extracted as `constant` (`variableTypes: ['declConst', …]`), so wiring was add-to-`VALUE_REF_LANGS` +
+the shadow prune (`declConst`/`declVar` — a function-local `const X` shadows a unit `const X`). It hit
+the **same reader-scan bug as Dart**: Pascal attaches a proc body (`block`) as a *next sibling* of the
+`declProc` header (the reader scope), both under a `defProc`, so the same sibling-pull fix was extended
+to `block`. The Pascal-specific wrinkle is precision: the Pascal extractor emits function **parameters**
+(`const ATarget: TControl`, `var Dest: …`) and class **fields** as `variable` at the enclosing scope,
+which collapse to noisy file-wide targets — so **Pascal value-ref targets are restricted to
+`constant`** (genuine shared values are `const`; the cost is the rare unit-level `var` global). That
+cleaned the bulk (`var`-param/field FPs gone). A residual minority remains — tree-sitter-pascal
+*context-dependently* misparses a `const` parameter in a complex multi-line Delphi method signature as
+a `declConst` (the `ATarget` case; not reproducible in isolation), a parse-fidelity tail like C++ but
+far smaller. After the fix: a random precision sample on mORMot was 100% TP (font/crypto/DB constants
+referencing each other), castle's top targets are all real FFI binding consts with 0 collisions, and
+the headline is FFI library-name constants — `LazGio2_library = 'libgio-2.0…'` read by **1880**
+`external` declarations (2→1880), mORMot's `LIB_CRYPTO` 1→358. **Caveats:** low same-file density on
+app code (cross-unit reads; horse gave 4 edges), the `const`-only restriction, the rare const-param
+misparse, and Pascal's case-insensitivity (the exact-text reader-scan misses a differently-cased
+reference — a miss, never an FP).
+
+**C++ was attempted and reverted** — the machinery (file/namespace-scope + class `field_declaration`
+extraction) is correct on clean C++, but tree-sitter-cpp's parse fidelity on real template/macro-heavy
+code (and the `.h`→C-grammar routing) leaks class members and parameters to file scope as bogus
+constants. Two guards (skip declarations under an `ERROR` or `compound_statement` ancestor) removed
+~83% of the gross leaks, but the residual pervaded even well-structured library source
+(template-class member leaks, amalgamated mega-headers, `.h`-as-C++). It did not reach the precision
+bar the other languages hold, so it was reverted. Reviving C++ needs prior work on C++ parse handling
+(template-class member scoping, `.h`-as-C++ detection, amalgamated-header exclusion), not a value-refs
+wiring pass. See the playbook's §2b C++ note.
+
+**`tsx` is covered by the TS rows** — excalidraw is a React/.tsx codebase, so the headline
+`tablerIconProps` (1→170) and most of its targets live in `.tsx` files. The one
+tsx-specific path — a const read *only* inside JSX (`<Foo x={CONST}/>`) — relies on the
+reader-scan descending into the JSX subtree; it's locked by a unit test
+(`value-reference-edges.test.ts`), so no separate tsx repo sweep is needed.
+
+**Svelte / Vue / Astro are covered for free** — their extractors re-parse the `<script>` /
+frontmatter block as `typescript` / `javascript`, which are in `VALUE_REF_LANGS`, so a `const`
+in a `.svelte`/`.vue`/`.astro` script edges its readers without any extra work (verified on a
+synthetic `.svelte`). No separate matrix row. See the playbook's coverage tracker (§2b) for the
+full status against the README's language list.
+
+**JavaScript note — CommonJS `require` bindings are targets, and that's correct.** JS edge
+growth (~4–5%) runs higher than TS (~0.7–1.6%) because `var x = require('…')` bindings and
+module-level `var` state pass the distinctive-name gate and are read by same-file functions.
+These are *not* noise: changing such a binding (swap the dependency, reassign the state)
+genuinely affects its readers, so it's a legitimate impact target. Where it overlaps an
+existing `calls` edge, `getImpactRadius` dedups by node — no double-counting. (TS `import`s
+dodge this entirely: they're `import`-kind nodes, not `const`/`var`, so never targets.)
+
+## Agent A/B — what it does and doesn't buy (excalidraw, sonnet/high, 12 runs)
+
+- **Impact API (the win):** `impact` ON vs OFF — `tablerIconProps` 1→170,
+  `COLOR_PALETTE` 15→26, `CaptureUpdateAction` 61→86. This is what `codegraph impact`
+  and CodeGraph Pro's verdict engine consume via `getImpactRadius`.
+- **Agent read-displacement: none — and that's expected.** On an indexed repo the agent
+  answers impact questions in one codegraph call (0 Read / 0 Grep in *both* arms), and it
+  reaches for `codegraph_search` / `callers`, **not** `impact`/`explore`, so it often
+  doesn't query the value-ref edges at all. ON was never worse than OFF. **Do not claim
+  value-refs reduces agent reads** — the win is blast-radius correctness, not fewer turns.
+  (This is the "adapt the tool to the agent" wall: edges only help if the agent calls the
+  edge-traversing tool.)
+
+## Known limitations (intentional)
+
+- **Parameter-only shadowing** is not guarded. The shadow prune counts
+  `variable_declarator`s, so a file-scope const shadowed *only* by a function parameter of
+  the same name would slip through. Not observed in S/M/L TS validation, and guarding it
+  would over-prune legitimate consts whose name coincides with a parameter elsewhere in
+  the file — so it's left unguarded until a real repo surfaces it.
+- **Same-file only.** Cross-file value consumers (a const imported and read elsewhere) are
+  not edged; that needs import/scope resolution and is out of scope.
+- **Reactive/computed reads** (a value read only through a framework getter) have no static
+  identifier to match and aren't covered.
+
+## Extending to another language
+
+The step-by-step runbook — wiring checklist, validation scripts, FP hunts, per-language
+declarator types, and traps — is in
+[`value-reference-edges-playbook.md`](./value-reference-edges-playbook.md). Point a fresh
+session at it and say "Start on language X." In short: decide whether the language's
+constants are file/module-scope (fits) or class-scope (bigger change); confirm the declarator
+node type for the shadow prune; sweep small/medium/large public OSS repos; fix FP clusters;
+add a matrix row here + a test.