Parent: #459 Depends on: #465, #479, #480, #483, #498 Related: #481, #496, #500
Goal
Add versioned portable bytecode, immutable realm/bootstrap snapshots, and optional ahead-of-time artifacts for fast startup and restricted-JIT deployments.
Scope
- Define a deterministic serialized format for validated bytecode, constants/names, lexical metadata, source locations/maps, exception handlers, module metadata, feature/options keys, and integrity checks.
- Snapshot only immutable or explicitly copy-on-write realm bootstrap state: builtin bytecode/templates, canonical atoms/shapes, generated tables, and read-only metadata. Per-realm globals, prototypes, registries, jobs, handles, GC state, and mutable caches remain isolated.
- Support compile-once/load-many APIs for scripts/modules and owned build-time AOT generation where platform policy permits.
- Version artifacts by zig-js format, engine semantics, target/options/features, owned dependency revisions, generated-data versions, and backend/CPU features.
- Validate lengths, offsets, graphs, maps, relocations, stack limits, signatures, hashes, and resource bounds before allocating/publishing.
- Integrate precise GC roots, debugger/source registration, invalidation, code-cache eviction, memory pressure, and exact teardown.
- Measure serialization/build cost, load/start latency, cold evaluation, code/bytecode bytes, mapped/retained RSS, and cache hit/miss behavior.
No-workaround rules
- No raw pointer/layout dump, trusted unchecked cache, source/hash collision shortcut, hidden pre-created mutable Context, precomputed benchmark output, native artifact loaded on an incompatible CPU, or compilation moved outside an existing cold timer without a separately labeled precompiled mode.
Acceptance
- Format specification, schema/version inventory, deterministic encoder, hostile decoder tests, and reproducible fixture hashes are checked in.
- Fresh compile and serialized/AOT load execute exact semantic, exception, source/debugger, step, GC, no-GIL, and teardown differentials.
- Corrupt, stale, wrong-option, wrong-dependency, wrong-target, and oversized artifacts fail closed before execution.
- Repeated realms prove mutable-state isolation and bounded shared immutable lifetime.
- #460 publishes separate cold-source, cold-precompiled, and warm-cache panels with all build/load work and memory boundaries explicit.
- Restricted platforms consume portable artifacts through #498 without claiming native JIT execution.
Foundation
Bytecode ownership is defined in src/bytecode.zig; cold lifecycle and bounded cache policy are tracked by #479/#480.