# PR-6.3 — CALL_CLOSURE (Model B Hidden Arg0)

## Briefing

Closures must be dynamically invokable.

Under Model B, invocation semantics are:

* The closure object itself becomes hidden `arg0`.
* User-supplied arguments become `arg1..argN`.
* Captures remain inside the closure and are accessed explicitly.

---

## Target

Introduce opcode:

`CALL_CLOSURE arg_count`

Stack before call:

```
[..., argN, ..., arg1, closure_ref]
```

Execution steps:

1. Pop `closure_ref`.
2. Validate object is `ObjectKind::Closure`.
3. Pop `arg_count` arguments.
4. Read `fn_id` from closure object.
5. Create new call frame:

  * Inject `closure_ref` as `arg0`.
  * Append user arguments as `arg1..argN`.
6. Jump to function entry.

No environment copying into locals.

---

## Work Items

1. Add `CALL_CLOSURE` opcode.
2. Implement dispatch logic.
3. Integrate with call frame creation.
4. Ensure stack discipline is preserved.

---

## Acceptance Checklist

* [ ] CALL_CLOSURE implemented.
* [ ] closure_ref validated.
* [ ] arg_count respected.
* [ ] Hidden arg0 injected correctly.
* [ ] Errors thrown on non-closure call.

---

## Tests

1. Closure returning constant.
2. Closure capturing value and using it.
3. Calling non-closure results in trap.
4. Nested closure calls work.

---

## Junie Instructions

You MAY:

* Modify interpreter call logic.
* Add tests.

You MUST NOT:

* Change stack model.
* Introduce coroutine semantics.
* Modify GC.

If function signature metadata is insufficient to validate arg_count, STOP and ask.

---

## Definition of Done

Closures can be dynamically invoked with hidden arg0 semantics.

---

# PR-6.4 — GC Traversal for Closures (Model B)

## Briefing

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

Under Model B, the closure object itself is passed at call time, but its environment remains stored in heap.

GC must traverse:

closure -> env -> inner HeapRefs

---

## Target

Extend GC mark phase to handle `ObjectKind::Closure`:

When marking a closure:

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

No compaction. No relocation.

---

## Work Items

1. Extend mark traversal switch.
2. Ensure safe iteration over env payload.
3. Add regression tests.

---

## Acceptance Checklist

* [ ] Closure env scanned.
* [ ] Nested closures retained.
* [ ] No regression in existing GC tests.

---

## Tests

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

---

## Junie Instructions

You MAY:

* Modify mark traversal.
* Add tests.

You MUST NOT:

* Modify sweep policy.
* Introduce compaction.

If unsure whether Value variants can embed HeapRef, STOP and ask.

---

## Definition of Done

GC correctly traverses closure environments under Model B semantics.

---

# PR-6.5 — Verifier Support for Closures (Model B)

## Briefing

The verifier must understand closure values and enforce safe invocation rules.

Under Model B:

* `CALL_CLOSURE` injects hidden `arg0`.
* User-visible arg_count excludes hidden arg.
* Captures are accessed via explicit instructions (future PR).

---

## Target

Extend verifier to:

1. Introduce stack type: `ClosureValue`.
2. Validate MAKE_CLOSURE effects.
3. Validate CALL_CLOSURE semantics:

  * Ensure top of stack is ClosureValue.
  * Ensure sufficient args present.
  * Validate `arg_count` matches function signature expectations.
  * Account for hidden arg0 when checking callee arg arity.
4. Validate ret_slots against function metadata.

---

## Work Items

1. Extend type lattice with ClosureValue.
2. Define stack transitions for MAKE_CLOSURE.
3. Define stack transitions for CALL_CLOSURE.
4. Enforce strict failure on mismatch.

---

## Acceptance Checklist

* [ ] ClosureValue type exists.
* [ ] Invalid CALL_CLOSURE rejected.
* [ ] Hidden arg0 accounted for.
* [ ] ret_slots validated.
* [ ] All verifier tests pass.

---

## Tests

1. Valid closure call passes verification.
2. CALL_CLOSURE with wrong arg_count fails.
3. CALL_CLOSURE on non-closure fails verification.
4. Nested closure calls verify correctly.

---

## Junie Instructions

You MAY:

* Extend verifier model.
* Add tests.

You MUST NOT:

* Weaken verification rules.
* Replace verifier checks with runtime-only traps.

If function metadata (arg_slots/ret_slots) is insufficient, STOP and request clarification.

---

## Definition of Done

Verifier fully supports closure creation and invocation under Model B semantics.