PHP node identity: interfaces/traits/enums get no declaration node — sourceless stubs shadow the real name, absorb its edges, and break lookup (failure mode #3, PE-78803)

[filipechagas]

Root-cause investigation of the last remaining PoC-gate blocker (node-identity stub shadowing), measured on the 0.9.37 pinned graph of api.lawnstarter.com @ d2d4bed7ae (46,406 nodes / 139,497 links). Fork code referenced @ a9adfc6 (v8). Related evidence: #37 (grading comment), open siblings #38/#39 (different bugs in the same repro neighborhood).

Symptom (Q4 / Q2 of the gate evals)

• graphify explain "BalanceitemRepository" silently resolves to a bare stub node (id balanceitemrepository, no source, degree 1) while graphify affected on the same name refuses with "No unique node match". The interface's real fan-in (38 production files) is invisible from the stub.
• graphify explain "ChargeCustomerCancellationFee" returns an ambiguity list: bare id chargecustomercancellationfee vs the real class node.

Root cause 1 (primary): PHP type declarations other than class produce no declaration node

_PHP_CONFIG.class_types = frozenset({"class_declaration"}) — graphify/extract.py:1065. tree-sitter-php emits interface_declaration, trait_declaration, enum_declaration (all with a name field; enums use enum_declaration_list as body), but none are in class_types, so no node is ever minted for a PHP interface, trait, or enum. Compare Java (extract.py:936) and Groovy (extract.py:952), which both include interface_declaration.

In the pinned api corpus that is 142 interfaces, 30 traits, 119 enums (291 declarations) with no canonical node. interface BalanceitemRepository (app/Repositories/Balanceitem/BalanceitemRepository.php:22) is one of them: the graph has its file node (label BalanceitemRepository.php) containing 28 method nodes directly, but no interface node (app_repositories_balanceitem_balanceitemrepository_balanceitemrepository is absent).

Everything below cascades from this: every resolution pass that could canonicalize edges has nothing to land on —

• fqn_to_id in _resolve_php_type_references (graphify/extractors/resolution.py:2721-2732) skips file nodes (label contains .) and methods (label ends )), so the interface's FQN resolves to nothing.
• _rewire_unique_stub_nodes (graphify/extract.py:2037) finds no sourced type-like node with the label, so stubs are never collapsed.

Cascade A — the bare shadow stub (the explain hijacker)

_php_emit_base (graphify/extractors/engine.py:3056-3071) handles implements/extends/trait-use and mints a sourceless stub without origin_file for an unresolved base name. _disambiguate_colliding_node_ids skips nodes with an empty source key (resolution.py:704-706), so this stub keeps the bare id (balanceitemrepository). Same-namespace implements (no use statement, as in DbBalanceitemRepository implements BalanceitemRepository) is non-"explicit" in the repoint pass, so it is left "for the legacy rewire" (resolution.py:2789-2792,2803) — which finds no unique real target (RC1). The bare stub survives with exactly the implements edge.

Cascade B — per-file stub fragmentation (Foo::CONST fan-in)

ensure_named_node (engine.py:2856-2878) mints per-file sourceless stubs with origin_file for type annotations. When N files each mint the same bare id, _disambiguate_colliding_node_ids salts each into <referencing-file-path>_php_<name> (resolution.py:694-714). references_constant edges (engine.py:5311-5330) resolve their target through the file-local label map, and references_constant is not in _PHP_REPOINT_RELATIONS (resolution.py:2490), so those edges are never re-pointed: the constant fan-in fragments across per-file stubs. Pinned graph: 17 stubs *_php_balanceitemrepository holding 20 references_constant edges.

Cascade C — imports/param-types land on the file node only by id collision

For files that do write use App\...\BalanceitemRepository, the repoint pass computes the FQN, misses fqn_to_id (RC1), and parks the edge on an "external" stub _make_id(fqn) (resolution.py:2798-2802, 2744-2760). Under PSR-4, _make_id("App\Repositories\Balanceitem\BalanceitemRepository") happens to equal the file node's id, so 69 references + 60 imports edges land on the file node (degree 171) — the fan-in survives, but attached to a node whose label (BalanceitemRepository.php) no longer exact-matches the type name. When the file name differs from the type name (e.g. a trait in Extras.php), the same path yields a sourceless FQN-labeled stub instead (verified in the minimal repro below).

