[mache-b094fa] feat(graph): public ref resolution — RefRange and a classified RefTarget

[jamestexas]

Downstream consumers (modmap — a monorepo blast-radius tool) hand-write a node_refs/_ast join for every reference range, and match call tokens against node_refs.token, which cannot tell a local Join from filepath.Join. Both are now first-class behind graph.RefResolver.

Resolution is four-valued, and the data demanded it

Bucketing all 123,117 refs in this repo's own projection:

resolution	refs		meaning
resolved	13,353	10.8%	exactly one local definition — follow it
external	16,285	13.2%	qualified by an import leaving the projection; zero local blast radius
ambiguous	21,920	17.8%	several defs, candidates returned
no-target	71,559	58.1%	no local definition at all

A boolean resolved? puts 89% into one undifferentiated bucket. For a blast-radius tool, "leaves the module" and "genuinely uncertain" are opposite answers — one has no radius, the other needs a human.

NodeID is populated only for resolved, so a caller cannot consume a guess by accident. Package narrowing is a filter, never a tiebreak: if it doesn't reduce to exactly one, the result stays ambiguous.

Deliberately absent: any heuristic deciding whether an import path "looks external" from its shape. Whether example.com/you is inside your module is something the caller knows and mache does not.

The bug only real data found

A node_id is not a unique key into node_refs. A qualified call dual-emits two rows at the same node — require.NoError and NoError — and 37,236 node_ids here carry more than one. node_defs is keyed on the bare token, so an arbitrary LIMIT 1 lands on the qualified row about half the time and reports a false no-target for a reference that resolves fine.

LLO's table contract makes the pick deterministic: qualifier is set on the bare-token row, NULL on the qualified one.

Worth knowing for anything else keying on node_id — including modmap's internal/assemble id-prefixing.

Verified against a real projection, not only fixtures

leyline.CanonicalSourceRoot -> resolved  via the internal import
fmt.Errorf                  -> external  via "fmt"
t.Errorf                    -> no-target (a receiver variable is not an import)

Two things the smell ratchet caught

lastSlash was a hand-rolled strings.LastIndexByte — and a byte-identical copy already existed in internal/ingest/inner_scope_test.go:76. Two independent reimplementations of one stdlib call. Now stdlib; hasPathSegment likewise collapsed to slices.Contains.

type Resolution collided with schema.Resolution (unrelated struct). Renamed RefResolution.

Neither was caught by go vet, golangci-lint, or tests.

Test note

The dual-emit regression was initially vacuous: its fixture used Helper/helper.Helper, where uppercase sorts first so the bare token won by accident — it passed with the fix reverted. Renamed to run/a.run so alphabetical order picks wrong, then re-falsified.

Still open in mache-b094fa

• the Open-stays-lazy test (the ~100GB constraint — currently unlocked by any test)
• the LookupDef returns []string / GetCallers returns []*Node asymmetry driving modmap's callerResolver

Verification

task ci passed via the pre-push gate; task smells returns 0; go test ./graph/ green.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TtGhz7QzUHZi52a3FeNtEs