ReviewOS

zig-utils/zig-js

ABI: implement exact Symbol registry and description bridges

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

Parent

Scope

Implement the three shared pinned Symbol bridges:

  • JSC__JSValue__symbolFor
  • JSC__JSValue__symbolKeyFor
  • JSC__JSValue__getSymbolDescription

Acceptance criteria

  • symbolFor decodes every tagged ZigString representation, uses the VM-shared GlobalSymbolRegistry without observable userland calls, and preserves registry identity across sibling realms while isolating foreign VMs.
  • getSymbolDescription returns the exact UID/description as a stable borrowed ZigString view, writes the canonical non-null empty view for an empty description, and leaves output untouched for non-Symbol inputs.
  • symbolKeyFor returns true and writes the exact registry key only for registry-backed Symbols; local and well-known Symbols return false and leave output untouched.
  • Latin-1, UTF-8, UTF-16, astral/lone-surrogate, empty, local, registered, and well-known cases are covered alongside mutation-safe input copying, sibling/foreign VM behavior, invalid input, allocation failure, and first pending-exception preservation.
  • Home/Bun inventories, README/API evidence, and all parent trackers are regenerated from checked-in results.
9 days ago

Implemented and published directly on main.

Implementation: 5f8bf8f3 (feat(abi): implement Symbol registry bridges (#205)) Documentation: e9d8de57 (docs(abi): publish Symbol bridge evidence (#205))

Delivered:

  • exact symbolFor, symbolKeyFor, and symbol-description bridges;
  • every tagged ZigString representation, including Latin-1, UTF-8, UTF-16, astral text, lone surrogates, and empty keys;
  • stable group-lifetime Latin-1/UTF-16 output views with untouched outputs on false/non-Symbol paths;
  • exact registered vs local vs well-known behavior, caller-input mutation safety, sibling identity, foreign-VM isolation, and first pending-exception preservation;
  • a fix at C-API realm bootstrap so all sibling realms share one GlobalSymbolRegistry even when registration begins after both realms exist.

Validation:

  • zig build test-home-private-abi -Doptimize=Debug — green, 118/118 symbols linked and runtime matrix passed.
  • zig build home-private-abi-audit bun-private-abi-audit — green.
  • Home: 119/431 implemented, 312 pending.
  • Bun core: 113/421 implemented, 308 pending.
  • Public/extension accounting remains 117/19.

README benchmark scores were preserved because this was an ABI/correctness slice and no benchmark input changed.

Sign in to comment on this issue.