ReviewOS

zig-utils/zig-js

ABI: implement the pinned JSC64 EncodedJSValue boundary codec

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

Parents: #163, #164 Depends on: #165

Home and Bun inspect EncodedJSValue words inline, while zig-js uses its own internal NaN-box tags. Implement an explicit private-ABI boundary codec instead of conflating the two layouts.

Acceptance:

  • Pin the exact JSC64 empty/null/boolean/undefined/int32/double/cell encodings used by the declared Home/Bun revisions.
  • Prove 8-byte size/alignment and exact constant values.
  • Round-trip signed int32, finite doubles, infinities, canonical/noncanonical NaNs, and negative zero without colliding with cells or immediates.
  • Validate aligned non-null external cell handles and reject empty/immediate/number words as cells.
  • Provide explicit primitive conversion to/from zig-js internal Value without changing the internal representation.
  • Add focused reference-derived tests and document why private shims must use this boundary.
9 days ago

Completed in aea89f2 and documented in 6cc32c1.

Focused evidence: zig build test-private-abi-value passes the exact 8-byte JSC64 constants, signed-int32 endpoints, finite/infinite/negative-zero doubles, positive and negative noncanonical NaNs, aligned cell handles, invalid-cell rejection, and real primitive conversion to/from js.Value. String/object conversion deterministically requires a future external cell handle, so the codec cannot accidentally expose zig-js internal NaN-box bits.

Sign in to comment on this issue.