prometeu-runtime/files/TODOs.md

PR-4.6 — Verifier Error Model Consolidation

Briefing

Verifier errors must be deterministic, structured, and clearly separated from runtime traps.

Target

• Introduce a coherent verifier error model.

Work items

• Define a VerifierError enum covering:

  • Stack underflow.
  • Stack overflow.
  • Invalid jump target.
  • Invalid function boundary.
  • Return slot mismatch.

• Ensure verifier returns structured errors.

• Update tests to expect structured errors.

Acceptance checklist

• Verifier errors are structured and deterministic.
• No reliance on runtime traps for verifier failures.
• cargo test passes.

Tests

• Update existing tests to assert specific verifier errors.

Junie instructions

You MAY:

• Introduce a new verifier error enum.
• Refactor error returns.

You MUST NOT:

• Map verifier errors to runtime traps.
• Change runtime trap behavior.

If unclear:

• Ask before merging or renaming error categories.

---

PR-4.7 — Verifier Golden Test Suite

Briefing

We need a stable suite of valid and invalid bytecode samples to ensure verifier correctness over time.

Target

• Introduce golden tests for the verifier.

Work items

• Add a set of small bytecode samples:

  • Valid programs.
  • Invalid programs for each verifier error.

• Implement golden tests asserting:

  • Successful verification.
  • Specific error kinds for invalid programs.

Acceptance checklist

• Golden tests exist for all verifier error categories.
• Tests are deterministic.
• cargo test passes.

Tests

• New golden tests only.

Junie instructions

You MAY:

• Add deterministic golden tests.

You MUST NOT:

• Modify verifier logic to fit tests without understanding the cause.
• Introduce random or timing-based tests.

If unclear:

• Ask before changing test expectations.

---

PR-5.1 — Define Canonical Syscall Metadata Table

Briefing

Syscalls must follow a unified, function-like ABI based on slot counts and capabilities. This PR introduces the canonical metadata table describing every syscall.

Target

• Define a single authoritative metadata structure for syscalls.
• Ensure all syscalls are described in terms of slot-based ABI.

Work items

• Introduce a SyscallMeta struct containing:

  • Syscall identifier.
  • arg_slots.
  • ret_slots.
  • Capability flags.
  • Determinism flags (if defined in spec).

• Create a canonical syscall table/registry.

• Ensure all existing syscalls are registered in this table.

• Document the structure in code comments (English).

Acceptance checklist

• All syscalls have a SyscallMeta entry.
• Metadata includes arg and return slot counts.
• No syscall is invoked without metadata.
• cargo test passes.

Tests

• Add a test ensuring all registered syscalls have metadata.

Junie instructions

You MAY:

• Introduce a syscall metadata struct.
• Add a central registry for syscalls.

You MUST NOT:

• Change existing syscall semantics.
• Add new syscalls.

If unclear:

• Ask before defining metadata fields.

---

PR-5.2 — Implement Slot-Based Syscall Calling Convention

Briefing

Syscalls must behave like functions using the stack-based slot ABI. This PR implements the unified calling convention.

Target

• Ensure syscalls read arguments from the stack.
• Ensure syscalls push return values based on ret_slots.

Work items

• Modify the VM syscall dispatch logic to:

  • Look up SyscallMeta.
  • Pop arg_slots from the stack.
  • Invoke the syscall.
  • Push ret_slots results.

• Remove any legacy argument handling paths.

Acceptance checklist

• All syscalls use slot-based calling convention.
• Argument and return slot counts are enforced.
• No legacy calling paths remain.
• cargo test passes.

Tests

• Add tests:

  • Syscall with correct arg/ret slots → passes.
  • Syscall with insufficient args → trap or verifier failure.

Junie instructions

You MAY:

• Refactor syscall dispatch code.
• Use metadata to enforce slot counts.

You MUST NOT:

• Change the stack model.
• Add compatibility layers.

If unclear:

• Ask before modifying dispatch semantics.

---

PR-5.3 — Enforce Capability Checks in Syscall Dispatch

Briefing

Syscalls must be capability-gated. The runtime must verify that the current program has permission to invoke each syscall.

Target

• Enforce capability checks before syscall execution.

Work items

• Extend SyscallMeta with capability requirements.

• Add capability data to the VM or execution context.

• In syscall dispatch:

  • Check capabilities.
  • If missing, trigger TRAP_INVALID_SYSCALL or equivalent.

Acceptance checklist

• Capability checks occur before syscall execution.
• Missing capability leads to deterministic trap.
• Valid capabilities allow execution.
• cargo test passes.

Tests

• Add tests:

  • Syscall without capability → trap.
  • Syscall with capability → success.

Junie instructions

You MAY:

• Add capability checks in dispatch.
• Extend metadata with capability fields.

You MUST NOT:

• Change trap semantics.
• Introduce dynamic or nondeterministic permission systems.

If unclear:

• Ask before defining capability behavior.

---

PR-5.4 — Verifier Integration for Syscall Slot Rules

Briefing

The verifier must ensure that syscall calls respect argument and return slot counts before runtime.

Target

• Extend verifier to validate syscall usage.

Work items

• At syscall call sites:

  • Look up SyscallMeta.
  • Ensure enough argument slots are available.
  • Ensure stack shape after call matches ret_slots.

• Emit verifier errors for mismatches.

Acceptance checklist

• Verifier rejects incorrect syscall slot usage.
• Correct programs pass.
• Runtime traps are not required for verifier-detectable cases.
• cargo test passes.

Tests

• Add tests:

  • Too few args for syscall → verifier error.
  • Correct args/returns → passes.

Junie instructions

You MAY:

• Extend verifier with syscall checks.

You MUST NOT:

• Change runtime trap logic.
• Add new trap categories.

If unclear:

• Ask before enforcing slot rules.

---

PR-5.5 — Remove Legacy Syscall Entry Paths

Briefing

Any old or experimental syscall entry paths must be removed so that the slot-based ABI is the only supported mechanism.

Target

• Ensure only the new unified syscall dispatch path exists.

Work items

• Search for legacy or alternate syscall invocation logic.
• Remove or refactor them to use the canonical dispatch.
• Update modules and exports accordingly.

Acceptance checklist

• Only one syscall dispatch path remains.
• No legacy syscall logic is present.
• cargo test passes.

Tests

• Existing tests only.

Junie instructions

You MAY:

• Remove legacy syscall code paths.
• Refactor callers to use the unified dispatch.

You MUST NOT:

• Introduce new syscall semantics.
• Keep compatibility shims.

If unclear:

• Ask before deleting anything that looks externally visible.

---

PR-5.6 — Syscall Multi-Return Tests

Briefing

We must ensure multi-return syscalls behave correctly with the slot-based ABI.

Target

• Add deterministic tests covering multi-return behavior.

Work items

• Create or adapt at least one syscall with ret_slots > 1.

• Add tests:

  • Verify correct stack results after syscall.
  • Verify incorrect caller expectations fail verification.

Acceptance checklist

• Multi-return syscalls behave correctly.
• Verifier catches mismatches.
• cargo test passes.

Tests

• New multi-return syscall tests.

Junie instructions

You MAY:

• Add deterministic tests.
• Use existing syscalls or create a simple test-only syscall.

You MUST NOT:

• Modify syscall semantics to satisfy tests.
• Add nondeterministic behavior.

If unclear:

• Ask before introducing new test syscalls.