implement PLN-0033 vm string sharing hot path

This commit is contained in:
2026-04-20 08:45:34 +01:00
parent 8c5957a0a9
commit 09821cf9cc
10 changed files with 359 additions and 17 deletions
@@ -0,0 +1,108 @@
---
id: PLN-0033
ticket: perf-vm-allocation-and-copy-pressure
title: Plan - VM Hot Path Ownership and String Copy Pressure
status: done
created: 2026-04-20
completed: 2026-04-20
tags: [perf, runtime, vm, memory, strings]
---
## Briefing
Implement the runtime-core portion of `DEC-0018` by reducing repeated string payload copies and hot-path allocation pressure without changing guest-visible semantics.
## Decisions de Origem
- `DEC-0018` - VM Allocation and Copy Pressure Baseline
## Alvo
Change the VM core so that hot paths over numeric values and already-materialized values converge toward zero allocation, while preserving the public semantics of string values and `GET_GLOBAL`.
## Escopo
### Included
- VM value representation and ownership audit for hot paths.
- `GET_GLOBAL` copy-pressure reduction without semantic drift.
- String-producing opcode hot-path changes, especially `ADD`.
- Unit and focused integration coverage for unchanged semantics.
### Excluded
- Public ABI changes.
- Certification or host-facing telemetry policy changes.
- Broad speculative string interning or copy-on-write rollout unless directly required by a concrete implementation step.
## Fora de Escopo
- Cartridge language changes.
- Host debugger protocol changes.
- General fault/log path rewrites beyond keeping them isolated from hot-path work.
## Plano de Execucao
### Step 1 - Audit current hot-path ownership
**What:** Identify the exact VM operations that still clone or allocate on already-materialized hot paths.
**How:** Review `Value`, `GET_GLOBAL`, `ADD`, related stack helpers, and any nearby string coercion paths; classify each site as unavoidable first materialization versus avoidable repeated copy.
**File(s):** `crates/console/prometeu-bytecode/src/value.rs`, `crates/console/prometeu-vm/src/virtual_machine.rs`
### Step 2 - Rework internal representation/ownership for expensive payloads
**What:** Introduce the smallest internal representation change needed to avoid repeated payload copies for expensive values.
**How:** Prefer internal ownership changes that preserve guest-visible semantics. If strings or other expensive payloads need to move behind handles or equivalent internal storage, keep the public value meaning unchanged and constrain the change to runtime-core internals.
**File(s):** `crates/console/prometeu-bytecode/src/value.rs`, `crates/console/prometeu-vm/src/heap.rs`, `crates/console/prometeu-vm/src/object.rs`, `crates/console/prometeu-vm/src/virtual_machine.rs`
### Step 3 - Fix `GET_GLOBAL` without semantic change
**What:** Remove avoidable repeated copy pressure from `GET_GLOBAL`.
**How:** Keep the observable contract identical while changing retrieval/storage internals so already-materialized expensive payloads are not recopied on each hot-path access.
**File(s):** `crates/console/prometeu-vm/src/virtual_machine.rs`
### Step 4 - Optimize string-producing opcode paths
**What:** Reduce repeated allocation/copy pressure in string-producing operations, starting with `ADD`.
**How:** Separate true new-string creation from repeated cloning of existing payloads. Ensure any operation that semantically creates a new string still does so correctly, while avoiding extra transient allocations around existing materialized values.
**File(s):** `crates/console/prometeu-vm/src/virtual_machine.rs`, related helper modules if introduced
### Step 5 - Preserve semantic coverage
**What:** Prove semantics did not change while ownership internals did.
**How:** Add/update tests for constants, dynamic strings, globals, arithmetic/string `ADD`, and edge cases where strings cross stack/global boundaries.
**File(s):** `crates/console/prometeu-vm/src/virtual_machine.rs`, VM test modules
## Criterios de Aceite
- `GET_GLOBAL` keeps its public semantics unchanged.
- Hot-path access to already-materialized expensive values no longer performs avoidable repeated payload copies.
- Numeric hot paths remain allocation-free.
- String operations that truly create a new string remain correct and deterministic.
- VM tests cover constant-pool strings, runtime-created strings, and globals under the new ownership model.
## Tests / Validacao
### Unit Tests
- Value/ownership tests for expensive payload movement or referencing.
- VM opcode tests for `GET_GLOBAL`, `SET_GLOBAL`, and string `ADD`.
### Integration Tests
- Small bytecode programs that read globals repeatedly and mix numeric/string paths.
### Manual Verification
- Review allocation-sensitive hotspots in the final implementation to confirm repeated copies were removed rather than merely relocated.
## Riscos
- Internal representation changes may ripple into GC/root traversal.
- A partial fix may hide copies in helper methods rather than eliminate them.
- Over-optimizing strings could accidentally change guest-visible behavior if semantic boundaries are not defended by tests.
## Dependencies
- `DEC-0018`
- Existing VM heap/object/root traversal contracts
@@ -0,0 +1,98 @@
---
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
@@ -0,0 +1,88 @@
---
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`