Skip to content

Diagnostics fakes: v8 heap snapshot is an empty-but-valid graph; inspector/repl sessions look real but aren't #4916

Description

@proggeramlug

What lies

The diagnostics-tier modules return Node-shaped fakes — valid structure, fabricated content:

  • v8.getHeapSnapshot() / writeHeapSnapshot() — returns a minimal valid V8 heap-snapshot JSON document with an empty node graph (crates/perry-runtime/src/node_v8.rs:21, V8_HEAP_SNAPSHOT_JSON const at line ~83). Tools that load it (Chrome DevTools, heap-analysis libs) parse it fine and show… nothing. getHeapStatistics()/getHeapSpaceStatistics() return Node-shaped objects with Perry arena/RSS numbers — defensible, but undocumented as approximations.
  • inspector.Session.post() — unimplemented protocol methods throw Inspector error -32601: '<method>' wasn't found (crates/perry-runtime/src/node_inspector.rs:196). Loud-ish, but the session itself connects "successfully" first, so tooling gets a working-looking session that rejects every useful command.
  • repl.start() (programmatic) — needs verification: node_repl.rs builds the server object and listener/command storage, but there does not appear to be a real readline-driven evaluation loop behind programmatic repl.start(). Verify, then either implement or stub-flag.

Why it matters

Severity: SILENT-LIE for heap snapshots (empty-but-valid is the worst kind of fake), PARTIAL for inspector/repl. These are exactly the APIs people reach for when something is already going wrong — a lying diagnostic tool costs double.

Acceptance

  • Heap snapshot either (a) emits a real object graph from Perry's GC heap walk (it already has scanners for marking — the graph exists) in V8 snapshot format, or (b) throws ERR_PERRY_UNIMPLEMENTED with a pointer to PERRY_GC_DIAG=1, never an empty fake.
  • getHeapStatistics() docs state which fields are Perry-arena-sourced vs zero.
  • Inspector: document the supported protocol-method subset; inspector.url() returns undefined unless a real endpoint exists.
  • Verify programmatic repl.start(); implement an actual eval loop or flag stub: true.
  • All residual fakes flagged stub: true in the API manifest.

Metadata

Metadata

Assignees

No one assigned

    Labels

    stubsRegistered API that is a no-op / fake / silently wrong — stub-elimination epic

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions