prometeu-runtime/files/TODOs.md

PR-1.2 — Remove HIP/RC Trap Codes From ABI

Briefing

The new architecture removes HIP/RC completely. Any ABI surface describing HIP traps or gate-related traps must be deleted.

Target

• Delete HIP/RC trap codes from bytecode ABI.
• Replace with a minimal, architecture-aligned trap/error taxonomy.

Work items

• Remove HIP trap constants/enums (e.g., anything like TRAP_INVALID_GATE, TRAP_DEAD_GATE, and related HIP trap identifiers).

• If there is a shared trap enum used by VM/tooling:

  • Keep only traps that remain meaningful in the GC stack+heap model (e.g., OOB, illegal instruction, stack underflow), as specified.
  • Rename/restructure as needed to reflect the reset.

• Update any match arms / formatting / disasm text that referenced HIP traps.

• Update tests and fixtures accordingly.

Acceptance checklist

• No HIP/gate trap identifiers remain in the codebase.
• Bytecode crates compile.
• Disassembler / printers compile and produce readable output for remaining traps.
• cargo test passes.

Tests

• Update/adjust any trap-related unit tests.

---

PR-1.3 — Remove RC/HIP Opcodes From opcode and Decode/Encode Paths

Briefing

Legacy opcodes must be removed entirely. Decoder/encoder must not recognize them, and there must be no compatibility decoding.

Target

• Remove all RC/HIP opcodes and their textual/structural representation.
• Ensure decoding fails deterministically for unknown opcodes.

Work items

• Delete RC/HIP-related opcode variants from prometeu-bytecode opcode definitions.

• Remove any encode/decode logic for those opcodes.

• Ensure decoder behavior for unknown opcodes is:

  • Deterministic.
  • Produces an actionable error message.
  • Has no fallback to “legacy”.

• Update disasm formatting tables and opcode-name maps.

• Update tests/fixtures that referenced removed opcodes.

Acceptance checklist

• Opcode enum(s) no longer include RC/HIP concepts.
• Encoder/decoder do not accept legacy opcodes.
• Disasm no longer prints legacy opcode names.
• cargo test passes.

Tests

• Add/adjust a unit test ensuring decoding an unknown/removed opcode produces the expected error.

---

PR-1.4 — Define the Minimal Core ISA Surface (Bytecode-Only)

Briefing

After deleting legacy opcodes, we must explicitly define the minimal ISA that remains. This PR establishes the canonical core ISA module boundary and documentation.

Target

• Introduce a “core ISA” definition that is small and stable.
• Provide clear docs for stack effects and operand encoding at a bytecode level.

Work items

• Create/reshape modules so the “core ISA” is clearly isolated (e.g., isa/core or similar).

• Add module docs describing:

  • Instruction encoding rules.
  • Stack-based evaluation model (bytecode-level).
  • Which instructions exist at this stage (no closures/coroutines yet unless already in the spec subset).

• Add a docs/bytecode/ISA_CORE.md (or equivalent) that is short but precise.

• Ensure the ISA definition is used by:

  • Encoder/decoder.
  • Disasm.
  • Verifier (later).

Acceptance checklist

• Minimal ISA is explicitly defined and documented.
• No legacy instructions remain.
• cargo test passes.

Tests

• Existing tests only.

---

PR-1.5 — Bytecode Module Pruning (Delete Unused/Experimental Modules)

Briefing

The bytecode crate should be minimal. Anything experimental, unused, or legacy should be removed to reduce mental load.

Target

• Delete unused bytecode modules.
• Keep only essential components for: encoding/decoding, layout, disasm, and data structures required by spec.

Work items

• Remove unused files/modules identified in PR-1.1 map.
• Update mod.rs trees and public exports.
• Ensure no downstream crate relies on removed exports; if they do, fix the downstream usage by deleting legacy use, not by keeping legacy APIs.

Acceptance checklist

• Unused modules are deleted and no longer referenced.
• Public API surface is smaller and cleaner.
• cargo test passes.

Tests

• Existing tests only.

---

PR-1.6 — Canonical Function Boundaries & FRAME_SYNC Placement (Bytecode Layout)

Briefing

GC and coroutine scheduling rely on deterministic safepoints. The bytecode layout must define canonical function boundaries and FRAME_SYNC semantics at the bytecode layer.

Target

• Enforce canonical function ranges and end labels.
• Ensure FRAME_SYNC placement rules are representable and checkable.

Work items

• Review current layout utilities and make them canonical for:

  • Computing function code_len.
  • Determining valid jump targets (instruction boundaries).
  • Determining function end boundary.

• Document FRAME_SYNC at the bytecode level:

  • What it signals.
  • Where it is required (as per updated specs).

• Update disasm to clearly display FRAME_SYNC.

Acceptance checklist

• Function boundaries are computed via a single canonical routine.
• FRAME_SYNC is clearly represented and documented.
• Existing verifier/layout tests (if any) are updated.
• cargo test passes.

Tests

• Add or update unit tests for layout boundary correctness (e.g., end-exclusive semantics).

---

PR-1.7 — Bytecode Roundtrip Tests (Encode/Decode/Disasm Sanity)

Briefing

Before touching VM behavior, we want confidence that the bytecode toolchain is coherent after the ISA reset.

Target

• Add roundtrip tests that validate:

  • Encode → decode preserves structure.
  • Disasm prints stable, readable output.

Work items

• Add a small set of “known-good” bytecode samples built using the new minimal ISA.

• Implement tests:

  • Encode then decode equals original structure.
  • Disasm output contains expected instruction names and operands.

• Keep samples intentionally tiny and deterministic.

Acceptance checklist

• Roundtrip tests exist and pass.
• Samples do not depend on legacy semantics.
• cargo test passes.

Tests

• New unit tests for encode/decode/disasm roundtrip.