Files
prometeu-runtime/docs/vm-arch/execution-allocation-qualification.md

63 lines
3.6 KiB
Markdown

# VM execution allocation qualification
Successful stack reads construct diagnostics only on failure. Return completion
validates the exact frame height and ordered signature groups before rotating the
current frame suffix right by its result width and truncating parameters and
locals. Void returns truncate directly. This preserves result order and owners
without a temporary result vector or Value clones.
Only the returning frame is removed. Caller locals and continuation remain intact.
Direct RET and branches to function end share completion while retaining their
existing instruction charges. The last-frame safepoint still runs after results
are rooted in the operand stack. If GC scratch admission fails, those roots remain
published and no sweep occurs.
## Measurement
On 2026-10-14, aarch64 macOS with rustc 1.98.1, the dedicated
`crates/console/prometeu-vm/tests/execution_allocations.rs` integration binary
measured the following native allocation/deallocation calls. Both debug and
release produced the same counts:
| Instruction loop | Iterations | Before alloc/free | After alloc/free |
| --- | ---: | ---: | ---: |
| CALL / PUSH_I64 / RET / POP / JMP | 1,000 | 3,000 / 3,000 | 0 / 0 |
| CALL / RET / JMP (void) | 1,000 | 0 / 0 | 0 / 0 |
| CALL / two PUSH_I64 / RET / two POP / JMP | 1,000 | 5,000 / 5,000 | 0 / 0 |
| PUSH_I64 / DUP / ADD / POP / JMP | 1,000 | 6,000 / 6,000 | 0 / 0 |
Run `cargo test -p prometeu-vm --test execution_allocations -- --nocapture`
and the same command with `--release` before `-p`.
The allocator wrapper enables counting only on the executing test thread after
ten warm-up iterations. It includes alloc, alloc_zeroed, dealloc and realloc
(realloc contributes to both counters). Fixture construction, image validation,
reporting and destruction occur outside the measured region. The fixtures do not
create GC pressure. Error diagnostics, deliberate guest allocations, collection
and dead-string reclamation are outside this zero-allocation claim. This is an
instruction-region qualification, not a gameplay throughput measurement.
## Semantic and resource evidence
VM regressions exercise direct, closure and trait calls, taken and untaken
function-end branches, captured strings, ordered mixed result groups, Arc pointer
identity and heap receiver identity. A 1,024-slot mixed return checks the published
result-width ceiling and caller-local preservation. Internal tests check height
and type refusal before mutation, last-root closure survival, GC scratch refusal
without partial sweep, and successful collection after scratch admission returns.
Lifecycle tests continue to check saved continuation and completion boundaries.
Actual storage remains quota-accounted. Removing the disposable return vector
removes its TemporaryBytes reservation; a valid scalar return can therefore
succeed with zero temporary capacity when no collection is needed. This does not
raise a ceiling, introduce an unmetered cache, or bypass the temporary memory
required by a triggered collector. Operand and call stack capacity accounting,
GC thresholds, verifier contracts and syscall ABI are unchanged.
The focused VM and transitive-root layer tests qualify these behaviors. Workspace
quality-gate status is tracked separately; these measurements do not establish
that all repository diagnostics or platform checks pass.
See the [memory and allocation contract](../specs/runtime/03-memory-stack-heap-and-allocation.md)
and the [materialization and copy-pressure lesson](../../discussion/lessons/DSC-0014-perf-vm-allocation-and-copy-pressure/LSN-0035-first-materialization-is-not-the-same-as-hot-path-copy-pressure.md).