feat(vm)!: implement typed callables and single-context execution
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

Add structural Fn signatures, typed capture environments, indirect calls and Trait dispatch while preserving logical parameter and result groups, ownership and budgets.

Remove guest coroutine execution and legacy loading. Activate bounded sealed PBX v1 with mandatory capture metadata, preserve frame continuations and root return results, and migrate producers and shipped cartridges.

Publish coordinated specs, handoffs and the completed runtime lesson. Validation: 880 workspace tests passed, 9 existing tests ignored; both cartridges completed six production-host frames.
This commit is contained in:
2026-10-09 05:47:24 +01:00
parent 86bade3e1f
commit ec84a6bba5
96 changed files with 3656 additions and 6075 deletions
@@ -1,107 +1,36 @@
# Coroutines and Cooperative Scheduling
# Single Execution Context and Frame Continuation
Domain: VM coroutine model
Domain: VM execution lifecycle
Function: normative
This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.
VM directly owns one PC, operand stack, call stack and globals. Entry preparation
does not allocate a heap execution object. There are no guest coroutine instances,
ready/sleeping queues, sleeper clock or coroutine scheduling phase.
## 1 Coroutine Model
SPAWN/YIELD/SLEEP are retired; 0x54–0x56 remain reserved. Loading MUST reject them
before execution, including unreachable code. Assembler rejects their mnemonics;
diagnostic decoding can identify retired numbers. No compatibility mode exists.
Other instruction numbers are unchanged.
PROMETEU provides coroutines as the only guest-visible concurrency model.
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
is not a terminator, can occur in any body and resumes next PC. Host MUST NOT
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
preserve the same open frame without draw publication or extra callback budget.
Coroutines are:
Successful RET of the last root completes entry and leaves rooted results on VM
stack. Recurring host may prepare FunctionId 0 next logical frame, preserving
globals/init guard. Callee RET does not close a frame. Replacement preparation
validates/reserves before releasing owners. HALT/trap/reset/unload retain their
contracts.
- cooperative;
- deterministic;
- scheduled only at safepoints;
- never preemptive.
Threshold GC opportunities are sync and successful root RET after result rooting.
Preparation, ordinary callee RET and allocation failure add no opportunity. GC
advances no clock/frame, grants no budget and invokes no guest cleanup/callback.
Asset/render workers retain their independent protocols and run no guest code;
no physical-core affinity is implied.
There is:
- no parallel execution;
- no hidden threads;
- no scheduler behavior outside explicit machine rules.
## 2 Coroutine Lifecycle
Each coroutine can be in one of the following states:
- `Ready`
- `Running`
- `Sleeping`
- `Finished`
Coroutine-local execution state includes, conceptually:
```
Coroutine {
call_stack
operand_stack
state
}
```
## 3 Scheduling
At each eligible scheduling boundary:
1. the scheduler selects the next coroutine;
2. ordering remains deterministic;
3. execution continues within the frame-budget model.
Baseline policy:
- round-robin or equivalent deterministic ordering;
- no surprise priority inversion hidden from the model;
- no preemption between safepoints.
## 4 Coroutine Operations
Typical operations:
| Operation | Description |
| --------- | ----------------------------- |
| `spawn` | Create a coroutine |
| `yield` | Voluntarily suspend execution |
| `sleep` | Suspend for N frames |
`yield` and `sleep` only take effect at safepoints.
## 5 Interaction with the Frame Loop
Coroutine scheduling happens inside the frame model, not beside it.
Conceptually:
```
FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutine
Run VM
FRAME_SYNC
------------------------
```
This preserves:
- deterministic replay;
- explicit cost accounting;
- consistent host/runtime handoff.
## 6 Costs and Determinism
Coroutine management:
- consumes cycles;
- contributes to certification/cost reporting;
- remains part of the deterministic execution trace.
Nothing about scheduling is "free" or hidden.
## 7 Relationship to Other Specs
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the broader frame/event model.
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines coroutine-related instruction families.
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines coroutine-owned execution state in the memory model.
Persistent operations can advance through short steps in normal frame execution
and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols require
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
[events](09-events-and-concurrency.md) and
[memory](03-memory-stack-heap-and-allocation.md).