prometeu-runtime/files/TODOs.md

PR-7.8 — Verifier Rules

Briefing

Verifier must enforce coroutine safety.

Target

Rules:

• YIELD forbidden inside invalid contexts (define minimal safe rule).
• SPAWN argument validation.
• SLEEP argument type validation.

Checklist

• Invalid YIELD rejected.
• SPAWN arg mismatch rejected.

Tests

• Invalid bytecode rejected.

Junie Rules

You MUST NOT weaken verifier.

---

PR-7.9 — Determinism & Stress Tests

Briefing

Validate deterministic behavior.

Target

Tests must confirm:

• Same order across runs.
• Sleep/wake order stable.
• GC works with many coroutines.

Checklist

• Deterministic order tests.
• Stress test 100+ coroutines.

Junie Rules

Tests must not depend on wall clock or randomness.

---

Final Definition of Done

• Cooperative coroutines implemented.
• Deterministic scheduling.
• No mailbox.
• GC and verifier fully integrated.
• All tests pass.

---

PR-8 — Tooling & Test Harness (JVM-Grade Discipline)

This phase establishes tooling and test discipline required to keep the Prometeu VM at JVM-grade quality.

Goals:

• Deterministic execution
• Reproducible tests
• Strong disassembler guarantees
• Layered test coverage
• Zero legacy artifacts enforcement

Each PR below is self-contained and must compile independently.

---

PR-8.1 — Disassembler (Roundtrip + Snapshot Reliability)

Briefing

The disassembler must be:

• Deterministic
• Complete
• Roundtrip-safe (encode → decode → encode)
• Snapshot-friendly

It must fully support:

• New opcodes (MAKE_CLOSURE, CALL_CLOSURE, SPAWN, YIELD, SLEEP)
• Updated syscall representation
• Closure and coroutine instructions

Target

1. Update disassembler to support all new opcodes.
2. Guarantee stable formatting.
3. Add roundtrip validation tests.

Formatting rules:

• No unstable ordering.
• No implicit formatting differences across platforms.
• Explicit numeric representation where required.

Acceptance Checklist

• All opcodes supported.
• Deterministic formatting.
• Roundtrip encode/decode test passes.
• Snapshot tests stable.

Tests

1. Encode → disasm → reassemble → byte-equal check.
2. Snapshot test for representative programs.
3. Closure/coroutine disasm coverage.

Junie Instructions

You MAY:

• Modify disassembler module.
• Add snapshot tests.

You MUST NOT:

• Change bytecode encoding format.
• Introduce formatting randomness.

If any opcode semantics unclear, STOP and ask.

---

PR-8.2 — Deterministic Execution Harness

Briefing

The VM must be testable deterministically.

Requirements:

• No wall-clock time.
• Controlled tick progression.
• Fixed seed where randomness exists (if any).

Target

Introduce a test harness wrapper:

• Controlled tick counter.
• Deterministic scheduler stepping.
• Explicit run_budget boundaries.

Provide utilities:

• run_until_halt()
• run_ticks(n)
• run_frames(n)

No external timing.

Acceptance Checklist

• No real-time dependencies.
• Deterministic coroutine wake order.
• Repeatable runs produce identical traces.

Tests

1. Same program run twice produces identical state traces.
2. Sleep/wake ordering stable.

Junie Instructions

You MAY:

• Extend test harness.
• Add deterministic trace utilities.

You MUST NOT:

• Introduce randomness.
• Use system time.

If current VM depends on real time, STOP and refactor before proceeding.

---

PR-8.3 — Layered Test Suite Architecture

Briefing

Tests must be structured by layer to isolate failures.

Layers:

1. Bytecode encode/decode
2. Verifier
3. VM execution
4. GC behavior
5. Scheduler behavior

Target

Organize tests into modules per layer.

Enforce:

• No cross-layer assumptions.
• Verifier tests do not execute VM.
• VM tests assume verified input.

Add minimal coverage per layer.

Acceptance Checklist

• Tests grouped logically.
• No duplicated logic.
• Clear separation of concerns.

Tests

Add representative tests per layer:

• Encode/decode edge cases.
• Verifier rejects invalid closures.
• VM executes valid programs.
• GC collects unreachable closures.
• Scheduler deterministic ordering.

Junie Instructions

You MAY:

• Refactor test layout.
• Add missing coverage.

You MUST NOT:

• Merge unrelated layers.
• Hide verifier failures inside runtime traps.

If a test spans layers, STOP and split appropriately.

---

PR-8.4 — No Legacy Artifacts Enforcement

Briefing

The codebase must not contain legacy RC/HIP artifacts.

Forbidden patterns:

• retain
• release
• hip
• gate
• borrow
• scope (legacy usage context)
• RC-related modules

Target

Implement automated check:

• Script or test that scans source tree for forbidden symbols.
• Fails CI if found.

Also:

• Remove dead modules/files.
• Remove unused features.

Acceptance Checklist

• Automated legacy scan exists.
• No legacy symbols present.
• Dead modules removed.

Tests

