ReviewOS

zig-utils/zig-js

ABI: implement the private JSString backing iterator

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

Parent: #140 Related: #134, #163, #164

Implement the shared private JSString backing-iterator boundary using zig-js owned string cells and the pinned caller-owned callback layout.

Scope

  • JSC__JSString__iterator

Acceptance

  • Validate the JSString cell and selected VM/realm without coercion or observable user code.
  • Reproduce the pinned extern iterator layout (data, stop, append8/append16/write8/write16 callbacks).
  • Deliver 8-bit strings as Latin-1 and non-8-bit strings as exact UTF-16 code units, including astral pairs, lone surrogates, embedded NUL, and empty strings.
  • Honor callback nullability and the caller stop flag safely; never retain callback pointers or caller data after return.
  • Reject null, non-string, dead, and foreign-VM cells without pointer access or callback invocation, preserving an existing pending exception.
  • Add focused and compiled-consumer fixtures, update both inventories and README/API/ABI evidence, and publish verification.

Flat zig-js strings may use one append callback; write callbacks remain part of the validated layout for compatibility with consumers that also accept JSC rope traversal.

9 days ago

Completed on origin/main.

  • ade5f898 implements the pinned 48-byte caller-owned iterator layout and exact flat-string callback delivery.
  • debc7079 publishes the inventories and README/API/ABI evidence.

Verification:

  • Home compiled consumer: 247/247 runtime/link matrix
  • Home inventory: 248/431 implemented, 183 pending, zero unclassified
  • Bun core inventory: 242/421 implemented, 179 pending, zero unclassified

Coverage includes Latin-1, exact UTF-16 astral/lone-surrogate units, embedded NUL, empty strings, stop, null callback/iterator/cell boundaries, foreign VM rejection, and first-exception preservation. Callback and caller-data pointers are used synchronously only and are never retained.

Sign in to comment on this issue.