ReviewOS

zig-utils/zig-js

ABI: implement heap snapshots and profile serialization

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

Parents: #140, #143, #246 Roadmap: #134

Implement the three remaining pinned heap-profiler boundaries as real graph snapshots, including both Bun string formats and the JSC object-returning API. This is also the heap-snapshot prerequisite for promoting the remaining PR-249 collection tests.

Scope

  • Pin Bun 4982b91e and WebKit cd821fec snapshot schemas, source identities, and Home signature divergence.
  • Snapshot all strong roots across sibling realms at a quiescent VM boundary without changing user-visible state.
  • Preserve stable node IDs, cell kinds/class names, shallow sizes, named/indexed edges, roots, and weak-edge semantics.
  • Implement JSC__JSGlobalObject__generateHeapSnapshot as parsed GCDebugging snapshot data.
  • Implement Bun__generateHeapSnapshotV8 with valid V8 nodes/edges/string tables.
  • Implement Bun__generateHeapProfile from the same graph with exact aggregate/retained-size reporting.
  • Handle the Bun bun.String vs Home *String return ABI and ownership correctly.
  • Cover arena and precise-GC contexts, cycles, sibling realms, weak references, ArrayBuffer/external bytes, OOM/failure atomicity, and repeated snapshots.
  • Promote the applicable PR-249 heap-snapshot/preventCollection reference case with an explicit disposition for JSC-only hooks.
  • Add bounded Debug, ReleaseSafe, and sanitizer evidence; refresh inventories, README counts, and roadmap evidence.
  • Close only after fixing CI is green.

No placeholder JSON or count-only output: consumers must be able to parse/traverse the graph and use the V8 snapshot with standard tooling.

9 days ago

The collector prerequisite is now implemented in zig-utils/zig-gc#39 and pushed as zig-gc c17c01a. Each cell has a process-unique, nonzero, never-recycled ID in its header; moving compaction preserves it; and zig-js can query immutable ID/kind/size metadata at the snapshot safepoint. Focused Debug and ReleaseSafe dependency checks are green.

This removes pointer-address identity from the #403 snapshot design and lets both the GCDebugging and V8 serializers share stable node IDs.

9 days ago

Dependency update: zig-utils/zig-gc#39 is complete. Stable cell identity landed in zig-gc c17c01a and its test + tsan Actions run is green: https://github.com/zig-utils/zig-gc/actions/runs/29773868754.

9 days ago

Implemented on main in 403a2a8, 0130a65, a33bc39, and 7983fca. Evidence now includes both Home/Bun ownership profiles; WebKit GCDebugging v3 and V8 schema parsing; VM-wide sibling roots, cycles, weak-only omission, ArrayBuffer external bytes, stable IDs across arena repeats and real precise-GC compaction; dominator-derived retained sizes with a cyclic graph oracle; injected OOM/no-partial-output/no-leak checks; Debug, ReleaseSafe, and TSan fixtures; and the explicit PR-249 portable/JSC-only disposition. Local ABI audits, release compatibility, reference audit, and 32-page docs build are green. Awaiting the exact main private-abi-boundary CI job before closure.

9 days ago

Closure gate is green: the exact private-abi-boundary job for main commit 7983fcab completed successfully: https://github.com/zig-utils/zig-js/actions/runs/29776746300/job/88467854285

9 days ago

Follow-up inventory drift was reconciled in 2fa80c3: the PR-249 heap-snapshot dependency now records the existing #403 partial resolution. Exact threads-reference-audit is green in https://github.com/zig-utils/zig-js/actions/runs/29787583184/job/88502417146

Sign in to comment on this issue.