---
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`