docs/plans/bytecode_layout_migration_analysis.md

**Bytecode Layout**

Current layout: `fixed5x32-v1` uses 5 `i32` words per instruction.

Observed facts from `data/cards_compiled.json`:

- Instructions analyzed: 5,172
- JSON database size: 11,222,487 bytes
- Binary snapshot size: 3,139,615 bytes
- `V` is zero in 36.49% of instructions
- `A_LOW` is zero in 79.39% of instructions
- `A_HIGH` is zero in 79.93% of instructions
- `S` is zero in 45.32% of instructions
- Only 20.07% of instructions need a non-zero high 32 bits of `A`
- Rough zero-bit rate across raw 32-bit words: about 96.75%
- Unique full instructions: 599 out of 5,173, about 11.58%

Instruction shape distribution:

- `op_only`: 1,554 instructions, 30.05%
- `op_v`: 637 instructions, 12.32%
- `op_v_a`: 113 instructions, 2.18%
- `op_v_s`: 1,130 instructions, 21.85%
- `full`: 1,738 instructions, 33.60%

Rough storage estimate:

- Fixed-width words: 25,860
- Compact optional-field words: 13,982
- Potential reduction: 11,878 words, 45.93%

**What This Means**

The fixed-width VM is materially wasteful, but the pain is not just storage. The real coupling is execution math:

- The Rust engine assumes `ip += 5`
- Jumps are encoded in instruction-count units derived from 5-word chunks
- Many helpers use `chunks(5)` directly
- Some higher-level optimizations depend on bytecode offsets lining up with effect indices

So the bytecode is still important, but mostly as a stable execution contract. Its current shape is more of a transport convenience than a semantic necessity.

The zero-bit number is useful, but it overstates the practical gain if read literally. Many instructions are simple and repeated:

- `RETURN` appears everywhere
- common jumps and simple draw/buff effects recur often
- a lot of non-zero fields still only use a handful of bits

So there are really three different optimization levers:

1. Field compaction: stop storing absent `V/A/S` words
2. Narrower payload encoding: stop paying full 32 bits for tiny values
3. Dictionary or template encoding: reuse repeated instructions or repeated short sequences

Field compaction is the safest first step because it preserves the current instruction model.
Template encoding is likely the next-biggest size win because only about 11.6% of full instructions are unique.

**Best Next Step**

Do not jump directly from `fixed5x32-v1` to a fully irregular format.

Safer staged plan:

1. Introduce `BytecodeProgram` and centralize decoding behind an iterator/API.
2. Keep the in-memory interpreter interface stable while abstracting away `chunks(5)`.
3. Add a new layout version that uses a compact header per instruction plus optional payload words.
4. Convert jumps from `ip + 5 + v * 5` math to decoded instruction indices.
5. Keep compiler support for both layouts during migration.

**Recommended Compact Layout**

Use tagged instructions instead of raw 5-word tuples:

- Header word:
  - opcode
  - flags for `has_v`, `has_a`, `has_s`, `wide_a`
- Followed by only the present payload words

Examples:

- `RETURN` -> `[header]`
- `DRAW 1` -> `[header, v]`
- `SET_TAPPED true @slot` -> `[header, v, s]`
- Filtered effect -> `[header, v, a_low]`
- Wide filter effect -> `[header, v, a_low, a_high, s]`

That keeps decoding simple while removing most zero padding.

**Priority Order**

If the goal is maximum practical win with minimum risk:

1. Prune compiled JSON fields
2. Keep using `cards_compiled.bin`
3. Centralize bytecode access behind an abstraction
4. Only then migrate layout

If the goal is readability and debuggability:

1. Push more common patterns into generated Rust
2. Use bytecode as fallback for uncommon/complex patterns
3. Treat compact bytecode as a second-stage optimization