This commit is contained in:
2026-03-24 13:40:31 +00:00
parent 6eda2d21ac
commit c9b9f18b32
5 changed files with 29 additions and 109 deletions
-101
View File
@@ -11,107 +11,6 @@
* A **single canonical layout/decoder/spec** is used across compiler/linker/verifier/VM.
* Any invalid program fails with clear diagnostics, not panics.
**Estimation scale:**
* **1 point** = small / straightforward
* **3 points** = medium
* **5 points** = large
* Any work that feels bigger must be broken down into multiple PRs (≤ 5 points each).
---
## Phase 1 — Single Source of Truth: Bytecode Spec + Decoder (Highest ROI)
### PR-01 (3 pts) — Move OpcodeSpec to `prometeu-bytecode` and make it authoritative
**Briefing**
Today opcode metadata (imm sizes, stack effects, branch-ness, terminators) is duplicated and/or inconsistent across crates. This creates a perpetual maintenance nightmare.
**Target**
Create one authoritative opcode spec in **`prometeu-bytecode`** and delete/replace all “local” opcode knowledge.
**Scope**
* Create `prometeu-bytecode::opcode_spec` containing:
* `imm_bytes`
* `pops`, `pushes` (stack effect)
* `is_branch`, `is_terminator`
* optional: `name`, `category`
* Update callers to import from `prometeu-bytecode`.
**Requirements Checklist**
* [ ] There is exactly one canonical `OpcodeSpec` source.
* [ ] All crates compile against that source.
* [ ] No hardcoded operand sizes remain outside the spec.
**Completion Tests**
* [ ] Unit test enumerating all opcodes validates:
* every opcode has a spec
* `imm_bytes` is defined
---
### PR-02 (5 pts) — Introduce canonical decoder in `prometeu-bytecode` and migrate VM to it
**Briefing**
The VM currently has its own decoder. The linker and other tools decode manually. This must be centralized.
**Target**
Add a single canonical decoder in `prometeu-bytecode` that produces typed decoded instructions.
**Scope**
* Add `prometeu-bytecode::decoder`:
* `decode_next(pc, bytes) -> DecodedInstr`
* includes: opcode, pc, next_pc, raw immediate bytes slice
* helpers: `imm_u8/u16/u32/i32/i64/f64` with size validation
* Migrate VM to use `prometeu-bytecode::decoder`.
**Requirements Checklist**
* [ ] VM no longer has a bespoke decoder.
* [ ] No slicing-based immediate parsing in VM core paths.
* [ ] Decoder validates immediate sizes and fails deterministically.
**Completion Tests**
* [ ] Decoder unit tests for representative opcodes with each immediate size.
* [ ] Roundtrip test: encode→decode (table-driven; property test optional).
---
### PR-03 (3 pts) — Delete/neutralize `abi::operand_size` duplication
**Briefing**
`prometeu-bytecode/src/abi.rs` provides partial operand sizing that can drift from the canonical spec.
**Target**
Make all operand sizing derived from the opcode spec.
**Scope**
* Replace `operand_size()` with `OpcodeSpec::imm_bytes`.
* Remove or restrict legacy APIs that leak duplication.
**Requirements Checklist**
* [ ] There is no second operand-size table.
**Completion Tests**
* [ ] Test ensuring `operand_size()` (if retained) matches spec for all opcodes.
---
## Phase 2 — Canonical Layout + Verifier Contract (JVM-like Control Flow)