feat(truapi-server): host-side wire debug tap and debugger

[decrypto21]

What

Implements the wire observability layer for TrUAPI: a payload-blind debug tap in the Rust host
(truapi-server), correlated by the wire requestId. The host streams every product↔host frame to
a debugger app it dials out to. The tap carries the frame bytes opaquely — the core never decodes
them — so it leaks no application content or key material, and @parity/truapi (the product package)
is untouched. Dev-only: the tap is inert unless a host installs a sink. Design doc:
docs/design/wire-observability-debug-host.md (#315).

What's in it

• DebugSink trait + DebugEvent in truapi-server — the tap at the two frame choke points
  (ProductRuntime::receive_frame inbound, FrameSink::emit_frame / SinkTransport::send outbound).
  Outbound forwards to the product before it emits; inbound emits before dispatch so a corrupt frame
  is still observed; emit is fire-and-forget and inert when no sink is installed (a lock-free
  has_debug fast path). Direction on the wire is product-vantage (out = left the product), pinned
  by a guard test; DebugEvent is #[non_exhaustive] (room for non-frame events like SSO).
• @parity/truapi-debugger (private, in-repo) — the debugger. createWireDebugger groups frames into
  per-requestId WireTraces (LRU-capped); createMethodNameMap resolves frameId → "account.getAccount" from the generated wire-table; a Bun WS server the host dials into serves a
  payload-blind trace view. Envelope: { channelId, dir, frame }.
• @parity/truapi-host worker dial — a dev-gated outward WebSocket to the debugger, configured from a
  localStorage debugger URL the host reads. When set it installs the Rust DebugSink; absent ⇒ no
  sink and the tap stays inert. The product is cross-origin and can't turn it on.

Verification

cargo test -p truapi-server green — the tap is covered in both directions with the product-vantage
direction convention pinned (debug_sink_taps_frames_in_both_directions,
frame_direction_wire_str_is_product_vantage). @parity/truapi-debugger has a live-server bun test
(a host dials in, streams a frame, the server decodes + groups it on /traces), and a new
ts-debugger CI job builds + tests it. @parity/truapi and @parity/truapi-host are green
(tsc + bun test); the TrUAPI playground builds.

Notes

Design decisions live in the design doc (#315).
Corrupt inbound frames are surfaced as a malformed frame rather than the transport silently closing.
Not in this PR (phase 2): the native outward-dial sinks (ws_bridge), wss + cert-trust, and a mock
host + browser harness.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​parity/​truapi-debugger@​0.0.0	N/A	N/A	N/A	N/A	N/A

View full report