Root cause 2 (independent): an imports edge whose target never got a stub node is invisible to all resolution

_import_php (extract.py:810-822) emits the edge with target _make_id(short_name) and creates no node. If the importing file never uses the name as a base/param type (e.g. only Foo::class), no stub node ever exists, so:

• the PHP repoint pass skips the edge (stub_label.get(tgt) → continue, resolution.py:2770-2773),
• _rewire_unique_stub_nodes never sees it (it iterates nodes, not edge endpoints),
• the dangling bare target survives into graph.json, and serve materializes an attributeless degree-1 node at load.

This hits classes too — the Q2 case: CustomerScheduleControllerTest.php has use App\Actions\Schedules\Cancellation\ChargeCustomerCancellationFee; (L7) and uses it only as ::class (L730, L764). The real class node exists; the import edge still dangles on bare chargecustomercancellationfee. The ::class/::CONST references themselves are silently dropped (file-local label-map miss at engine.py:5315 emits nothing).

Pinned-graph scale: 2,123 dangling endpoints; 19,303 imports edges have no target node; 1,802 distinct dangling ids match a real in-corpus declared type's normalized name, carrying 11,456 edges of recoverable fan-in. 1,471 sourceless stub nodes absorb ~16.3k edges (imports 6,307, references 4,426, calls 1,703, inherits 1,539, references_constant 1,150, mixes_in 780, implements 383).

Root cause 3 (lookup side): ambiguity detection groups rivals by source_file

find_node_ambiguity (graphify/serve.py:1382-1389) returns rivals only when the winning tier spans >1 distinct source_file. All sourceless stubs share source_file="", so Q4's 18 exact-tier stubs collapse into one group → no ambiguity reported → explain silently answers with matches[0] (graph-iteration order) = the bare stub. Q2's exact tier contains one sourced node + one sourceless → 2 groups → ambiguity reported. affected uses a different resolver (resolve_seed, graphify/affected.py:99-143) that requires a unique label match → refuses. That is the whole explain-vs-affected inconsistency.

Minimal repro (7 PHP files, AST-only, no API cost)

Corpus: interface FooRepository { const BAR; find(); } + same-namespace class DbFooRepository implements FooRepository + two consumers (use + ctor param + FooRepository::BAR) + trait Loggable/enum Status in Extras.php + a consumer + OnlyImport.php (use App\Repo\DbFooRepository; used only via ::class). Run graphify.extract.extract() on it. Observed (0.9.37):

• no FooRepository interface node; file node contains find() directly
• bare sourceless stub foorepository ← implements edge
• per-file stubs app_uses_consumer_php_foorepository, app_uses_consumer2_php_foorepository, each holding one references_constant edge
• imports/references [parameter_type] land on the file node app_repo_foorepository
• trait: mixes_in/imports land on sourceless FQN stub app_repo_loggable (label App\Repo\Loggable)
• enum: imports --> status dangling (no node); Status::Active reference dropped
• OnlyImport: imports --> dbfoorepository dangling even though the real class node exists in the corpus

Control: change interface FooRepository to class FooRepository, re-extract → zero sourceless stubs; implements/imports/references/references_constant ALL canonicalize onto app_repo_foorepository_foorepository. The one missing declaration-node type is the load-bearing difference.

Fix directions (not implemented)

