feat(symbolizer): expose address-level symbol resolution as a public API

[jake-kramer]

Part of a series: symbol-aware tree references (1 of 8)

The full picture. Native and eBPF profiles are ingested with raw memory addresses; function
names are resolved at query time from debug info. Today that resolution only triggers when the
query-frontend sees an __unsymbolized__ dataset label — which queryless queries ({}) never
surface, so their results silently lose symbolization — and it works by rewriting the whole TREE
query into PPROF and back, which makes every dataset in the query pay the pprof cost and silently
drops any query selector that isn't hand-mirrored between the two query types. This series changes
the tree representation instead: tree nodes can reference unresolved {buildID, address} locations
directly, partial trees carry those references through every merge (with truncation deferred), and
the frontend resolves them once after the final merge, then rewrites and truncates the tree.
Correct for every query shape, no pprof detour, and the wire format stays a tree. Tracking issue:
grafana/pyroscope-squad#487.

The series, in order (each PR stands alone for review; no new behavior activates until 6):

1. symbolizer: expose address-level Resolve API ← this PR.
   Extracts per-address symbol lookup from behind SymbolizePprof into a public Resolver
   interface that later PRs consume directly. Pure refactor: no caller change, no new behavior.
2. proto: SymbolRefTable + tree query/report fields.
   The wire schema for trees that carry unresolved references — a compact side table of resolved
   names, interned build IDs, and addresses. Schema + generated code only; no consumers yet.
3. model/symbolref: intern table + merge rebasing.
   New package implementing the reference table and deterministic reference rebasing when partial
   trees from different backends merge.
4. model/symbolref: job grouping + rebuild.
   Groups unresolved references into per-build-ID resolution jobs, and rebuilds the final resolved
   tree — expanding inline-frame chains, merging newly-identical nodes, truncating exactly once.
5. symdb + querybackend: produce and aggregate symbol-ref trees.
   Backends emit trees with unresolved references for unsymbolized datasets (deferring truncation)
   and merge partials of both shapes; fully-symbolized datasets keep today's exact path.
6. frontend: orchestration behind a default-off per-tenant flag.
   The frontend requests symbol-ref trees, resolves post-merge via this PR's API, and rewrites the
   result. The first PR where any new behavior can be switched on.
