prometeu-runtime/files/TODOs.md

PR-2.2 — Simplify VM Execution Loop (Pure Stack Machine)

Briefing

The VM should operate as a simple stack-based interpreter with a clear fetch–decode–execute loop, without hidden side channels or legacy behaviors.

Target

• Normalize the VM main loop to a clean stack-machine structure.
• Remove any legacy control paths tied to HIP/RC behavior.

Work items

• Refactor the main interpreter loop to:

  • Fetch instruction at PC.
  • Decode opcode.
  • Execute operation on stack/frames.

• Remove any conditional logic that depends on HIP/RC state.

• Ensure PC advancement is canonical and centralized.

Acceptance checklist

• VM loop is structurally simple and readable.
• No HIP/RC conditionals remain.
• VM compiles and runs basic programs.
• cargo test passes.

Tests

• Existing tests only.

Junie instructions

You MAY:

• Refactor the interpreter loop for clarity.
• Remove legacy conditionals.

You MUST NOT:

• Change opcode semantics.
• Introduce GC, closures, or coroutines here.
• Redesign the instruction set.

If unclear:

• Ask before modifying control flow assumptions.

---

PR-2.3 — Normalize Value Model (Stack vs Heap References)

Briefing

The VM must use a clear value model: primitives and tuples on the stack, heap objects referenced through opaque handles. This PR prepares the VM for the GC-based heap.

Target

• Define a single Value representation that distinguishes:

  • Immediate primitives.
  • Heap references (opaque handles).

• Remove any gate-based or borrow-based value types.

Work items

• Review the Value or equivalent enum/struct.

• Remove variants related to gates, borrows, or HIP.

• Ensure only the following categories remain:

  • Primitives (int, bool, etc.).
  • Tuples or small aggregates.
  • Heap reference handle (placeholder for future GC objects).

• Update stack operations accordingly.

Acceptance checklist

• Value type has no HIP/gate-related variants.
• All stack operations compile with the new value model.
• No borrow/mutate semantics remain.
• cargo test passes.

Tests

• Existing tests only.

Junie instructions

You MAY:

• Simplify the Value enum/struct.
• Remove legacy variants and adjust matches.

You MUST NOT:

• Design the GC handle layout.
• Introduce new object systems.
• Change instruction semantics beyond type cleanup.

If unclear:

• Ask what the intended value shape should be.

---

PR-2.4 — Consolidate Trap and Error Surface

Briefing

With HIP removed, the runtime trap surface must be simplified and aligned with the new stack+heap model.

Target

• Define a minimal, coherent set of runtime traps.
• Remove traps that only existed for HIP/RC semantics.

Work items

• Audit the VM’s trap/error enums.

• Remove HIP/RC-related traps.

• Keep only traps that remain meaningful, such as:

  • Illegal instruction.
  • Stack underflow/overflow.
  • Invalid jump target.
  • Out-of-bounds memory access.

• Ensure trap handling paths are consistent and deterministic.

Acceptance checklist

• Trap enum contains only relevant traps.
• No HIP/RC trap names remain.
• VM compiles and tests pass.

Tests

• Adjust any tests expecting removed trap codes.

Junie instructions

You MAY:

• Delete unused trap variants.
• Refactor match statements accordingly.

You MUST NOT:

• Add new trap categories without approval.
• Change the meaning of existing non-legacy traps.

If unclear:

• Ask before modifying trap semantics.

---

PR-2.5 — Prepare Call Frame Structure for Closures and Coroutines

Briefing

Before introducing closures and coroutines, the call frame structure must be neutral and future-proof, without HIP-specific fields.

Target

• Simplify the call frame to a minimal, generic structure.
• Remove any HIP/borrow/gate-related fields.

Work items

• Review the call frame struct.

• Remove fields tied to scope frames, borrow state, or gates.

• Ensure the frame contains only:

  • Function identifier.
  • Program counter.
  • Base stack pointer.
  • Locals or register area (if applicable).

• Keep the structure simple and extensible.

Acceptance checklist

• Call frame struct has no HIP-related fields.
• VM call/return paths compile and work.
• cargo test passes.

Tests

• Existing call-related tests must still pass.

Junie instructions

You MAY:

• Remove unused fields from the frame.
• Refactor call/return code to match the new structure.

You MUST NOT:

• Introduce closure or coroutine logic yet.
• Redesign the call stack architecture.

If unclear:

• Ask before changing frame responsibilities.

---

PR-2.6 — Remove Dead Runtime Modules and Symbols

Briefing

After the VM reset, there will be leftover modules, helpers, or symbols that are no longer referenced. This PR performs a final cleanup pass.

Target

• Remove dead or unreachable runtime code.
• Ensure the VM crate has a minimal, clean surface.

Work items

• Use compiler warnings and search tools to find:

  • Unused modules.
  • Unused structs/enums/functions.
  • Legacy HIP/RC terminology.

• Remove dead code.

• Update module trees and public exports.

Acceptance checklist

• No dead modules remain.
• No HIP/RC terminology found in the VM crate.
• cargo test passes.

Tests

• Existing tests only.

Junie instructions

You MAY:

• Remove unused code and modules.
• Update mod.rs and exports.

You MUST NOT:

• Remove code that is still referenced.
• Replace deleted modules with new experimental ones.

If unclear:

• Ask before deleting anything that looks structurally important.