Embedding: optimize Zig, C, private ABI, and Objective-C boundaries

Parent: #459 Depends on: #460, #461, #463, #473, #479

Goal

Make Zig, public C, private ABI, and Objective-C host boundaries low-overhead for realistic embedding patterns while preserving all handle/lifetime/exception/affinity contracts.

Scope

• Add symmetric host-boundary benchmarks for evaluate/compile, direct function/method/constructor calls, native callbacks, property/index access, strings UTF-8/UTF-16, typed arrays/no-copy buffers, protect/unprotect, context groups/realms, promises/jobs, modules, inspector, and ObjC/Foundation conversion.
• Attribute boxing/handle lookup, context/realm validation, string conversion/copy, argument marshalling, callbacks/reentrancy, exception projection, locks, GC protection/barriers, and allocator traffic.
• Add borrowed/owned views, batched operations, cached descriptors, or direct native stubs only when lifetime, mutation, relocation, and ABI behavior remain exact.
• Keep public/private profile layouts and version pins immutable unless an intentional versioned contract change is made.
• Compare system JSC only for exact public/ObjC API-equivalent calls; report zig-js extensions separately.

No-workaround rules

• No raw internal pointer leak, skipped affinity/realm validation, unrooted borrowed value, elided exception, mutable buffer alias beyond contract, or benchmark-only unsafe API.

Acceptance

• #460 contains cold/warm, scalar/batch, small/large, callback/reentrant, GC-moving, and 1/8-context host rows with exact transcripts/checksums.
• Public C, private Home/Bun, and ObjC inventory/audit fixtures remain exact in Debug/ReleaseSafe/TSan.
• #463 removes libffi without regressing the owned bridge path.
• Profiles prove reduced marshalling/copy/handle/lock cost with bounded memory and exact teardown.
• Every directly comparable accepted host-boundary row meets #459 gates.

Foundation

Completed public/private/ObjC profiles under #135/#138/#140 and their linked inventories; stable embedding docs in docs/api.md.

String private-ABI child #622 is complete via 287550f8. JSC__JSValue__stringIncludes now shares the bounded-linear exact UTF-16 matcher and maps scratch OOM into the pending-exception channel. Home private ABI audit was 447/447 with 0 pending/unclassified; the 392/392 runtime matrix passed normal and TSan.

Child #654 is complete and closed. Every private-ABI Zig build now carries the pinned checked-out Home runtime in build-graph identity, and the fresh complete Linux private-ABI boundary leg passed. Closure evidence: /zig-utils/zig-js/issues/654#issuecomment-5360870045

Opened #672 to audit and correct private ABI String-value egress into semantic byte consumers. Scope is canonical property keys/atoms, URL and form parsing, module/time-zone source, and Error text, with unchanged symbols/layouts and full private/public ABI fixtures.

Child #672 is complete in df57cd7e. Private decoded-string egress is canonical across keys/atoms, names, error text, URL/form/DOMURL, time-zone, and property paths; Home/Bun ABI audits and affected runtime fixtures are green with zero symbol or layout changes.

Opened #674 for the remaining public C value-key boundary. JSObject*PropertyForKey currently routes String Values through the physical asStr() image; the child will make all four entry points consume canonical WTF-8, preserve allocation-free ASCII/canonical borrowing and public exception semantics, and verify the pinned C ABI with no symbol/layout change.

Public value-key child #674 is complete in d56dbb80. JSObject*PropertyForKey now canonicalizes String Values representation-aware after ToPropertyKey, borrowing ASCII/canonical storage and preserving public OOM exceptions for future flat Latin-1 conversion. Public audit 117/117, Home ABI 50/50, all public host fixtures, TSan, ReleaseSafe, and 1767-pass full units are green with no ABI change.

Private embedding name egress child #692 is complete in 09941fcd. Callable display names, class names, tags, and received-value diagnostics now expose canonical WTF-8 under both current and flat Latin-1 storage, with existing lookup/exception ordering and fail-closed OOM behavior preserved. Public/private ABI audits and fixtures pass; full Debug and TSan inventories are green; 0 applicable Test262 files/flips.

Private StringData boundary follow-up #696 landed in 459af38b: JSString/boxed equality is semantic and Jest-compatible substring predicates now search UTF-16 code units. Home/Bun ABI inventories and the 392/392 Home runtime fixture remain green.

Closed embedding leaf #699 in ad6c363c: private DOMFormData callbacks now preserve non-ASCII filenames across canonical and flat-Latin-1 StringCell layouts, publish conversion OOM, and retain exact Home/Bun/public-C ABI inventories. Full units: 1,794 passed, 1 skipped, 0 failed/leaked; Test262 flips 0.

