ReviewOS

zig-utils/zig-js

ABI: implement exact global-object lifecycle

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

Parent: #140 Profiles: #163, #164 Roadmap: #134 Dependency: #414 Pinned consumer: oven-sh/bun@4982b91e3702094330f3be3883354c52b8c01323 Pinned implementation reference: src/jsc/bindings/ZigGlobalObject.cpp

Implement the private global-object creation, test-isolation replacement, and exit teardown as one ownership-complete lifecycle slice. These symbols must create and retire real zig-js realms; they must not be aliases, inert shims, or ordinary-object factories.

Acceptance:

  • Implement Zig__GlobalObject__create(*anyopaque, i32, bool, bool, ?*anyopaque) *JSGlobalObject as a standalone VM plus exposed realm, preserving the pinned context identifier, mini/full heap choice, eval-mode flag, worker flag, and console metadata.
  • Implement Zig__GlobalObject__createForTestIsolation(old_global, console) as a new same-VM realm that preserves the script-execution-context identity and relevant embedder metadata while retiring the old realm from future lookup/use.
  • Implement consuming, idempotent Zig__GlobalObject__destructOnExit: stop work, retire identifiers, clear module/job/embedding roots, collect when supported, and release the owned VM/realm without double-free or stale lookup.
  • Define explicit null, foreign, already-retired, retained-reference, sibling-realm, and wrong-thread behavior rather than relying on accidental C-API ownership.
  • Cover metadata preservation, realm identity/prototypes, module-registry isolation, queued-work teardown, external-owner finalization, precise-GC collection, and concurrent lookup retirement. Precise collection is tracked by #414.
  • Add independently compiled Home and Bun ABI fixtures plus focused Debug, ReleaseSafe, and TSan evidence.
  • Pin an exact source/semantic contract, promote all three symbols in both inventories with zero unclassified entries, and update ABI docs/README without changing unrelated benchmark scores.
  • Reconcile exact main CI before closure.
9 days ago

Implemented the ownership-complete arena-backed lifecycle in 47d08d89, with the pinned contract, independent Home/Bun executables, inventories, CI matrix, and concise docs in c4fff8e5.

Focused evidence:

  • internal lifecycle test: 3 passed, 0 leaked
  • Home and Bun ABI executables: Debug passed
  • Home and Bun ABI executables: ReleaseSafe passed
  • Home and Bun ABI executables: TSan passed
  • inventories: Home 444/471 implemented (27 pending), Bun 435/461 implemented (26 pending), zero unclassified
  • ordinary, null, foreign, stale, retained, repeated, same-VM, and wrong-thread cases are exercised

The replacement realm has clean globals and transfers process identity atomically. Physical reclamation of an old realm before VM teardown needs a shared precise-GC context-group architecture; that remaining acceptance is now explicitly tracked by #414. Exact main run: https://github.com/zig-utils/zig-js/actions/runs/29792663816

9 days ago

Complete. The three pinned lifecycle exports now create, replace, and idempotently retire real precise-GC realms with exact metadata/identity transfer and finalization. #414/#416 supplied physical same-VM reclamation; exact main run 29801586207 passed all 43 jobs, including the 392/392 Home private fixture.

9 days ago

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.

Sign in to comment on this issue.