fix(context): call paths label synthesized hops like explore, not as events

[colbymchenry]

Summary

Two surfaces label a synthesized (dynamic-dispatch) calls hop, and they disagreed:

• ToolHandler.synthEdgeNote (codegraph_explore's Flow and dynamic-dispatch links, the codegraph_node trail) tags it, e.g. dynamic: interface → impl @file:line.
• ContextBuilder's "## Call paths" (what buildContext and codegraph context print) kept its own ternary chain. That chain covered callback, react-render, jsx-render, vue-handler, http-client, queue-job and socket messages. Everything else fell through to event ${m.event ?? ''}.

So on main an interface hop in the call paths reads:

- runExport → exportReport →[event  @src/pdf-exporter.ts:5] exportReport → renderPdf

A C++ override, a redux thunk, a gin middleware chain, a closure collection, a fn-pointer dispatch and a GoFrame route read the same way. With this PR:

- runExport → exportReport →[interface → impl @src/pdf-exporter.ts:5] exportReport → renderPdf

What changed

• New src/graph/synthesized-hop.ts. describeSynthesizedHop(edge) returns { summary, detail, registeredAt }, or null for a static edge. It is the one per-synthesizer derivation, as AGENTS.md asks of a derivation two surfaces render.
  • summary is explore's wording: callback via \subscribe`, interface → impl, redux thunk`. A synthesizer it doesn't list reads by its own name, as explore's fallback already did.
  • detail is what only the call paths print: the queue name, a socket's direction, the HTTP clause.
• Both surfaces render from it. synthEdgeNote renders dynamic: <summary> @<site>. ContextBuilder renders <summary><detail> @<site>.
• fix(go): a call through an interface reaches a method the struct gets by embedding #2414's arm moves into the helper. fix(go): a call through an interface reaches a method the struct gets by embedding #2414 added a promotedInto arm to synthEdgeNote and landed on main while this was open. The helper carries it with the same wording, so the merge took this side of that conflict. go-promoted-dispatch.test.ts passes unchanged.
• Removed dead code. synthEdgeNote's long label form goes: none of its three callers read it, and its last reader was the removed codegraph_trace. So does its doc comment, which had drifted above whenLabel.
• Footnote. The call paths footnote said hops are marked [callback/event …]; it now says […].
• Docs. AGENTS.md lists the module among src/graph/'s shared derivations. CHANGELOG has a bullet under [Unreleased] → Fixes, because codegraph context output changes.

Wording parity

I compared both new surfaces with main's code, copied verbatim, over 36 edge shapes. They cover every kind either surface had its own wording for, with and without each optional field, plus several kinds only explore's fallback named. The comparison called the real ToolHandler and ContextBuilder.

explore and the node trail print the same thing for every edge a synthesizer emits today. Two shapes differ:

• the promotedInto arm, which matches fix(go): a call through an interface reaches a method the struct gets by embedding #2414 now that it is on main;
• a JSX or Vue hop carrying a registeredAt would now show it. No synthesizer sets one.

The call paths keep their wording for every kind they already labelled: callback, React re-render, JSX child, Vue handler, HTTP, queue job and socket message, plus event-emitter, which the fallback happened to get right. What changes:

• interface-impl, closure-collection, fn-pointer-dispatch and goframe-route now read as explore names them, instead of event @…. So does every synthesizer only explore's fallback knew: cpp-override, redux-thunk, gin-middleware-chain, flutter-build, test-request and the rest.
• A non-socket event-bus hop reads bus event `x` (was event `x` ).
• When a field is missing, the label now uses explore's words: a registrar, a job, an event, a child component, a template event. Before, it showed registrar, an empty string with a double space, <child> or @event. The synthesizers always set these fields, so this can't happen today.

Tests

New __tests__/synthesized-hop.test.ts:

• End to end, on a 4-file TypeScript fixture: an interface, a class that implements it, a caller and a helper.
  • buildContext's call paths label the real interface-impl edge interface → impl @src/pdf-exporter.ts:5 and contain no →[event.
  • codegraph_explore tags the same hop dynamic: interface → impl @src/pdf-exporter.ts:5.
  • The fixture puts each symbol in its own file. ContextBuilder keeps at most 5 nodes per file, and in one file the interface method is the one it drops.
• Red phase: against main's ContextBuilder, the first test fails with →[event @src/pdf-exporter.ts:5].
• A table over describeSynthesizedHop: the kinds the call paths mislabelled, plus the detail only the call paths print.

Validation

All of this ran on Windows. The box sat at 100% CPU from other sessions throughout.

Type check. tsc --noEmit is clean. __tests__ isn't in the project tsconfig, so I type-checked the new test file separately under the same strict settings. It is clean too.

Focused suites. All pass on the branch merged with main 61f8b09:

• the new tests;
• go-promoted-dispatch — its explore assertion, dynamic: interface → method promoted into blockSeriesSet @…, now comes from the helper;
• field-channel-scope and explore-synth-constant-endpoints — explore's callback and redux thunk tags;
• context, cli-context-command and cpp-library-type-receiver.

Sweep. Every test file that drives ToolHandler or ContextBuilder (79 files, 2038 tests), run on the merge with 2f2afea: 2012 passed and 9 timed out.

• Rerun with --testTimeout=120000 --hookTimeout=120000, 8 of the 9 passed.
• The ninth is function-ref's "Caller/impact graph misses methods passed as first-class references (callbacks), e.g. executor.submit(obj.method, …) #1820: a module global never binds through a shadow…". It indexes 68 small projects in turn under its own 60 s cap, which overrides the flag, and it timed out when run alone too. A temporary copy with a 600 s cap passed in 164 s. It runs none of the code this PR changes.
• A first pass before merging main had 27 failures. The part of its log I kept showed Windows EBUSY errors deleting a temp codegraph.db. After the merge, a second pass over the same files had only the 9 timeouts above.

CLI. codegraph context runExport exportReport renderPdf on the 4-file fixture, from the CLI built from this change, prints - runExport → exportReport →[interface → impl @src/pdf-exporter.ts:5] exportReport → renderPdf.

🤖 Generated with Claude Code