feat(trace): :rf.trace/trigger-handler — error events carry triggering-handler source-coord (rf2-3nn8)

[mike-thompson-day8]

Summary

Extend re-frame2 error traces to carry the source-coord of the handler whose execution produced the error. Tools (10x, pair, IDE jump-to-source) consume the slot to render click-to-jump links straight from any :rf.error/* event to the offending handler's source. The registrar already stamps :ns / :file / :line / :column at registration time; this threads that data through to the emitted error event.

The four locks

Q	Lock
Q1 Naming	:rf.trace/trigger-handler (nested), :kind + :id alongside the coord. Flattening to :rf.handler/source-coord would conflate "what handler" with "where in source".
Q2 Coverage	Optional field. Present when a handler is in scope at emit time (event / sub / fx / cofx / view); absent for outermost-dispatch errors with no handler resolved.
Q3 Site	Registration-site coord. Call-site coord (the specific (inject-cofx :foo) line inside the handler body) is a separate follow-up.
Q4 Elision	Not separately elided. The trace surface as a whole remains dev-only via interop/debug-enabled?; when an error event is emitted, the field rides along.

Mechanism

Single trace/*current-trigger-handler* dynamic Var that each runtime boundary binds around the user code it runs. emit-error! reads the Var and hoists its value to the top-level :rf.trace/trigger-handler slot when bound. The trigger-handler-from-meta helper picks :ns / :file / :line / :column off the registrar slot's meta map and re-nests them under :source-coord; returns nil when no coord was stamped (programmatic registration) so the slot is omitted rather than populated with placeholder data.

Runtime boundaries that bind

• router.cljc — process-event* around the interceptor chain + post-chain phases (db commit, flows, fx walk).
• fx.cljc — handle-one-fx around the user-fx handler call.
• cofx.cljc — inject-cofx around the cofx fn body (both arities).
• subs.cljc — validate-and-trace around the sub body-fn invocation.
• views.cljs — reg-view*'s wrapper around the render-fn call.

Interceptor errors flow up to the router's :rf.error/handler-exception emit site, which fires inside the event-runtime binding — so the enclosing handler's coord is what surfaces (interceptors aren't reg-stamped, per the bead's locked design). The no-such-cofx / no-such-fx paths fire while the enclosing event-handler binding is still active, so they carry the event's coord.

Spec changes

• Spec-Schemas.md §:rf/error-event — optional :rf.trace/trigger-handler added to the canonical Malli shape with the :kind enum, :id keyword, and :source-coord sub-map.
• 009-Instrumentation.md §The error event shape — per-context coverage table (present vs absent), registration-site (not call-site) coord choice, "no-poison-data on programmatic registration" rule, production-elision wording.
• docs/guide/14-errors.md — user-facing error-event example updated with the new slot and tool-consumption note.

Files touched

Spec: spec/Spec-Schemas.md, spec/009-Instrumentation.md, docs/guide/14-errors.md

Runtime impl: implementation/core/src/re_frame/trace.cljc (new dynamic Var + helper + emit-error! hoist), router.cljc, fx.cljc, cofx.cljc, subs.cljc, views.cljs

Tests: implementation/core/test/re_frame/trigger_handler_coord_test.clj — 9 deftests / 46 assertions covering the four locks (top-level placement; per-kind coord propagation: event handler-exception, fx handler-exception, sub-exception, no-such-cofx, no-such-fx; negative no-such-handler case; programmatic-registration negative case; field-by-field parity with the registrar's source-coord).

Test plan

• clojure -M:test green across core (235 tests), schemas (49), machines (114), routing (21), flows (26), ssr (31), epoch (59), http (39)
• npm run test:cljs green (571 tests)
• npm run test:browser green (559 tests)
• npm run test:elision green — the trace surface still DCEs cleanly in :advanced + goog.DEBUG=false
• npm run test:examples green

Discipline

• JVM interop preserved — source-coord under JVM continues to use *file* / (meta &form) at the macro path; the per-boundary binding sits on top and works identically on JVM and CLJS.
• Single-import contract preserved — no new namespace required to read :rf.trace/trigger-handler off an error event; it's a plain map key.
• No new registries / dispatch types / effect substrates / component substrates. This bead enriches existing trace events; no new primitive.
• Additive change to the schema — existing error-event consumers that don't read the field are unaffected.