Closed Zig embedding leaf #701 in 40febcea: public js.Value.toString now returns canonical WTF-8 for non-ASCII Error name/message fields without invoking JavaScript hooks or reallocating canonical storage. Full units: 1,795 passed, 1 skipped, 0 failed/leaked; direct Zig API Test262 coverage is 0.

Private profiler StringData leaf #703 is complete in b959adf7. V8 snapshot and heap-profile cell names now cross the private ABI as canonical WTF-8 with snapshot-scoped conversion storage; Home/Bun Debug, ReleaseSafe, and TSan ownership fixtures and exact 447/447 + 437/437 private inventories are green. This closes the discovered representation leak without changing ABI signatures or GCDebugging schema.

C API enumeration slice #759 landed in 1adc7b7b. JSObjectCopyPropertyNames prototype membership and host-class/ordinary own-key overlap now use lazy secure exact-byte indexing; the focused C API witness covers host-first ordering, duplicates, ordinary continuation, 4 KiB names, encoded NUL, and non-enumerable shadowing in normal and TSan modes.

C/private ABI property-name boundary hardening landed in #762 via fix(c-api): seed property name membership (#762). C-API differential remains 34/34 against JSC, Home private ABI is 392/392, and public/private inventories remain complete.

#763 is complete in fix(private-abi): seed borrowed string interning (#763): group/global borrowed ZigString views and heap-snapshot names now use the shared secure exact-byte primitive; Home 392/392, Home/Bun heap fixtures pass, audits remain complete.

The shared intern table consumed by private atomic-string paths is hardened in #764 via 288b4893. Home private ABI remains 392/392, private semantic egress 1/1, and C/JSC differential 34/34; no ABI surface or deterministic StringCell identity changed.

Completed the private embedding-side Wasm streaming handle hardening in #865 via fix(wasm): harden streaming compiler handles (#865).

The revision-pinned context-free addBytes signature is unchanged. Secure capability issuance, independently keyed exact registry lookup, failure-atomic initialization, and all Home/Bun ownership/lifecycle fixtures are documented and pass in Debug, ReleaseSafe, and TSan. #865 contains the complete linked evidence.

The private structured-serialization ownership boundary was hardened in #866 and shipped in c6642bb2, preserving the pinned ABI layout while replacing predictable owner IDs with secure exact capabilities.

Private execution-context registry hardening landed through #867 in 58697c0e, preserving the pinned 32-bit ID ABI while securing map placement and failure ordering. The separately discovered INT32_MAX macro-sentinel compatibility mismatch is tracked in #868.

Pinned macro-context identifier semantics are now exact through #868 in fix(private-abi): preserve macro context identifiers (#868). INT32_MAX is translated through the shared monotonic namespace, reserved from ordinary allocation, and covered across Home/Bun Debug, ReleaseSafe, TSan, and exact full units.

Follow-up #869 is complete in fix(private-abi): harden VM identity registries (#869). The remaining VM-owned canonical-object and contiguous-vector identity registries now use independent lazy secure exact-identity maps with failure-atomic first publication and allocation-free moving-GC rekeying. Full validation evidence is recorded in #869.

Follow-up #870 is complete in 17dea421 — fix(private-abi): harden lifecycle registry (#870). The process-global private lifecycle table now uses independent lazy secure exact-pointer hashing, failure-atomic publication, centralized exact retirement, and empty-table reset/reseed, with Debug/ReleaseSafe/TSan, external fixtures, fuzz, full units, ABI audits, and docs gates passing.

Embedding hardening issue #871 is complete in 516a8d59. The public signatures remain unchanged while both inspector transports now expose opaque random capabilities rather than allocator addresses, with exact kind/liveness/owner validation and documented failure behavior.

Embedding validation follow-up #872 is complete in 99e534be. The complete public C/C++ host suite now passes in Debug, ReleaseSafe, and TSan while the pinned public ABI remains 117/117 complete.

Closed #1087 in a9dcaf24: warmed inherited native caches skipped mandatory public JSClassRef get callbacks after one unhandled response. The public C fixture now matches system JSC's values, exception, and exact callback counts; it is included in the ordinary C/C++ host suite and the standard 35-row JSC differential gate.

Canonical observation publication and native cache/frame-proof consumption now preserve the observable lookup prefix. Debug, ReleaseSafe, unsuppressed TSan, explicit precise-GC/shared lookup, finalization, ordinary native-cache, and 403 paired upstream cases pass. ABI exports/layouts are unchanged, and no performance result is being promoted. Hosted integration remains queued; broader embedding performance acceptance remains open.