feat(truapi-debugger): wire trace engine, standalone inspector, and in-app panel

[decrypto21]

Adds the TrUAPI wire debugger: the trace engine, a standalone loopback inspector, an in-app panel a host can mount, the dev-gated worker dial that feeds them, and the release plumbing for @parity/truapi-debugger. Stacked on #295, which emits the opaque frames this correlates and decodes.

Why: the tap in #295 has no consumer. This is the consumer, and the first thing in the stack that turns frames into something readable.

How: js/packages/truapi-debugger holds the engine and both surfaces; the dial is in create-worker-host-runtime.ts.

Engine:

• Correlates frames into per-operation traces keyed on (channelId, requestId), resolving each frame's lifecycle role at ingest from the generated wire table.
• Locates the opener by role rather than by position. frames[0] is the opener only if the opener was the first frame observed, and a tap attaching mid-session usually sees a closer first, so retention spares the opener by role. Keying on index 0 evicts the frame that pairing and storm detection depend on.
• Keeps the two pairing verdicts distinct. An opener with no close is a claim about the host; a close with no opener is usually a claim about the debugger, because the operation predates the tap or retention dropped the opener. One shared badge made the tool report its own retention as a protocol defect.
• Rotates generations when a product recycles a request id.
• Surfaces undecodable frames as a malformed sentinel rather than dropping them.
• Bounds retention on traces, frames per trace, and bytes per trace, counting evictions and marking truncation.

Surfaces:

• The standalone inspector is a loopback WS + HTTP server the host dials. Every HTTP route is fed by the same view model the page renders, so curl and the UI cannot disagree about operations, badges, or payloads.
• The in-app panel mounts the same engine and renderers inside a host: no server, no dial-out, frames never leave the app.
• Both strips render from one shared aggregate. A second bespoke roll-up is how the two once disagreed, the standalone reporting malformed 1 / truncated 1 on a stream the panel showed as clean.

Confinement and decode:

• The debugger is the server; the host always dials outward. The URL must be ws:// on a loopback host, with origin, target, and bind checked as three distinct loopback classifications.
• Host must match a loopback name exactly rather than by substring, and inbound payload size is capped.
• No denylist and no reveal toggle: the decoder is absent from a production bundle, behind a build-time flag.
• Decode is gated on an affirmative schema-hash match per channel and per frame. A host running a stale WASM bundle declares a stale hash, and the debugger refuses payloads and flags its method names as unreliable rather than rendering nonsense.
• sync-release-versions gains the debugger's @parity/truapi range, so a protocol release that leaves the debugger pinned to an older version fails at release time rather than at decode time.

Driven end to end against dot.li on paseo-next-v2 with the playground as the product: 172 operations, 351 frames, decoded payloads, and codecOk/schemaOk true on the channel.

• Design doc: docs(design): wire observability and debug host #315
• Stacked on: feat(truapi-server): payload-blind wire-debug tap, sinks, and the codegen decode surface #295

[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/​happy-dom@​20.11.2

View full report