Repository navigation
node:v8: snapshot and profiler output parity cut #3296
Description
Summary
Create the medium PR boundary for package-visible V8 diagnostic output surfaces that can return Perry-shaped data while preserving Node's observable stream/file/report contracts.
Child Issues
- node:v8: implement heap snapshot output #3140 - implement heap snapshot output
- node:v8: implement GCProfiler report shape #3142 - implement GCProfiler report shape
Intended PR Boundary
Implement the diagnostic-output layer after the basic node:v8 namespace exists:
v8.getHeapSnapshot([options])returns a readable stream that emits heap-snapshot-shaped JSON.v8.writeHeapSnapshot([filename[, options]])writes a non-empty heap snapshot file and returns the written path.new v8.GCProfiler()exposesstart,stop, and disposal behavior with a Node-shaped report object.- Add or extend a V8 parity fixture to cover stream/file/report shapes without requiring exact V8 heap internals.
This cut is coherent because all children are diagnostic outputs where Perry-specific internal data is acceptable if the Node-observable shape, stream/file lifecycle, and error behavior match.
Node Behavior
Node v25.9.0 returns a readable HeapSnapshotStream from getHeapSnapshot(), writes .heapsnapshot files through writeHeapSnapshot(), and exposes GCProfiler instances whose start() returns undefined and stop() returns a report with keys such as version, startTime, statistics, and endTime.
Perry Behavior
docs/runtime-parity.md and docs/runtime-parity-gaps.md list the V8 snapshot/profiler APIs. Source search found no public node:v8 heap snapshot or GCProfiler implementation, and this checkout has no dedicated V8 parity fixture.
Duplicate searches run before filing:
node:v8 heap snapshot GCProfiler profiler output diagnostics parity cutnode:v8 diagnostics serialization heap statistics snapshot promiseHooks startupSnapshot GCProfiler parity cut
Non-goals
- Top-level
v8.serialize/deserializeor Serializer/Deserializer classes. - Heap-stat object helpers already covered by node:v8: diagnostics and serialization parity cut #2492 / node:v8: expose heap statistics shape #3138.
- Promise hook callbacks or startup snapshot helper state.
- Exact V8 heap/profiler internals beyond package-visible output shape.
- CPU profile and heap profile handle APIs unless they are filed as separate focused leaves.
Acceptance
- Focused parity/regression coverage proves child issues node:v8: implement heap snapshot output #3140 and node:v8: implement GCProfiler report shape #3142.
- Heap snapshot stream/file output is readable/non-empty and heap-snapshot-shaped for covered cases.
GCProfilerconstructor/method/report shape matches Node for covered cases.- Related docs/gap metadata are updated for APIs covered by this cut.
Activity
proggeramlug commentedon May 30, 2026
Closing this "parity cut" umbrella tracker as superseded by its granular child issues.
Perry tracks Node/TypeScript parity gaps as granular, per-gap issues (the ones listed under Child Issues above) — that is the workable backlog the maintainer prefers, rather than umbrella roll-ups. Each child issue carries its own Node-vs-Perry evidence, source pointers, and test surface, and remains open and independently tracked; closing this umbrella loses no work, only the duplicate roll-up framing.
The child issues continue to be addressed by focused PRs (each PR auto-closes the specific leaf issues it fixes). If a consolidated tracker is still wanted for this module, feel free to reopen.