1. Intentionally insert forbidden symbol in test branch → test fails.
2. Scan passes on clean tree.

Junie Instructions

You MAY:

• Add static scan test.
• Remove dead code.

You MUST NOT:

• Suppress warnings instead of fixing code.
• Leave deprecated modules commented out.

If unsure whether a symbol is legacy or valid, STOP and ask.

---

Final Definition of Done

• Disassembler roundtrip-safe.
• Deterministic harness in place.
• Layered test suite established.
• No legacy artifacts remain.
• All tests reproducible and stable.

---

PR-9 — Final Hardening & Baseline Documentation

This phase finalizes the new Prometeu VM baseline after the architectural reset (GC, closures, coroutines, unified syscall ABI, deterministic scheduler).

Goals:

• Consolidated architecture documentation (short, precise, authoritative)
• Minimal and controlled public surface area
• Removal of temporary feature flags
• Final cleanup: dead code, warnings, outdated docs/examples

All PRs below are self-contained and must compile independently.

---

PR-9.1 — Consolidated Architecture Documentation

Briefing

The project must include a short, authoritative architecture document in English describing the new baseline.

It must reflect the current state only (no legacy, no transitional wording).

This document becomes the canonical reference for contributors.

Target

Create ARCHITECTURE.md at repository root with sections:

1. Overview

   • Stack-based VM
   • GC-managed heap (mark-sweep, non-compacting)
   • Closures (Model B, hidden arg0)
   • Cooperative coroutines (FRAME_SYNC safepoints)
   • Unified syscall ABI

2. Memory Model

   • Stack vs heap
   • Heap object kinds
   • GC roots (VM + suspended coroutines)

3. Execution Model

   • Interpreter loop
   • Safepoints
   • Scheduler behavior

4. Verification Model

   • Verifier responsibilities
   • Runtime vs verifier guarantees

5. Non-Goals

   • No RC
   • No HIP
   • No preemption
   • No mailbox

The document must be concise (no more than ~4–6 pages equivalent).

Acceptance Checklist

• ARCHITECTURE.md exists.
• No mention of RC/HIP.
• Reflects actual implementation.
• Reviewed for consistency with code.

Tests

Manual review required.

Junie Instructions

You MAY:

• Create new documentation files.

You MUST NOT:

• Invent features not implemented.
• Reference legacy behavior.

If architecture details are unclear, STOP and request clarification.

---

PR-9.2 — Public Surface Area Minimization

Briefing

The public API must be minimal and intentional.

Internal modules must not leak implementation details.

Target

1. Audit all pub items.
2. Reduce visibility to pub(crate) where possible.
3. Hide internal modules behind private boundaries.
4. Ensure only intended API is exported.

Focus areas:

• VM core
• Heap internals
• Scheduler internals
• GC internals

Acceptance Checklist

• No unnecessary pub items.
• Public API documented.
• Internal types hidden.
• cargo doc shows clean public surface.

Tests

• Build documentation.
• Ensure no accidental public modules remain.

Junie Instructions

You MAY:

• Restrict visibility.
• Refactor module structure.

You MUST NOT:

• Break existing internal usage.
• Expose new APIs casually.

If removing pub causes architectural issue, STOP and escalate.

---

PR-9.3 — Remove Temporary Feature Flags

Briefing

During refactor phases, temporary feature flags or conditional compilation may have been introduced.

These must not remain in the final baseline.

Target

1. Identify all feature flags related to transitional behavior.
2. Remove obsolete cfg gates.
3. Remove commented legacy branches.
4. Ensure single authoritative execution path.

Acceptance Checklist

• No transitional feature flags remain.
• No commented-out legacy logic.
• Single execution model.
• All tests pass.

Tests

• Full test suite passes without feature toggles.

Junie Instructions

You MAY:

• Remove obsolete flags.
• Simplify code paths.

You MUST NOT:

• Remove legitimate platform flags.
• Leave partial dead branches.

If unsure whether a flag is temporary or architectural, STOP and ask.

---

PR-9.4 — Final Cleanup & Quality Sweep

Briefing

This PR performs the final cleanup pass.

Goal: Zero warnings. No dead code. No outdated examples.

Target

1. Remove dead modules/files.
2. Remove unused imports and code.
3. Eliminate compiler warnings.
4. Update outdated examples.
5. Remove stale TODOs referencing removed architecture.

Optional (if present):

• Enforce cargo clippy clean baseline.
• Ensure rustfmt compliance.

Acceptance Checklist

• No dead code.
• Zero compiler warnings.
• Clippy clean (if configured).
• Examples reflect new baseline.
• No TODO referencing RC/HIP.

Tests

• Full test suite passes.
• Clean build with warnings denied (if configured).

Junie Instructions

You MAY:

• Remove unused code.
• Refactor minor clarity issues.

You MUST NOT:

• Introduce new features.
• Change runtime semantics.

If cleanup requires semantic change, STOP and split into new PR.

---

Final Definition of Done

• Architecture documented clearly.
• Public API minimal and controlled.
• No temporary flags remain.
• Codebase clean, warning-free, and aligned with the new VM baseline.