7. integration tests + docs. (test(symbolizer): add symbol-ref tree integration tests and docs #5335)
   End-to-end coverage — including the queryless-query case that motivated the issue — plus an
   equivalence test pinning the new path's output against the legacy one.
8. symdb: compaction preserves line-less locations (fix(symdb): preserve line-less locations when rewriting partitions without functions #5337) — merges first.
   Fixes a pre-existing bug (fix: drop malformed locations #4051) in the shared compaction symbols rewriter that replaced every
   location of a partition without functions — exactly the fully-unsymbolized native datasets this
   series serves — with a zero value, permanently destroying the addresses symbolization needs.
   Found during end-to-end validation of this series; stacked at the bottom so it lands before the
   feature can be enabled anywhere.

---

What / Why

pkg/symbolizer could previously only be driven through SymbolizePprof, which takes a whole
pprof profile. Anything that wants symbols for a set of {buildID, address} pairs — for example,
resolving symbols for a tree-shaped query result — had no way to ask for that directly; it would
have had to synthesize a throwaway pprof profile just to reuse the lookup path.

This PR extracts that lookup into a narrow, exported interface:

type Resolver interface {
    Resolve(ctx context.Context, buildID, binaryName string, addrs []uint64) ([][]lidia.SourceInfoFrame, error)
}

SymbolizePprof is refactored to call Resolve internally instead of duplicating the lookup
logic. Resolve is defined on *Symbolizer in the producer package (pkg/symbolizer), the same
pattern pkg/objstore.Bucket already uses, so a later out-of-process implementation can satisfy
Resolver without importing this package.

What moved: fallback-symbol synthesis (the binary!0xaddr placeholder text). Resolve itself
never produces it — a nil/empty slot in its result means "could not resolve this address," full
stop. Rendering the placeholder is now the caller's job: SymbolizePprof's per-mapping goroutine
calls the existing createFallbackSymbol helper immediately after Resolve returns, for every nil
slot. This is a mechanical relocation of an existing call, not a change to what it computes.

What stayed byte-identical:

• SymbolizePprof's emitted profile, on every existing fixture — same metric names/label values,
  same log message text, same check order as the code this replaces.
• The pre-existing, deliberately-unreused lookup buffer in the per-address loop
  (var framesBuf []lidia.SourceInfoFrame is never reassigned, so each table.Lookup call gets
  nil) — preserved exactly as-is; not something this PR changes or "fixes."

---

Behavior changes

There is exactly one externally-visible behavior change:

Context cancellation or a deadline firing while Resolve is resolving symbols now surfaces as a
real error, and that error now propagates out of SymbolizePprof instead of being silently
swallowed into a fallback-filled profile with a nil error.

Concretely: Resolve returns a non-nil error only when ctx.Err() != nil (checked at entry
and again around the debug-info fetch, via errors.Is against context.Canceled /
context.DeadlineExceeded); every other failure mode (empty/invalid buildID, fetch failure,
malformed debug info, a specific address not resolving) keeps degrading to a nil/empty result slot
with a nil error, exactly like the code it replaces.

This matters today at the three real call sites that invoke SymbolizePprof, all of which already
treat any error it returns as fatal to the request:

• pkg/frontend/readpath/queryfrontend/symbolizer.go:82
• pkg/frontend/readpath/queryfrontend/query_select_merge_profile.go:112
• pkg/frontend/readpath/queryfrontend/query_select_merge_profile.go:237

Before this PR, a query whose context was canceled or timed out mid-symbolization would silently
get back a profile full of binary!0xaddr placeholders and no error. After this PR, that same
request now fails with a wrapped context.Canceled/context.DeadlineExceeded error, matching how
these call sites already handle every other symbolization failure.

Internal contract note (not observable from outside pkg/symbolizer, since SymbolizePprof's
output is unaffected): whenever Resolve returns a nil error, the returned outer slice always has
len(result) == len(addrs), and result[i] == nil means address i didn't resolve, for any reason
short of context cancellation.

---

Security hardening

Resolve is a new public entry point into a buildID-driven object-store path
(getLidiaBytes → fetchLidiaFromObjectStore → path.Join(bucketPrefix, tenantID, buildID)).
Previously, this path was only reachable through SymbolizePprof, whose one caller always
sanitized buildID first — so encapsulation, not validation, was what kept it safe. Now that
Resolve is exported, Resolve validates buildID itself (same sanitizer extractBuildID already
applies) before doing any object-store or debuginfod I/O, and degrades to a nil-per-miss result
instead of trusting the caller. A test asserts zero mock calls on the storage/debuginfod clients
when buildID fails validation, proving the rejection happens before any I/O — the property that
actually matters for a future caller that might source buildID from less-trusted input.

---

Testing

• Full pkg/symbolizer suite passes under -race, including the pre-existing golden-baseline
  tests (TestSymbolizePprof, TestSymbolizationKeepsSequentialFunctionIDs) with zero edits to
  any existing assertion.
• New tests added for gaps the old private lookup path had no way to exercise directly:
  • size-limit-exceeded degrades to a nil result with no error (does not take the cancellation-error
    path).
  • context cancellation, in two forms: already-canceled at entry, and canceled mid-fetch
    (deterministic, channel-coordinated, no sleeps) — plus a third subtest for
    context.DeadlineExceeded via a real timeout.
  • cancellation propagating through SymbolizePprof end-to-end.
  • concurrent fan-out: three mappings with distinct build IDs resolved concurrently
    (MaxDebuginfodConcurrency = 4), with a blocking-mock/channel handshake that forces genuine
    3-way overlap (a regression to serialized execution hangs the test rather than passing).
  • an invalid/malformed buildID degrades to a nil-per-miss result with zero calls to the
    debuginfod client or bucket, plus the new invalid_build_id metric label incrementing exactly
    once.
• Coverage: 84.7% of statements in pkg/symbolizer.
• go build ./... and make lint (golangci-lint run ./...) are both clean across the whole repo,
  not just this package.

---

Follow-ups

None deferred from review. Resolve's two adjacent string parameters (buildID, binaryName)
were flagged as a general API-ergonomics observation during review and deliberately left as-is —
the signature is pinned across the rest of this series and the one call site already threads both
arguments correctly.

[jake-kramer]

This change is part of the following stack:

• fix(symdb): preserve line-less locations when rewriting partitions without functions #5337
  • feat(symbolizer): expose address-level symbol resolution as a public API #5317 ◀
    • feat(query): add SymbolRefTable and symbol_refs tree fields to the query API #5318
      • feat(model): add symbolref package for symbol-aware tree references #5321
        • feat(model): add unresolved-binary grouping and tree rebuild to symbolref #5322
          • feat(symdb): add symbol-ref tree resolver output #5332
            • feat(querybackend): produce and aggregate symbol-ref tree reports #5333
              • feat(frontend): resolve symbol-ref trees after the final merge #5334
                • test(symbolizer): add symbol-ref tree integration tests and docs #5335
                  • test(symbolizer): comparative benchmark, symbol-ref vs pprof-detour #5336

_{Change managed by git-spice.}

[simonswine]

While I think the error propagation is great, I am not too sure that is better to fail the whole flamegraph query, when a single symbolisation fails.

I think we should retain the user observable behaviour of using fallback symbols if we couldn't resolve some of the symbols.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit e054fad. Configure here.}

[simonswine]

Thanks for fixing the context cancellation and looking into the fallback behaviour