Observability: publish generated-code symbols and exact native stacks

[chrisbbreuer]

Parent: #459
Depends on: #461, #483
Related: #466, #467, #487, #495

Goal

Make generated JavaScript and WebAssembly code fully visible to host profilers, crash reporters, debuggers, and the zig-js inspector with exact native↔source↔bytecode attribution.

Current boundary

The saved macOS baseline profile sees hot anonymous MAP_JIT addresses as <unknown binary> because generated mappings have no native symbol table. #461 requires symbolized attribution and #483 includes debug/unwind metadata, but neither owns end-to-end profiler registration, native stack reconstruction, or lifecycle validation.

Scope

• Define artifact-owned symbols for functions, tiers, OSR regions, runtime stubs, Wasm functions, side exits, and retired generations.
• Publish native PC ranges to macOS sampling/crash tooling and Linux perf/jitdump/perf-map interfaces through owned writers and explicit platform APIs.
• Emit/register exact unwind metadata for every native frame, call stub, deopt/side exit, trap, and host transition on each ABI.
• Map native PC → artifact generation → optimizer/baseline/Wasm origin → bytecode/Wasm offset → source URL/line/column, including inlined frames.
• Reconstruct logical stacks across JS↔host↔Wasm, async continuations, generators, exceptions, proper-tail calls, deopt, and optimized-away frames where required.
• Deregister/retire symbols and unwind records only after the final executing reader leaves the artifact epoch.
• Measure registration, sampling, symbolization, memory, and disabled-path overhead.

No-workaround rules

• No permanent executable mapping retention for symbolization, stale/reused PC attribution, guessed stack scanning, profiler-only different codegen, unsafe unwind through Zig frames, or dependency on a third-party profiler library.

Acceptance

• Owned fixtures validate PC ranges, names, source offsets, inline/deopt frames, unwind, crash traces, and async/host/Wasm boundaries on each backend.
• System profiler samples attribute generated leaves to stable symbols instead of anonymous mappings.
• Inspector CPU profiles and host-native samples agree on artifact/source identity for the same execution.
• Invalidation/retirement/teardown races never expose stale metadata and pass TSan/artifact lifetime tests.
• Disabled observability has measured zero or bounded negligible overhead; enabled overhead and memory are published.

Foundation

Baseline dispatch profile; inspector/CPU-profile foundations under #139/#404.

[chrisbbreuer]

Landed the native-PC ownership foundation in 1b14ab9 (feat(observability): own native PC metadata).

This adds opt-in, context-owned baseline/optimizer PC ranges, stable symbol/function/source identity, exact hoisted-function definition coordinates, owned lookup snapshots, and execution-epoch-aware retirement. The row is removed before executable unmapping; focused TSan covers lookup racing reclamation, and disabled contexts allocate/retain no native metadata.

Validation: 1,511 unit tests passed with 0 skipped / 0 failed / 0 leaked across 10 shards; focused native-PC TSan passed; docs link check covered 100 files; the 49-page docs manifest/build passed.

This does not claim external profiler visibility yet. Next is the Darwin system-profiler publication/unwind layer, followed by native-PC↔bytecode/inline/deopt maps and inspector/host-stack agreement.

[chrisbbreuer]

Pushed 93cd3ade (feat(observability): publish native symbols to LLDB).

This lands the debugger-symbol publication slice on top of the owned native-PC registry:

• adds an embedder-owned publication interface; supplying it implies native observability and propagates through shared realms;
• adds an opt-in standard GDB JIT protocol adapter for macOS LLDB;
• emits an in-memory Mach-O object whose one __text section names the exact existing executable PC range—no copied, linked, or remapped executable image;
• owns registration with the artifact and unregisters before metadata destruction and executable unmapping;
• keeps __jit_debug_descriptor and __jit_debug_register_code out of the default static archive unless the embedder explicitly selects this process-global adapter;
• serializes concurrent register/unregister list mutation.

Owned evidence:

• zig build native-observability-lldb-test: real LLDB resolves a pending zig_js_baseline_1_observedNative breakpoint at __text + 0, then reports zero matching functions after Owner teardown;
• focused publication lifecycle under TSan: 3 passed, 0 failed/leaked;
• full zig build test-parallel: 1,515 passed, 0 skipped/failed/leaked across 10 shards;
• docs build/manifest/link gates pass;
• C API audit 117/117 and Home public ABI audit 50/50 pass;
• the rebuilt default libzig-js.a contains no __jit_debug globals.

The issue remains open. This does not yet claim Instruments/sample symbol visibility, unwind publication, external source/inline maps, deopt/crash/async/host/Wasm coverage, inspector agreement, or measured disabled/enabled overhead. Those remain the next acceptance slices; the next investigation stays on public Darwin system-profiler and unwind mechanisms rather than treating LLDB registration as profiler evidence.