1. RC1: add interface_declaration, trait_declaration, enum_declaration to _PHP_CONFIG.class_types (extract.py:1065), mirroring Java/Groovy. Caveats: enum bodies are enum_declaration_list (check body_fallback_child_types); the resolution.py:2688 raw-scan (class_declaration only) should also learn interface_declaration so interface-extends-interface edges resolve; check knock-on id shifts for interface methods (currently file-scoped, would become interface-scoped) on incremental rebuilds.
2. RC2: _resolve_php_type_references should resolve imports edges from their own target_fqn metadata (already stamped by _import_php since PHP use-import map 1/5: capture use FQN/alias metadata on imports edges #19) instead of requiring a stub node to read a label from.
3. RC3: find_node_ambiguity should not treat N sourceless rivals as one file; and/or exclude sourceless stubs from the exact tier when a sourced match exists.

Fixing RC1 alone flips Q4 (canonical node exists; stubs rewire onto it; explain/affected agree); RC2 fixes Q2's disambiguation round-trip; RC3 removes the silent-wrong-answer failure mode generally.

[filipechagas]

Triage (2026-08-07)

Split into four fix slices, mirroring the #37 → #40–#43 pattern; each is ready-for-agent and linked as a sub-issue:

• Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47 — RC1 (class_types gains interface/trait/enum declarations). Highest gate leverage: flips Q4 alone. Smallest diff, but carries the enum-body / raw-scan / method-id-shift caveats from the fix-directions section above.
• Stub-shadow fix 2/4: resolve imports edges from their own target_fqn metadata (RC2 of #46) #48 — RC2 (resolve imports edges from their own target_fqn metadata). Fixes Q2's disambiguation round-trip. Independent of Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47, though full recovery of interface/trait/enum import targets also needs Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47's nodes to exist.
• Stub-shadow fix 3/4: find_node_ambiguity must not collapse sourceless rivals into one group (RC3 of #46) #49 — RC3 (find_node_ambiguity sourceless-rival grouping). Correctness guard on lookup; removes the silent-wrong-answer mode generally. Serve-side only, independent.
• Stub-shadow fix 4/4: release + acceptance grading on the pinned api corpus #50 — release + acceptance grading on the pinned corpus (blocked by Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47/Stub-shadow fix 2/4: resolve imports edges from their own target_fqn metadata (RC2 of #46) #48/Stub-shadow fix 3/4: find_node_ambiguity must not collapse sourceless rivals into one group (RC3 of #46) #49 via native dependencies). Closes this issue with the grading comment, mirroring query: relational verbs ("calls"/"callers"/"uses") hijack seed selection and bury the real identifier's callers (upstream Graphify-Labs#2507) #37's protocol.

Priority order (gate impact, from the 0.9.37 eval re-run): RC1 > RC2 > RC3. All three are parallelizable — no inter-slice blockers.

Upstream angle: RC1 and RC2 look inherited from upstream Graphify-Labs/graphify (the class_types config and _import_php are upstream code paths, not fork divergence). Candidates for upstreaming once graded, following the #37 → upstream#2507 precedent.

Related issues checked during triage: #38 (receiver-type binding gap) and #39 (wrong calls edges) were verified against the pinned graph — both are independent mechanisms, not consequences of the stub shadowing here. #39's endpoints are sourced nodes, not sourceless stubs; details on that issue.

This issue stays open as the canonical spec / tracking parent; needs-triage removed. #50 closes it.

[filipechagas]

Acceptance grading — measured on a fresh post-fix rebuild of the pinned corpus

All four sub-issues are implemented and closed on fix/stub-shadowing-46: #47 (RC1, 9c4db41), #48 (RC2, 258d8e3), #49 (RC3, 313a168), plus the two siblings from the same repro neighborhood, #39 (075038e) and #38 (293d57e). Release 1606462 bumps the fork to 0.9.38 — required, not cosmetic: the AST cache is version-namespaced (cache/ast/v{version}), so a same-version rebuild would replay pre-fix cached nodes. Suite on the branch: 4,371 passed, 3 skipped (uv run --frozen pytest tests/ -q).

Grading setup. CLI reinstalled from the branch (graphify --version → graphify 0.9.38). ~/working/lawn/api was never touched; the corpus is a throwaway clone at /tmp/gfy-grade-api, git checkout d2d4bed7ae (graph stamps built_at_commit: d2d4bed7ae2d6fc2cdd7394785abd9fbb57c0c27). Rebuilt AST-only with graphify update . — the same command that produced the pinned 0.9.37 baseline (build log /tmp/gfy-build3-log.txt), same 6,108 uncached files, same two warnings, no LLM backend configured, zero API cost. Fresh clone ⇒ cold cache ⇒ the rebuild is guaranteed post-fix.

Pre/post table

PRE = /tmp/api-d2d4bed/graphify-out/graph.json (0.9.37). Every PRE figure below was recomputed from that file and reproduces this issue's body exactly.

Metric	PRE 0.9.37	POST 0.9.38	Δ
PHP interface/trait/enum declarations with no canonical node	291 (302 by direct tree-sitter count, see note)	0	−100%
graph.json nodes / links	46,406 / 139,497	46,268 / 142,106	−138 / +2,609
Distinct dangling edge endpoints (materialized at load)	2,123	0	−100%
Nodes as loaded by serve (raw + materialized)	48,529	46,268	−2,261
imports edges with no target node	19,303	0	−100%
Dangling ids matching a real in-corpus type / edges they carried	1,802 / 11,456	0 / 0	fully recovered
imports edges landing on an in-corpus sourced node	14,688 (36.4%)	26,426 (65.3%)	+11,738
imports edges parked on an external FQN-labelled stub	5,561 (13.8%)	12,687 (31.3%)	+7,126 (proven-external)
Sourceless nodes at load (declared stubs + materialized phantoms)	3,594 (1,471 + 2,123)	1,031 (1,031 + 0)	−71%
Edges touching a sourceless node, at load	35,593	25,010	−30%
(graph.json-only view of the two rows above)	1,471 stubs / 16,289 edges	1,031 stubs / 25,010 edges	see note
BalanceitemRepository exact-match tier	18 nodes, all sourceless, degree 1	1 sourced node, degree 176	Q4 unblocked
Inbound calls on ServiceCategory::parent()	1,698 (1,698 distinct fabricated sources)	2 (both genuine)	−99.9%
BalanceCustomerAccountService.handle() → ChargeCustomerService.handle() calls edge	absent	present	#38

Two notes on rows that are not naively apples-to-apples:

• 291 vs 302. This issue's body counted 142 interfaces / 30 traits / 119 enums = 291. A direct tree-sitter pass over the 6,062 PHP files in the pinned manifest counts 142 / 40 / 120 = 302, which is also exactly the size of graphify's own _php_non_class_types inventory in both graphs. Whichever count you take, PRE has a canonical node for none of them and POST has one for all of them; measured as "declarations with no (source_file, label) node": 302 → 0.
• Stub-absorbed edges appear to rise (16,289 → 25,010) — they did not. PRE's 19,303 imports edges had no node at all behind their target, so they were invisible to that count and serve materialized 2,123 attributeless degree-1 phantoms at load. Post-Stub-shadow fix 2/4: resolve imports edges from their own target_fqn metadata (RC2 of #46) #48 those edges resolve: 11,738 of them onto real in-corpus declarations, the rest onto FQN-labelled stubs that are proven external by their own use statement. The honest at-load comparison is the row above it: 3,594 → 1,031 sourceless nodes (−71%) and 35,593 → 25,010 incident edges (−30%).

Gate verdicts

Gate	Verdict	Evidence
Q4 — explain and affected agree; real fan-in reachable	PASS (flip)	Both now resolve to app_repositories_balanceitem_balanceitemrepository_balanceitemrepository (app/Repositories/Balanceitem/BalanceitemRepository.php:L22, degree 176). PRE: explain answered from the bare degree-1 stub, affected refused with "No unique node match". affected reaches 37 of 37 real production consumer files; the 38th grep hit (app/Enums/LineItemCategory.php:149) is a prose mention of DbBalanceitemRepository inside a docblock, not a code reference.
Q2 — resolves without a disambiguation retry	PASS (flip)	explain "ChargeCustomerCancellationFee" returns the real class directly, degree 15, all six ground-truth dependencies present (BaseAction, GetCancellationBlockReason, GetCancellationFeeReason, ChargeCustomerService, BalanceitemRepository, CancellationFeeRepository). 571 tok in one call vs PRE's ambiguity list + retry round-trip (94 + 532 = 627 tok).
Q1 — no regression	PASS	A: 128 → 132 nodes, 3/3 callers, same relaxed-context header. B byte-identical to A (cmp exit 0). C: 138 → 142 nodes, 3/3. Class-level affected: 3/3 (1,667 tok). Method-level affected --relation calls: 2/3 → 3/3 — BalanceCustomerAccountService.php:L37 now appears at its exact call site (#38).
Q3 — no regression	PASS	explain "CustomerWasCharged" diffs clean against the 0.9.37 output: same 13 connections, same listener RefreshCustomerPropertiesCanSelfReactivate (imports + .handle() references L27). The only deltas are a populated Community: Balance (this build clustered; the baseline did not) and two file labels gaining a path prefix to disambiguate colliding basenames. 417 → 431 tok.

Per-slice deferred criteria

• Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47 — 291 (302) missing declarations → 0. ✅
• Stub-shadow fix 2/4: resolve imports edges from their own target_fqn metadata (RC2 of #46) #48 — dangling imports 19,303 → 0; 11,738 edges recovered onto real declarations, slightly above the 11,456 with-Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47 upper bound because Stub-shadow fix 1/4: PHP interface/trait/enum declarations mint canonical nodes (RC1 of #46) #47's new nodes are themselves valid targets. ✅
• Stub-shadow fix 3/4: find_node_ambiguity must not collapse sourceless rivals into one group (RC3 of #46) #49 — the 18-node sourceless exact tier for BalanceitemRepository no longer exists at all (one sourced node), so the RC3 guard has nothing to suppress here; it remains the standing protection for the residual 1,031 stubs. ✅
• PHP: clearly-wrong calls edges in the repro neighborhood (.parent() --calls--> .setUp(); .handle() --calls--> test methods) — failure mode #3 evidence #39 — inbound calls on ServiceCategory::parent() 1,698 → 2. The 1,698 came from 1,698 distinct methods across the corpus that write parent::…; the 2 survivors are the only two real ->parent() call sites (tests/Integration/internal/app/ServiceCategoryTest.php:72,122). ✅
• PHP: docblock-typed property assigned in the constructor body binds no receiver type — missing calls edge (co-cause 2 of #37) #38 — the BalanceCustomerAccountService.handle() → ChargeCustomerService.handle() edge exists, and Q1's method-level surface goes 2/3 → 3/3. ✅

Residuals (documented, not chased)

• 1,031 sourceless stubs remain, 426 FQN-labelled and 605 bare. These are genuine out-of-corpus vendor types (Mockery, Carbon, Bus, Validator, …) that now have honest external nodes instead of dangling. The largest, mockery, carries 1,910 inbound calls — the corpus writes Mockery:: 3,347 times, and PRE those calls were silently dropped because no node existed to bind them to.
• Phrasing C's coder.md seed is still present (documented residual from query: relational verbs ("calls"/"callers"/"uses") hijack seed selection and bury the real identifier's callers (upstream Graphify-Labs#2507) #37's grading, unchanged by this work).
• explain prints 20 of 176 connections for the new BalanceitemRepository node — the fan-in is reachable (and affected renders 37/37), but the explain surface truncates. Not a PHP node identity: interfaces/traits/enums get no declaration node — sourceless stubs shadow the real name, absorb its edges, and break lookup (failure mode #3, PE-78803) #46 regression; the node had degree 1 before.

Raw outputs: /tmp/gfy-grade-out/ · throwaway corpus + graph preserved at /tmp/gfy-grade-api/ for audit.

[filipechagas]

All three root causes fixed, released as 0.9.38 on fix/stub-shadowing-46, and graded: the acceptance grading in the comment above shows all four gates PASS (Q4 and Q2 flipped as predicted — Q4 by #47's canonical nodes, Q2 by #48's target_fqn resolution — Q1/Q3 no-regression with a bonus 2/3→3/3 on method-level affected from #38). Baseline metrics from this issue's body: 291 (302 by direct count) missing declarations → 0, 2,123 dangling endpoints → 0, 19,303 dangling imports → 0, sourceless nodes at load 3,594 → 1,031 (all residuals genuine out-of-corpus vendor types). Sub-issues #47/#48/#49 and the release slice #50 are closed; the single PR into v8 follows.