prometeu-runtime/files/TODOs.md

PR-6.2 — Closure Capture Materialization

Briefing

Closures must capture values from the current stack frame into a heap-allocated environment.

This PR defines:

• How captured values are materialized.
• How the environment layout is constructed.

No CALL_CLOSURE yet.

---

Target

Define bytecode semantics for closure creation:

Introduce instruction (placeholder name):

MAKE_CLOSURE fn_id, capture_count

Semantics:

• Pop capture_count values from stack (top-first).
• Allocate closure object with those values stored in-order.
• Push resulting HeapRef to stack.

---

Work Items

1. Define new opcode MAKE_CLOSURE.
2. Implement stack semantics.
3. Ensure captured values are copied (not borrowed).
4. Update interpreter to support opcode.

---

Acceptance Checklist

• MAKE_CLOSURE opcode exists.
• Stack pops correct number of values.
• Closure allocated correctly.
• Closure ref pushed to stack.

---

Tests

1. Create closure capturing 0 values.
2. Create closure capturing 2 values.
3. Validate env order correctness.

---

Junie Instructions

You MAY:

• Add opcode.
• Modify interpreter dispatch.
• Add tests.

You MUST NOT:

• Implement CALL_CLOSURE yet.
• Modify GC behavior.
• Change verifier in this PR.

If capture order semantics unclear, STOP and ask.

---

Definition of Done

Closures can be created with captured environment and exist as heap values.

---

PR-6.3 — CALL_CLOSURE Instruction

Briefing

Closures must be invokable at runtime. This PR introduces dynamic invocation semantics for closures.

---

Target

Introduce opcode:

CALL_CLOSURE arg_count

Semantics:

• Stack layout before call:

  [... args..., closure_ref]
  

• Pop closure_ref.

• Validate it is ObjectKind::Closure.

• Pop arg_count arguments.

• Create new call frame:

  • Locals initialized with captured env first (design choice below).
  • Arguments appended after captures.

• Jump to function entry (fn_id).

---

Work Items

1. Add CALL_CLOSURE opcode.
2. Validate closure_ref type.
3. Integrate into call frame creation logic.
4. Respect function signature for ret_slots.

---

Acceptance Checklist

• CALL_CLOSURE implemented.
• Correct stack consumption.
• Correct frame initialization.
• Error on non-closure value.

---

Tests

1. Simple closure returning constant.
2. Closure capturing value and using it.
3. Error when calling non-closure.

---

Junie Instructions

You MAY:

• Add opcode and dispatch.
• Modify call frame initialization.
• Add tests.

You MUST NOT:

• Redesign stack model.
• Introduce coroutine behavior here.
• Change GC.

If frame layout decision is ambiguous, STOP and ask before choosing ordering.

---

Definition of Done

Closures can be invoked dynamically and execute correctly.

---

PR-6.4 — GC Traversal for Closures

Briefing

Closures introduce heap-to-heap references through their captured environments.

The GC must traverse:

closure -> env -> inner HeapRefs

This PR updates the GC mark phase to correctly traverse closure environments.

---

Target

Extend GC mark logic:

• When encountering ObjectKind::Closure:

  • Iterate over env values.
  • If a value contains HeapRef → mark referenced object.

---

Work Items

1. Update mark traversal switch for Closure.
2. Ensure no panics on malformed env.
3. Add tests for nested closure references.

---

Acceptance Checklist

• GC marks env HeapRefs.
• No regression in existing GC tests.
• Nested closures retained correctly.

---

Tests

1. Closure capturing another closure.
2. Closure capturing heap object.
3. Unreferenced closure collected.

---

Junie Instructions

You MAY:

• Modify mark traversal.
• Add GC tests.

You MUST NOT:

• Implement compaction.
• Change sweep policy.

If unsure whether env values may contain non-heap values, ask before assuming.

---

Definition of Done

GC correctly traverses closure environments.

---

PR-6.5 — Verifier Support for Closures

Briefing

The verifier must understand closure values as a distinct type and validate dynamic calls safely.

Closures are heap objects but semantically represent callable values.

---

Target

Extend verifier to:

• Introduce a stack type: ClosureValue.
• Validate MAKE_CLOSURE stack effects.
• Validate CALL_CLOSURE argument counts.
• Validate ret_slots against function signature.

---

Work Items

1. Add closure type to verifier type lattice.
2. Define stack transitions for MAKE_CLOSURE.
3. Define stack transitions for CALL_CLOSURE.
4. Ensure deterministic failure on misuse.

---

Acceptance Checklist

• Verifier understands closure values.
• Invalid CALL_CLOSURE rejected.
• ret_slots validated.
• All tests pass.

---

Tests

1. Valid closure call passes verification.
2. CALL_CLOSURE with wrong arg count fails.
3. CALL_CLOSURE on non-closure fails.

---

Junie Instructions

You MAY:

• Extend verifier type model.
• Add tests.

You MUST NOT:

• Weaken verification rules.
• Introduce runtime-only checks instead of verifier checks.

If closure typing conflicts with current stack model, STOP and ask.

---

Definition of Done

Verifier fully supports closure creation and invocation.

---