GC relocation: inventory movable pointers and define the rewrite contract

[chrisbbreuer]

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.
• GC: implement moving and compacting collection #144 is updated with the committed evidence and the next child is unblocked.

[chrisbbreuer]

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.

[chrisbbreuer]

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.