89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
---
|
|
id: PLN-0035
|
|
ticket: perf-vm-allocation-and-copy-pressure
|
|
title: Plan - Runtime Spec Wording for Materialization vs Copy Pressure
|
|
status: review
|
|
created: 2026-04-20
|
|
completed:
|
|
tags: [spec, runtime, memory, strings, perf]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Apply the minimal spec wording cleanup implied by `DEC-0018` so published runtime docs distinguish first materialization cost from repeated hot-path copy pressure without changing the public ABI.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0018` - VM Allocation and Copy Pressure Baseline
|
|
|
|
## Alvo
|
|
|
|
Update canonical runtime specs so the published memory/value/debug model reflects the accepted architectural framing behind the implementation work.
|
|
|
|
## Escopo
|
|
|
|
### Included
|
|
|
|
- Wording updates in runtime specs for values, memory/allocation, and debug/profiling boundaries.
|
|
- Clarifications that zero-allocation on the happy path is an engineering target, not certification policy.
|
|
|
|
### Excluded
|
|
|
|
- Any new guest-visible ABI rules.
|
|
- Broad documentation rewrite unrelated to `DEC-0018`.
|
|
|
|
## Fora de Escopo
|
|
|
|
- Lessons material.
|
|
- Cartridge author migration guides.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Identify exact normative gaps
|
|
|
|
**What:** Locate wording that currently conflates all allocation cost with hot-path copy pressure or leaves the first-materialization distinction implicit.
|
|
**How:** Review the accepted decision against the current value, memory, and debug chapters and capture only the gaps required to keep docs aligned with implementation intent.
|
|
**File(s):** `docs/specs/runtime/02a-vm-values-and-calling-convention.md`, `docs/specs/runtime/03-memory-stack-heap-and-allocation.md`, `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
|
|
|
### Step 2 - Update normative text
|
|
|
|
**What:** Clarify constant-pool materialization, runtime materialization, and repeated-copy pressure boundaries.
|
|
**How:** Add concise normative wording that preserves the existing ABI while making clear that internal engineering may target zero allocation on happy paths without publishing that as certification policy.
|
|
**File(s):** `docs/specs/runtime/02a-vm-values-and-calling-convention.md`, `docs/specs/runtime/03-memory-stack-heap-and-allocation.md`, `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
|
|
|
### Step 3 - Cross-check consistency
|
|
|
|
**What:** Ensure the updated docs stay aligned with the accepted decision and with any implementation evidence introduced under linked plans.
|
|
**How:** Review terminology across the edited chapters and confirm no text implies a guest-visible ABI or certification promise that the decision explicitly rejected.
|
|
**File(s):** same as above
|
|
|
|
## Criterios de Aceite
|
|
|
|
- Runtime specs distinguish first materialization from repeated copy pressure.
|
|
- Specs do not imply a public ABI change for `GET_GLOBAL` or strings.
|
|
- Specs do not promote zero-allocation happy-path behavior to certification policy.
|
|
- Edited docs remain consistent across values, memory, and profiling chapters.
|
|
|
|
## Tests / Validacao
|
|
|
|
### Unit Tests
|
|
|
|
- Not applicable.
|
|
|
|
### Integration Tests
|
|
|
|
- Not applicable.
|
|
|
|
### Manual Verification
|
|
|
|
- Read the edited chapters side by side with `DEC-0018` and confirm that every new normative statement maps directly to the accepted decision.
|
|
|
|
## Riscos
|
|
|
|
- Specs may drift ahead of implementation details if wording is too specific.
|
|
- Overstating performance goals in normative docs may accidentally create an external compatibility promise.
|
|
|
|
## Dependencies
|
|
|
|
- `DEC-0018`
|