---
id: PLN-0034
ticket: perf-vm-allocation-and-copy-pressure
title: Plan - Internal Allocation Evidence and Hot Path Measurement
status: review
created: 2026-04-20
completed:
tags: [perf, runtime, telemetry, allocation, engineering]
---

## Briefing

Add internal engineering evidence for `DEC-0018` so the team can verify progress toward zero allocation on the happy path without turning that metric into a certification contract.

## Decisions de Origem

- `DEC-0018` - VM Allocation and Copy Pressure Baseline

## Alvo

Produce low-intrusion internal measurement for allocation and copy pressure that can guide implementation and regression detection during engineering work.

## Escopo

### Included

- Internal-only allocation counters or equivalent evidence mechanisms.
- Measurement points around VM execution slices and/or frame boundaries.
- Regression-oriented tests or harnesses that assert expected internal evidence in happy-path scenarios.

### Excluded

- New public certification outputs.
- Guest-visible profiling ABI changes.
- Heavy per-opcode instrumentation that distorts the hot path.

## Fora de Escopo

- Rewriting the full telemetry model.
- Publishing allocation counts to cartridge authors as normative behavior.

## Plano de Execucao

### Step 1 - Define internal evidence model

**What:** Choose the minimal evidence surface that proves whether happy-path execution allocates.
**How:** Prefer counters or snapshots that can distinguish first materialization from steady-state hot-path execution. Tie the evidence to engineering diagnostics only.
**File(s):** `crates/console/prometeu-hal/src/telemetry.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`, internal runtime/telemetry helpers as needed

### Step 2 - Implement low-intrusion collection

**What:** Add instrumentation with bounded overhead.
**How:** Record allocation evidence at frame or execution-slice boundaries rather than on every operation when possible. Keep the instrumentation isolated from guest-visible contracts.
**File(s):** `crates/console/prometeu-vm/src/heap.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`, related telemetry modules

### Step 3 - Define regression scenarios

**What:** Create deterministic scenarios that express the engineering target.
**How:** Add tests or bench-like checks for numeric happy paths, already-materialized constant strings, and runtime-created string paths after first materialization.
**File(s):** runtime/VM test modules; dedicated internal telemetry tests if appropriate

### Step 4 - Document how evidence is used

**What:** Clarify that this evidence is an engineering metric, not certification policy.
**How:** Update inline docs or internal notes near the measurement code so future work does not accidentally publish the metric as a hard contract.
**File(s):** relevant telemetry/runtime modules

## Criterios de Aceite

- Engineers can observe whether selected happy-path scenarios allocate.
- The measurement surface distinguishes internal engineering evidence from public certification output.
- Instrumentation overhead stays bounded and does not require intrusive per-opcode tracing.
- Regression checks exist for at least one numeric path and one already-materialized string path.

## Tests / Validacao

### Unit Tests

- Counter/reset/snapshot correctness for internal allocation evidence.

### Integration Tests

- Runtime scenarios that verify zero-allocation expectations on steady-state happy paths.

### Manual Verification

- Inspect final measurement plumbing to confirm it is not exposed as public certification policy.

## Riscos

- Instrumentation may accidentally become hot-path overhead.
- Counters may undercount or overcount if first materialization is not separated from steady-state execution.
- Internal metrics may be misread later as external compatibility guarantees unless explicitly documented.

## Dependencies

- `DEC-0018`
- Existing runtime telemetry boundary