[PERF] VM Allocation and Copy Pressure
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-04-20 09:09:24 +01:00
parent 8937963819
commit cd6bf6b313
7 changed files with 71 additions and 531 deletions
@@ -1,123 +0,0 @@
---
id: AGD-0013
ticket: perf-vm-allocation-and-copy-pressure
title: Agenda - [PERF] VM Allocation and Copy Pressure
status: accepted
created: 2026-03-27
resolved: 2026-04-20
decision: DEC-0018
tags: []
---
# Agenda - [PERF] VM Allocation and Copy Pressure
## Problema
O core da VM ainda aloca e clona demais em alguns caminhos relevantes, especialmente quando strings entram no fluxo.
Hoje `ADD` com string usa `format!`/`to_string()`, `GET_GLOBAL` clona valores e varios caminhos de erro montam strings dinamicas.
## Dor
- churn de heap reduz o teto de throughput da VM.
- carts que abusam de string e estado global pagam custo cedo demais.
- hardware barato sente alocacao repetitiva de forma desproporcional.
## Hotspots Atuais
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L635)
- [virtual_machine.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-vm/src/virtual_machine.rs#L870)
- [tick.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs#L111)
## Alvo da Discussao
Definir o nivel de disciplina de alocacao/copia exigido do core da VM no baseline do console.
## O Que Precisa Ser Definido
1. Prioridade dos casos.
Fechar quais caminhos sao realmente hot:
- opcodes de string;
- acesso a globals;
- faults;
- logs.
2. Estrategia de ownership.
Decidir onde vale introduzir:
- borrow temporario;
- small-string strategy;
- copy-on-write;
- intern/cache de strings.
3. Meta de alocacao.
Definir se o projeto quer:
- zero alloc no frame loop feliz;
- alloc rara e explicita;
- apenas reducao oportunista.
4. Instrumentacao.
Decidir como medir alocacao sem transformar a VM em microbenchmark artificial.
## Open Questions de Arquitetura
1. Strings sao citizen de primeira classe no fantasy console ou recurso conveniente mas caro?
2. Vale endurecer a linguagem/ABI para reduzir alocacao implicitamente?
3. Caminhos de fault precisam ser maximizados para desempenho ou apenas os caminhos felizes?
## Sugestoes para Fechar as Open Questions
1. Strings devem ser tratadas como recurso suportado, mas caro por definicao no baseline.
A VM hoje modela `Value::String(String)` como valor inline clonavel e o opcode `ADD` concatena via `format!`, entao o custo de copia ja faz parte do comportamento real do runtime. A sugestao nao e prometer "string cheap" na semantica base, e sim preservar string como capacidade legitima da linguagem enquanto o baseline otimiza os caminhos quentes que nao dependem de formatacao dinamica. Strings hardcoded podem ser materializadas uma vez na constant pool durante build/load; strings dinamicas podem ser materializadas em storage dinamico durante runtime. Em ambos os casos, a primeira materializacao e aceitavel. O que esta fora da meta e recopiar payload de string repetidamente no caminho quente depois dessa primeira materializacao.
2. Vale endurecer o contrato operacional, mas nao a expressividade publica da linguagem neste primeiro passo.
A recomendacao e evitar uma mudanca ampla de ABI agora. Em vez disso:
- o caminho feliz do frame loop deve evitar alocacao implicita quando opera sobre numeros, handles e valores ja materializados;
- strings dinamicas devem continuar permitidas, mas tratadas como custo explicito de runtime;
- globals devem privilegiar handles e valores baratos no caminho quente, sem introduzir nova semantica publica para `GET_GLOBAL`;
- qualquer estrategia mais invasiva, como intern global, copy-on-write ou heap-string canonica, deve nascer como decisao posterior se a telemetria provar necessidade.
3. Fault paths nao precisam ser maximizados como se fossem caminho quente.
A recomendacao e exigir que traps e faults permanencam corretos, deterministas e legiveis para tooling host-owned, mas sem contaminar o caminho feliz com formatacao defensiva ou montagem rica de strings em toda instrucao. O investimento principal deve ir para opcode dispatch, acesso a globals e operacoes repetidas por frame; faults podem aceitar custo maior desde que esse custo seja pago so na excecao.
## Sugestao / Recomendacao
Fechar esta agenda com a seguinte linha:
- baseline alvo: "happy path com alloc rara e explicita", nao "zero alloc absoluto";
- prioridade imediata: reduzir copia/alocacao em `GET_GLOBAL` e nas operacoes de string mais frequentes do loop;
- strings constantes: custo de materializacao pago uma vez no carregamento/constant pool e depois preferencialmente referenciadas;
- strings dinamicas: custo inicial de criacao aceito em runtime, mas sem clones implicitos repetidos apos a primeira materializacao;
- `GET_GLOBAL`: nenhuma nova semantica publica; a reducao de copia deve vir de representacao interna e ownership dos tipos caros;
- ownership baseline: manter valores triviais por copia e mover payloads caros para representacoes por handle quando houver prova de pressao suficiente para justificar a complexidade;
- faults/logs: preservar clareza e determinismo, aceitando custo fora do caminho feliz;
- meta interna de engenharia: perseguir `zero alloc` no caminho feliz numerico e nos acessos quentes ja materializados, sem publicar isso como metrica de certificacao;
- instrumentacao canonica: medir `heap_used_bytes`, frequencia de GC e contagem de logs/faults no fim do frame, mantendo contadores de alocacao como metrica interna de engenharia, sem transformar o dispatch em microbenchmark intrusivo.
## Perguntas em Aberto
- Nenhuma no nivel arquitetural atual. A agenda pode ser encerrada quando esta direcao for promovida para decisao normativa.
## Dependencias
- `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`
## Criterio de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- caminho quente prioritario para desengordurar;
- meta minima de alocacao/copia da VM;
- estrategia de ownership para strings/values;
- instrumentacao canonica para medir regressao.
## Resolucao Proposta
- Strings continuam parte legitima da linguagem, mas sao tratadas como recurso potencialmente caro no baseline.
- Strings hardcoded podem pagar custo de materializacao uma vez no carregamento/constant pool.
- Strings dinamicas podem pagar custo inicial de criacao em runtime.
- A arquitetura deve evitar recopia de payload apos a primeira materializacao sempre que o caminho quente puder operar por referencia, handle ou ownership interno mais barato.
- `GET_GLOBAL` nao ganha nova semantica publica; qualquer reducao de copia deve vir de mudancas internas de representacao e processo.
- `Zero alloc no caminho feliz` e meta interna de engenharia do runtime, nao criterio publicado de certificacao.
- Faults e logs permanecem corretos e legiveis, mas nao dirigem a otimizacao principal.
@@ -1,112 +0,0 @@
---
id: DEC-0018
ticket: perf-vm-allocation-and-copy-pressure
title: Decision - [PERF] VM Allocation and Copy Pressure Baseline
status: in_progress
created: 2026-04-20
accepted: 2026-04-20
agenda: AGD-0013
plans: [PLN-0033, PLN-0034, PLN-0035]
tags: [perf, runtime, vm, memory, strings, allocation]
---
# Status
Accepted on 2026-04-20 and now in progress through linked implementation plans.
# Contexto
O core da VM ainda apresenta churn de alocacao e copia em caminhos relevantes, em especial:
- concatenacao de string em `ADD`;
- clone de valores em `GET_GLOBAL`;
- montagem de strings dinamicas em faults e logs.
O estado atual do runtime permite strings como parte legitima da linguagem, mas a representacao pratica ainda empurra payload caro para copias repetidas em alguns caminhos. A discussao da agenda fechou que o problema arquitetural nao e eliminar toda alocacao, e sim impedir recopia desnecessaria depois da primeira materializacao dos dados.
# Decisao
1. Strings SHALL remain part of the supported VM language surface.
2. The runtime MUST treat string payload as potentially expensive in the baseline performance model.
3. Hardcoded strings MAY pay one materialization cost during build/load into the constant pool, and runtime hot paths SHOULD preferentially reference that already-materialized representation.
4. Dynamically produced strings MAY pay an initial runtime materialization cost in dynamic storage, but the runtime MUST NOT introduce repeated implicit payload copies on hot paths unless the operation semantically requires a new string value.
5. `GET_GLOBAL` SHALL NOT gain new public semantics. Any reduction in copy pressure MUST come from internal representation, ownership strategy, or storage process, not from a guest-visible ABI change.
6. The baseline engineering target for the VM happy path SHALL be zero allocation on numeric and already-materialized hot paths.
7. That zero-allocation target SHALL remain an internal engineering objective and MUST NOT be published as a certification contract or guest-facing compatibility guarantee.
8. Fault and log paths MUST remain correct, deterministic, and readable, but they SHALL NOT drive the primary optimization strategy for the VM hot path.
# Rationale
Esta decisao fecha tres tensoes da agenda:
- preserva string como capacidade real da linguagem, sem prometer que string e "cheap" por definicao;
- evita reabrir a ABI publica apenas para aliviar pressao de copia em um ponto interno da VM;
- separa meta de engenharia de contrato normativo externo.
O custo inevitavel e a primeira materializacao:
- string hardcoded entra na constant pool em build/load;
- string dinamica nasce em runtime.
O custo evitavel e a recopia posterior do payload em caminhos quentes que ja deveriam operar sobre valor materializado, handle ou ownership mais barato.
Essa linha tambem mantem a arquitetura coerente com as specs atuais:
- valores triviais continuam baratos por copia;
- objetos com identidade e lifetime relevante continuam candidatos naturais a representacao por handle;
- tooling host-owned continua podendo observar heap e pressao de memoria sem que a VM precise transformar cada opcode em um ponto de instrumentacao intrusivo.
# Invariantes / Contrato
- The VM MUST preserve the public meaning of string values as guest-visible values.
- The VM MUST NOT change the public behavior of `GET_GLOBAL` as part of this decision.
- The runtime MUST distinguish first materialization from repeated implicit copy when evaluating optimization work.
- Constant-pool-backed strings SHOULD be treated as already materialized data for runtime access purposes.
- Runtime-created strings MAY allocate once at creation time.
- Hot-path operations over numeric values, handles, and already-materialized values SHOULD converge toward zero allocation.
- Any future move to heap-backed canonical strings, interning, copy-on-write, or similar global representation changes MUST be proposed in a separate decision if it changes operational constraints or implementation complexity materially.
- Fault generation and logs MAY allocate outside the happy path, provided they remain deterministic and do not leak into hot-loop design as a hidden steady-state cost.
# Impactos
- Spec
- No immediate guest-visible ABI change is required.
- Existing memory/value/debug specs remain directionally compatible.
- A follow-up plan may update wording in runtime specs to distinguish first materialization from repeated copy pressure more explicitly.
- Runtime
- Optimization work MUST target internal ownership and representation first.
- `GET_GLOBAL` copy pressure MUST be addressed without semantic drift.
- String-heavy `ADD` and similar paths become explicit hot-path optimization candidates.
- Host
- Certification and tooling remain host-owned.
- Allocation counters may exist as engineering telemetry, but they are not promoted to public certification criteria by this decision.
- Firmware / Tooling
- No cartridge author contract changes are introduced.
- Compiler/loader/tooling MAY continue to materialize hardcoded strings into constant-pool storage.
# Referencias
- `AGD-0013`
- `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`
- `crates/console/prometeu-vm/src/virtual_machine.rs`
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
# Propagacao Necessaria
- Create a plan that separates:
- hot-path ownership work in the VM core;
- telemetry/internal measurement work;
- any optional spec wording cleanup.
- Audit `GET_GLOBAL` and string-producing opcode paths under this contract.
- Define implementation evidence for "zero alloc on happy path" as internal profiling evidence rather than certification output.
- Do not reopen public ABI or language semantics during plan execution unless new evidence shows the current contract is insufficient.
# Revision Log
- 2026-04-20: Initial draft from AGD-0013.
- 2026-04-20: Accepted and linked to PLN-0033, PLN-0034, and PLN-0035.
@@ -1,108 +0,0 @@
---
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
@@ -1,98 +0,0 @@
---
id: PLN-0034
ticket: perf-vm-allocation-and-copy-pressure
title: Plan - Internal Allocation Evidence and Hot Path Measurement
status: done
created: 2026-04-20
completed: 2026-04-20
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
@@ -1,88 +0,0 @@
---
id: PLN-0035
ticket: perf-vm-allocation-and-copy-pressure
title: Plan - Runtime Spec Wording for Materialization vs Copy Pressure
status: done
created: 2026-04-20
completed: 2026-04-20
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`