ReviewOS

zig-utils/zig-js

ABI: project complete ZigException metadata and source lines

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

Goal

Complete the pinned Home/Bun exception projection immediately downstream of #249 by implementing JSC__JSValue__toZigException, ZigException__collectSourceLines, and ZigException__fromException against exact extern layouts and ownership rules.

Parent tracking: #134, #140, #163, #164.

Why this is one slice

#249 intentionally implemented the upstream OnlyPosition stack pass. Home then performs a second OnlySourceLines pass over the same retained frames, while full exception projection owns error classification, name/message/system fields, frame storage, and the stable exception-cell pointer. Splitting those paths would duplicate layout and ownership logic or leave a misleading half-usable ABI.

Required implementation

  • Pin ZigException, ZigStackTrace, frame, string, error-code, and runtime-type layouts with compile-time offsets/sizes.
  • Project Error, DOMException, primitive throws, and error-like objects without parsing the formatted .stack text when retained frames exist.
  • Preserve exact name/message/type/runtime type plus non-observable errno, syscall, code, path, and fd fields where applicable.
  • Populate caller-owned frame buffers with owned strings and stable exception-cell identity; preserve first pending exceptions and reject foreign VMs.
  • Implement the second source-line pass from retained script/module source, honoring source_lines_to_collect, line numbers, UTF-8/UTF-16 safety, truncation, and provider lifetime semantics.
  • Implement by-value ZigException__fromException with explicit zero/owned-field behavior despite having no caller frame buffer.
  • Cover syntax/runtime/primitive/DOM/system-like errors, empty and capped buffers, sibling realms, foreign VMs, GC, ownership/deinit, and source lines near file boundaries.
  • Promote both inventories and update README/API/Home integration evidence.

Evidence gate

  • Home and Bun audits retain zero unclassified declarations.
  • The compiled Home consumer checks exact layouts and runtime projection/source-line behavior.
  • Targeted exception/stack/module/GC validation passes with zero leaks.
  • The broad suite is batched with adjacent slices.
  • The current benchmark artifact remains linked unless measured code changes.
9 days ago

Implemented and published directly to main in three small commits:

  • 85711699 — exact exception layouts, projection, retained script IDs, source-line pass, inventories, and compiled consumer coverage
  • d99ad723 — README/API/Home/ABI documentation and current profile counts
  • 2d2e7096 — explicit capped Unicode source-line evidence

Final evidence:

  • Home: 252/431 implemented, 179 pending, zero unclassified.
  • Bun core: 246/421 implemented, 175 pending, zero unclassified.
  • Compiled consumer: 251/251 linked; runtime matrix passed.
  • Exact 216-byte ZigException, 48-byte trace, 72-byte frame, and 12-byte position layouts are compile-pinned.
  • Runtime coverage includes Error, SyntaxError, DOMException, primitive and system-like fields, cause runtime type, stable exception cells, by-value conversion, same-VM sibling realms, foreign rejection, owned/deinitialized strings, one-line boundaries, and capped multi-line Unicode source windows.
  • Source collection uses the retained script identity and never parses formatted .stack or invokes user getters. Owned line strings intentionally require no provider reference.
  • The broad suite remains batched with the adjacent completed slices; its last run had no failure or leak beyond the cold-sidecar assertion fixed and revalidated in 05c3751d. The current benchmark report remains valid because these private exception exports are outside the measured workload.

Sign in to comment on this issue.