ReviewOS

zig-utils/zig-js

GC relocation: inventory movable pointers and define the rewrite contract

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

Parent: #144 Roadmap: #134 Related: #325

Define the auditable pointer and identity contract required before any heap cell can move. This is a correctness foundation, not a claim that compaction is active.

Scope

  • Inventory every heap-cell pointer representation and owner: NaN-boxed Values, raw typed pointers, atomic slots, native-private data, Wasm references, weak/finalization records, C/Objective-C/private-ABI handles, debugger state, interpreter frames, and JIT metadata.
  • Classify each occurrence as immovable, stable-handle-backed, precisely rewritable, interior, or forbidden across a safepoint.
  • Define a relocation visitor API distinct from marking, including strong, weak, ephemeron, atomic, optional, and interior-reference operations.
  • Define stable object identity across relocation and the forwarding metadata/header lifecycle.
  • Add a checked-in machine-readable inventory plus a verifier that fails on drift in declared pointer-bearing fields and root registries.
  • Document safepoint and native embedding rules without enabling movement yet.

Acceptance

  • Every production GC cell kind and root registry appears in the inventory with an explicit rewrite strategy.
  • The relocation visitor can express all current tracing edges without silently treating raw pointers as stable.
  • Forwarding metadata and stable identity rules are represented in code and covered by focused tests.
  • C API, Objective-C, Bun/Home ABI, inspector, Worker/Thread, Promise/module, Wasm, and JIT boundaries have explicit dispositions.
  • Inventory/verifier, focused normal tests, and focused TSan tests pass with zero leaks.
  • #144 is updated with the committed evidence and the next child is unblocked.
9 days ago

Foundation landed on main in 6044da98 with the CI hook in a9ec20b3.

Evidence and boundary:

  • checked inventory: 9/9 live CellKinds, 26 pointer surfaces, and 21 required runtime/embedding tags;
  • source-anchor and enum-derived drift verifier exposed as zig build gc-relocation-inventory-check;
  • typed contract for stable logical IDs, forwarding records, required/optional strong edges, weak edges, atomic strong/weak slots, atomic/tagged Values, and proven-base interior projections;
  • explicit pinning rules for conservative native roots and the current native JIT frame; movement remains deliberately disabled;
  • focused normal and suppression-free TSan runs each pass 4/4 with zero failures or leaks; documentation builds successfully.

The verifier now runs in the bounded focused-engine-tests CI leg. Keeping this open only for descendant full-CI acceptance; #334 is otherwise unblocked.

9 days ago

Completed and accepted. The implementation-specific local evidence is recorded above, and descendant full CI at https://github.com/zig-utils/zig-js/actions/runs/29716788619 completed with 42 successful jobs, one intentional nightly skip, zero failures, and zero cancellations.

Sign in to comment on this issue.