ReviewOS

zig-utils/zig-js

ABI: implement the Home private JSMap boundary

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

Parent: #163 Depends on: #175, #176

Implement the complete seven-symbol JSMap.zig private ABI declared by the pinned Home profile. Bun routes these calls through its excluded generated bun.cpp surface, so this child intentionally changes the Home denominator only.

Exact ABI scope

  • JSC__JSMap__create
  • JSC__JSMap__set
  • JSC__JSMap__get
  • JSC__JSMap__has
  • JSC__JSMap__remove
  • JSC__JSMap__clear
  • JSC__JSMap__size

Acceptance

  • Create a fresh native Map with the selected realm Map.prototype and return its exact opaque cell pointer.
  • Operate directly on native Map internal storage without invoking mutable userland Map.prototype methods, accessors, proxies, or subclass hooks.
  • Match SameValueZero key semantics, including NaN equality, +0/-0 canonicalization, primitive value equality, and object identity.
  • Preserve insertion order; replacing an existing value does not move its key; deletion leaves iteration coherent; reinsertion appends; clear removes every live entry.
  • Return exact stored value identity, undefined for a missing key, exact has/remove booleans, and live-entry usize size.
  • Accept sibling-realm keys and values from the same VM, reject foreign-VM values failure-atomically with a VM-shared TypeError, and preserve the first pending exception.
  • Reject non-Map, WeakMap, exception, empty, and mismatched-VM handles safely without mutating state.
  • Extend the combined compile-link-runtime fixture with selected-realm, identity, SameValueZero, ordering, direct-storage, invalid-handle, and exception tests.
  • Regenerate and verify inventories, update README/API/ABI/Home docs and parent issue evidence, and keep Bun/public/extension accounting unchanged.
9 days ago

Implemented and documented on main in f4b6a58 and 07ed5d3.

Evidence:

  • zig build test-home-private-abi -Doptimize=Debug: Home 78 implemented / 354 pending; combined fixture 76/76 linked and runtime matrix passed.
  • zig build home-private-abi-audit bun-private-abi-audit c-api-audit: Home 78/432, Bun unchanged at 71/422, public 117/117, extensions 19, private export union 78.
  • Covered selected-realm Map.prototype, empty/missing behavior, exact stored identity, SameValueZero for NaN and signed zero, string value equality, object identity, update order, deletion/reinsertion order, mutable Map.prototype bypass, same-VM siblings, foreign key/value failure atomicity, ordinary/WeakMap/foreign receivers, first pending exception preservation, and clear.
  • README, Home integration, API, and ABI guides publish the asymmetric Home/Bun totals and exact direct-storage contract. Benchmark scores remain unchanged because the ABI slice does not alter benchmark workloads.

Sign in to comment on this issue.