prometeu-runtime/files/TODOs.md

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.