ReviewOS

zig-utils/zig-js

ABI: expose exact native CallFrame caller metadata

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

Goal

Implement the three pinned Home/Bun CallFrame introspection exports for Zig host callbacks: Bun__CallFrame__getCallerSrcLoc, Bun__CallFrame__isFromBunMain, and debug Bun__CallFrame__describeFrame.

Parent tracking: #134, #140, #163, #164. Depends on #248 and #250.

Required implementation

  • Associate each active pinned JSC64 callback frame with its owning VM and visible JavaScript caller without changing the consumer-visible register layout.
  • Return an owned source URL plus exact one-based line/column, skipping the private native frame and preserving same-VM sibling behavior.
  • Detect builtin://bun/main from caller source origin and reject null, stale, mismatched-frame, and foreign-VM inputs.
  • Provide a stable NUL-terminated debug description for the active frame without heap lifetime ambiguity.
  • Preserve nested/reentrant native callbacks and pending exceptions.
  • Promote both inventories and update README/API/Home/ABI evidence.

Evidence gate

  • Compiled consumer invokes all three exports from ordinary, constructor, nested, named-source, builtin-source, sibling-global, invalid, and foreign-VM cases.
  • Home/Bun inventories remain zero-unclassified.
  • Targeted host-function/CallFrame runtime matrix passes; broad testing stays batched with adjacent slices.
  • Current benchmark remains linked unless measured workload code changes.
9 days ago

Implemented and published directly to main:

  • 4949ce39 — active-frame ownership, all three exports, inventories, and compiled runtime coverage
  • c0e2b8ec — README/API/Home/ABI evidence and current counts

Final evidence:

  • Home: 255/431 implemented, 176 pending, zero unclassified.
  • Bun core: 249/421 implemented, 172 pending, zero unclassified.
  • Compiled consumer: 254/254 linked; runtime matrix passed.
  • The consumer-visible six-register JSC64 CallFrame remains unchanged. A nested thread-local descriptor exists only for the synchronous callback lifetime.
  • getCallerSrcLoc returns owned source URLs with exact one-based coordinates through same-VM sibling globals. isFromBunMain validates VM identity and the exact builtin origin. describeFrame returns bounded stable NUL-terminated text.
  • Ordinary calls, constructors, named/builtin origins, foreign globals/VMs, null/stale pointers, and nested reentrant restoration are covered.
  • Broad testing remains batched; the benchmark report remains current because no measured workload executes these private exports.

Sign in to comment on this issue.