ABI: implement strong and weak embedding references

[chrisbbreuer]

Parent

• Roadmap: implement every README-declared missing runtime surface #134
• ABI: define and implement versioned Bun and Home private-JSC profiles #140
• ABI: implement the pinned Home private-JSC profile #163
• ABI: implement the pinned Bun private-JSC profile #164

Scope

Implement the eight shared pinned reference imports:

• Bun__StrongRef__clear
• Bun__StrongRef__delete
• Bun__StrongRef__new
• Bun__StrongRef__set
• Bun__WeakRef__clear
• Bun__WeakRef__delete
• Bun__WeakRef__get
• Bun__WeakRef__new

Acceptance criteria

• Strong references retain the exact value across full and nursery collection, and set atomically replaces the rooted value without leaking the previous root.
• Weak references never retain their target, clear after collection when no strong path remains, and return the exact live value beforehand.
• Primitive, object, symbol, empty, and null/invalid inputs follow the pinned consumer boundary without manufacturing foreign-VM values.
• Reference wrappers record and enforce owning VM/global lifetime; cross-VM replacement is rejected deterministically.
• clear and delete are idempotent where the consumer contract permits it, are safe after target collection, and do not leave collector-visible stale pointers.
• The pinned WeakRefType and optional context are preserved for future callback/lifecycle behavior rather than discarded accidentally.
• Concurrent root tracing versus set/clear/get/delete is synchronized and covered without collector or wrapper use-after-free.
• Focused precise-GC, lifecycle, invalid-input, and multi-VM tests pass; Home/Bun inventories, combined fixture, API docs, README evidence, and parent trackers are regenerated.

[chrisbbreuer]

Implemented and pushed to main:

• zig-gc 7b1831e — atomic external weak slots with acquire/CAS clearing
• zig-gc c67e344 — post-weak-root owner notification outside collector locks
• zig-js 891829e4 — all eight strong/weak reference exports, precise-GC roots, lifetime ownership, finalization, and the expanded runtime fixture
• zig-js 0e772b3a — regenerated Home/Bun inventories plus README/API/integration evidence

Acceptance evidence:

• PrivateStrongRef.encoded is pinned at offset zero for Bun inline reads; the paired internal value is traced across full collection. Sibling-realm set succeeds, foreign-VM replacement leaves the existing root unchanged, and clear is idempotent.
• Handles retain their context group until delete, so wrapper storage, encoded cell handles, and root records cannot outlive their VM. Root-list mutations share the collector realm lock.
• Weak refs accept only the two pinned owner kinds and ordinary objects, preserve owner type/context, never mark the target strongly, and use atomic acquire/swap/CAS operations for embedder/collector synchronization.
• GC clearing invokes the FetchResponse owner callback exactly once outside zig-gc’s weak lock. Explicit clear/delete suppresses notification; PostgreSQL retains its pinned no-callback behavior.
• Focused zig-gc atomic-weak and scratch-retention tests pass.
• zig build test -Dtest-filter="private embedding references" -Doptimize=Debug: 3/3 pass with zero leaks, covering strong survival, weak death, one-shot callback, explicit-clear suppression, metadata, invalid values/types, and null calls.
• zig build test-home-private-abi -Doptimize=Debug: Home 161/431 implemented, 270 pending; combined fixture 160/160.
• python3 tools/bun-private-abi.py: Bun core 155/421 implemented, 266 pending. Public/extension accounting remains 117/19.

README, API docs, Home integration guidance, and both checked-in inventories now report the same evidence.

[chrisbbreuer]

All eight pinned imports, precise-GC and owner-finalization behavior, expanded consumer fixture, regenerated inventories, and README/API evidence are on main. Closing as complete; remaining private imports continue under the updated parent profiles.