99 lines
3.9 KiB
Markdown
99 lines
3.9 KiB
Markdown
---
|
|
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
|