3.9 KiB
| id | ticket | title | status | created | completed | tags | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| PLN-0034 | perf-vm-allocation-and-copy-pressure | Plan - Internal Allocation Evidence and Hot Path Measurement | review | 2026-04-20 |
|
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