prometeu-runtime/discussion/workflow/plans/PLN-0035-runtime-spec-wording-for-materialization-vs-copy-pressure.md

id	ticket	title	status	created	completed	tags
PLN-0035	perf-vm-allocation-and-copy-pressure	Plan - Runtime Spec Wording for Materialization vs Copy Pressure	done	2026-04-20	2026-04-20	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