GBC: Gengo Bytecode Cache — implementation

[ganehag]

The GBC spec is complete (docs/gbc-spec.md). Implementation has not started. GBC is a compiled module artifact that lets the runtime skip parsing and code generation for a known source file. It is not a heap snapshot.

Suggested first milestone

A minimal round-trip: writer + reader for a simple script with:

• No imports
• One bytecode section
• Constants
• Functions
• Empty types table
• Empty dependency table

Then add validation failures one by one until the full spec is covered.

Why it matters

• Eliminates parse + compile overhead on repeated loads of the same module
• Enables ahead-of-time compilation workflows (compile on dev machine, ship .gbc to constrained host)
• Required foundation for any future caching or separate compilation story

Notes

• GBC is not a memory snapshot — the VM still allocates and initialises objects at load time
• The spec covers magic bytes, version field, section table, and a dependency hash for invalidation
• See docs/gbc-spec.md for the full format

[ganehag]

Refining the checklist for this — since the spec was written, a few implementation-level decisions have been ratified that narrow the remaining work:

Wire format decision (ratified 2026-07-19/20): the wire serializes the defused, core-ops-only form exclusively. Fused/specialized opcodes never appear in a .gbc file — they're re-derived by the load-time fusion pass (src/lang/fusion_pass.zig) after loading, identically to a fresh compile. This means:

• Fused opcode values need zero wire stability — they can be freely renumbered between versions, since nothing external ever depends on them.
• The verification surface for external bytecode is just the core op set (~90 ops), not the full fused+core table.
• The fusion pass itself (already shipped, 660e690/8f58d02/4ea7207) is load-bearing GBC infrastructure: "run defused, re-fuse at load" is most of a correct-by-construction v1 loader.
• See dev-docs/design/vm-architecture.md §6.3 and docs/opcodes.md "Opcode space policy" for the full writeup.

Remaining concrete work, not yet started:

1. GBC writer/reader over the defused form (the compiler's natural pre-pass output) — the actual round-trip implementation this issue is tracking.
2. Verifier hardening for untrusted/external input:
   • Make path-dependent depth divergence a hard error (currently first-visit-wins marking tolerates it — found harmless for compiler-emitted bytecode by the B2 net-effect assertion, but a loader accepting external chunks can't assume that).
   • Decoder: extract and validate second const indices (e.g. call_global_local_sub_const's embedded global-name index) so constAt's checked path can be reasoned about uniformly for untrusted input.
3. Typed error sets for the loader's failure modes — deliberately deferred until the loader exists (no point designing error sets against a spec that hasn't met real parsing code yet).

Suggested first milestone is unchanged from the issue body: no-imports, one bytecode section, constants, functions, empty types/dependency tables, then add validation failures one by one.