ISA spec (isa_unified.py) does not match actual VM implementation

[SuperInstance]

Audit Finding

Severity: Critical
File(s): isa_unified.py (this repo) vs opcodes.py (flux-runtime repo)

Problem

The canonical ISA specification and the VM implementation have diverged on fundamental definitions. This is the single biggest blocker to ecosystem convergence.

Feature	isa_unified.py (spec)	opcodes.py (VM)	Match?
HALT opcode	0x00	0x80	❌
NOP opcode	0x01	0x00	❌
MOVI encoding	Format D, imm8 (3 bytes)	Format D, i16 (4 bytes)	❌
Branch offsets	Absolute addresses	PC-relative	❌ (probable)
Register file size	Documented as 16	Implementation may differ	❓

Root Cause

The unified ISA spec (isa_unified.py) was written as a clean-room design, while the VM (opcodes.py) evolved independently during development sessions. No reconciliation pass was performed.

Impact

• No runtime can pass conformance tests — they test against incompatible definitions
• Tooling fragmentation — assemblers, disassemblers, and compilers must pick one or the other
• Ecosystem split — repos that follow the spec cannot interoperate with repos that follow the VM

Suggested Fix (Priority Order)

1. Decide on source of truth: The running VM is the de-facto standard. Declare opcodes.py values as canonical.
2. Update isa_unified.py: Rewrite opcode values and encoding formats to match the VM exactly.
3. Add a golden test: Create a single source-of-truth JSON/YAML file that both the spec and VM import from.
4. Version the spec: Tag this as isa_unified.py v2.1 with a changelog documenting the alignment.

Related Issues

• flux-runtime: "Critical: Two incompatible ISA numbering systems"
• flux-benchmarks: "Critical: Benchmarks test against old opcode names"