ReviewOS

zig-utils/zig-js

Inspector: implement debugger and inspector protocol support

#139
Closed chris opened this 9 days ago ·
9 days ago

Parent: #134

Implement a usable inspector/debugger rather than shell-only stubs.

Acceptance:

  • Define and version the supported inspector protocol domains.
  • Implement session attach/detach, pause/resume, breakpoints, stepping, evaluation, exception pause, scripts, stack frames, and scopes.
  • Keep every implemented execution tier (interpreter and baseline JIT), workers, and GC stack/root state coherent while paused; optimizing-tier coherence is gated with the tier itself in #146.
  • Support concurrent sessions and deterministic teardown.
  • Add protocol transcripts and end-to-end debugger tests with no hidden skipped commands for every currently exposed 0.1 command/event.
  • Document transport, authentication boundary, supported domains, and current limitations.

Child issue map:

  • #152 — versioned sessions, transport, public inspectability, and Runtime domain (71bc743)
  • #153 — scripts, pause/resume, breakpoints, stepping, and exception control (through 835831d)
  • #154 — call frames, scopes, remote objects, GC roots, isolated-worker boundary, and completion evidence (bddbda8)
  • #155 — historical, dynamic eval, modules, and generated-function script registration (8ee36dc)
  • #156 — worker target discovery and cross-thread inspector transport (1060784)

Current implementation:

  • 71bc743 provides zig-js-inspector/0.1, embedder-owned synchronous JSON transport, opt-in inspectability, concurrent context-retaining sessions, deterministic detach, Schema and Runtime domains, live evaluation, structured errors, and real C transcript coverage.
  • 98c9dbb through 835831d add stable registered scripts and source retrieval, exact statement locations, debugger-statement and explicit pause/resume, resolved URL/script breakpoints, logical-depth stepping, none/all/uncaught exception policy, suspendable generator/async VM checkpoints, VM-throw notification, and quick-path deoptimization.
  • cfb9d6f through af694b5 add live tree/VM call frames, lexical/global scopes, frame evaluation, session-owned remote objects/properties/groups, precise-GC protection, and automatic pause-handle release.
  • a8acfaf defines deterministic single-session continuation ownership with observer-first pause delivery; 80a071a makes callback-driven release/detach safe; 54c00c7 tests the honest isolation boundary for independently-created workers.
  • bddbda8 completes #154 with direct baseline/native deoptimization assertions, live frame evaluation in the real C host, 6/6 debugger tests, 5/5 inspector tests, and the 117/117 C API host gate.\n- The checked-in zero-hidden inventory currently covers all 20 exposed commands and 8 events.

#154 and #155 complete main-context paused state and every supported historical/dynamic/module-generated script origin. #156 completes real worker targets, owner-pumped cross-thread transport, protocol parity, independent pauses, precise-GC roots, and deterministic teardown. The optimizing tier itself remains #146 rather than being represented as an inspector stub.

  • 4f3d8f4 through 8ee36dc complete #155: context-owned history, warmed bytecode/native deoptimization, live ordinary-VM scopes, direct/indirect eval, all generated-function constructors, JSObjectMakeFunction URL/offsets, module graphs, multi-session delivery, and detach/reattach. The final inventory remains 20 commands / 8 events with zero hidden acceptance.
9 days ago

#156 now has stable worker targets plus explicit cross-thread attach/dispatch/pump/release on main (e14cf92, 563ffe7). Commands execute only on the worker runtime thread, events/callbacks return only through the worker-owner pump, and a paused message handler accepts its continuation through that queue. Remaining #156 work is the full parity, multi-session, module/termination/GC/concurrency teardown evidence matrix.

9 days ago

Completed. Child #156 is closed through 1060784, finishing worker discovery, owner-pumped transport, full 0.1 protocol parity, independent target pauses, precise-GC remote roots, and deterministic teardown.

The implemented inspector remains exactly inventoried at 20 commands and 8 events with no hidden stubs. Optimizing-tier integration stays correctly gated with the not-yet-implemented optimizing tier in #146 rather than blocking or overstating the completed inspector.

Sign in to comment on this issue.