prometeu-runtime/files/TODOs.md

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.