add agendas and decisions
This commit is contained in:
parent
2e640a14ae
commit
f4073858b1
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,6 +1,6 @@
|
||||
# 18.0. Backend VM Pipeline - Orchestration Agenda
|
||||
|
||||
Status: Active (Draft)
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -12,7 +12,7 @@ Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
|
||||
## Context
|
||||
|
||||
- O pipeline já prevê `LowerToVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios.
|
||||
- O pipeline já prevê `LowerToIRVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios.
|
||||
- O runtime já impõe contratos concretos de loader/verifier/VM que precisam ser respeitados pelo backend.
|
||||
- Nesta rodada, `packer` está explicitamente fora de escopo.
|
||||
|
||||
@ -28,12 +28,72 @@ Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToVM`?
|
||||
1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToIRVM`?
|
||||
2. Quais invariantes são obrigatórias na fronteira `IRBackend` para evitar ambiguidade no backend?
|
||||
3. Quais invariantes são obrigatórias na fronteira `IRVM` para emissão determinística?
|
||||
4. Quais verificações devem ocorrer no compilador antes de delegar ao loader/verifier do runtime?
|
||||
5. Como organizar testes de integração sem introduzir dependência de packer?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes para fechamento da Agenda 18.
|
||||
|
||||
As agendas `18.1`, `18.2` e `18.3` definem os contratos de entrada, lowering e marshaling.
|
||||
|
||||
Esta agenda fecha a orquestracao end-to-end com pipeline canônico incluindo etapa de otimizacao de `IRVM`.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Pipeline canônico do backend executável
|
||||
|
||||
O pipeline normativo v1 do backend executavel MUST seguir esta ordem:
|
||||
|
||||
1. `FrontendPhase` produz `IRBackend`;
|
||||
2. `LowerToIRVM` produz `IRVM`;
|
||||
3. `OptimizeIRVM` transforma `IRVM -> IRVM` otimizado;
|
||||
4. `EmitBytecode` transforma `IRVM` otimizado em `BytecodeModule` pre-load;
|
||||
5. runtime loader aplica patching/resolucao (`HOSTCALL -> SYSCALL`) e verifier valida imagem final.
|
||||
|
||||
### 2) Posicionamento de otimização
|
||||
|
||||
1. A etapa `OptimizeIRVM` MUST ocorrer entre `LowerToIRVM` e `EmitBytecode`.
|
||||
2. Otimizacao semantica/estrutural MUST ocorrer no backend (compile-time), nao no runtime.
|
||||
3. Runtime permanece focado em load, validacao e execucao deterministica.
|
||||
|
||||
### 3) Contratos de entrada e saida por etapa
|
||||
|
||||
1. `LowerToIRVM` recebe `IRBackend` conforme Agenda `18.1` e MUST produzir `IRVM` conforme Agenda `18.2`.
|
||||
2. `OptimizeIRVM` recebe `IRVM` valido para o `vm_profile` alvo e MUST produzir `IRVM` equivalente semanticamente.
|
||||
3. `EmitBytecode` recebe `IRVM` (pos-otimizacao) sem opcodes internos nao-eliminados e MUST emitir artefato conforme Agenda `18.3`.
|
||||
|
||||
### 4) Invariantes de seguranca da etapa OptimizeIRVM
|
||||
|
||||
`OptimizeIRVM` MUST:
|
||||
|
||||
1. preservar semantica observavel do programa;
|
||||
2. preservar contratos de aridade/slots/retorno;
|
||||
3. preservar determinismo para mesmo grafo de entrada;
|
||||
4. nao introduzir opcodes fora do `vm_profile` executavel;
|
||||
5. nao mover chamadas host/intrinsic para fronteira semantica incorreta.
|
||||
|
||||
### 5) Criterio de aprovacao de pipeline
|
||||
|
||||
Um backend so pode declarar fluxo "integration-ready" quando:
|
||||
|
||||
1. `IRBackend -> IRVM -> IRVM otimizado -> BytecodeModule` estiver implementado;
|
||||
2. fixtures Gate I cobrirem cenarios positivos e negativos definidos em `18.3`;
|
||||
3. bytecode emitido inicializar e executar no runtime alvo sem packer.
|
||||
|
||||
### 6) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo:
|
||||
|
||||
1. formato final de packer/cartucho;
|
||||
2. politicas avancadas de otimizacao nao necessarias para conformidade v1;
|
||||
3. redesign de loader/verifier/runtime.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec de contrato `IRBackend -> IRVM` (backend-facing).
|
||||
@ -50,7 +110,8 @@ Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
@ -58,4 +119,3 @@ Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 18.1. Backend Workshop 1 - IRBackend Input Contract
|
||||
|
||||
Status: Active (Draft)
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -42,6 +42,96 @@ Fechar o `IRBackend` como contrato de entrada do backend executável, de forma s
|
||||
5. Quais invariantes de estabilidade de ordenação são obrigatórias para conformance?
|
||||
6. Quais campos mínimos de span/source mapping são mandatórios para erros backend-atribuíveis?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes para fechar o contrato de entrada `IRBackend` v1.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. `IRBackend` e o contrato de entrada normativo do backend executavel.
|
||||
2. O frontend MUST emitir `IRBackend` completo para toda unidade admitida no Gate U.
|
||||
3. O backend MUST tratar `IRBackend` como fonte de verdade para `IRBackend -> IRVM`.
|
||||
4. Esta agenda NAO define o formato de `IRVM` nem o encoding final de bytecode.
|
||||
|
||||
### 2) Obrigacoes minimas por callable
|
||||
|
||||
Para cada callable executavel emitido no `IRBackend`, o frontend MUST preservar:
|
||||
|
||||
1. identidade estavel do callable no build atual;
|
||||
2. assinatura observavel:
|
||||
- aridade de entrada;
|
||||
- shape de retorno observavel;
|
||||
3. categoria de callable (ex.: funcao comum vs superficie reservada nao executavel);
|
||||
4. ancora de atribuicao de fonte (`fileId`, `start`, `end`);
|
||||
5. corpo backend-lowerable com semantica suficiente para emissao de chamadas e fluxo.
|
||||
|
||||
`IRFunction` apenas com nome/contagem de parametros/span NAO satisfaz este contrato executavel.
|
||||
|
||||
### 3) Classificacao obrigatoria de callsites
|
||||
|
||||
Todo callsite executavel no `IRBackend` MUST estar classificado em exatamente uma categoria:
|
||||
|
||||
1. `CALL_FUNC` (chamada de callable de programa);
|
||||
2. `CALL_HOST` (fronteira host-backed);
|
||||
3. `CALL_INTRINSIC` (operacao VM-owned).
|
||||
|
||||
Implementacoes MUST NOT inferir a categoria por heuristica textual na fase `LowerToIRVM`.
|
||||
|
||||
### 4) Contrato para host-backed
|
||||
|
||||
Todo `CALL_HOST` MUST carregar identidade canonica:
|
||||
|
||||
1. `abiModule`,
|
||||
2. `abiMethod`,
|
||||
3. `abiVersion`.
|
||||
|
||||
Todo `CALL_HOST` MUST carregar declaracao de ABI:
|
||||
|
||||
1. `arg_slots`,
|
||||
2. `ret_slots`.
|
||||
|
||||
O conjunto de bindings host-backed no `IRBackend` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia deterministica.
|
||||
|
||||
### 5) Contrato para VM-owned intrinsics e builtins
|
||||
|
||||
Todo `CALL_INTRINSIC` MUST carregar identidade canonica VM-owned:
|
||||
|
||||
1. `canonicalName`,
|
||||
2. `canonicalVersion`.
|
||||
|
||||
Builtin projections, builtin constants e intrinsic callsites VM-owned MUST NOT ser modelados como host binding.
|
||||
|
||||
### 6) Metadados reservados obrigatorios
|
||||
|
||||
`IRReservedMetadata` MUST preservar, no minimo:
|
||||
|
||||
1. host bindings canonicos admitidos;
|
||||
2. builtin type surfaces relevantes para lowering;
|
||||
3. builtin const surfaces relevantes para lowering;
|
||||
4. `requiredCapabilities` deterministico para assistencia de pipeline/packer.
|
||||
|
||||
`requiredCapabilities` MUST ser deterministico para o mesmo grafo de entrada admitido.
|
||||
|
||||
### 7) Diagnosticos e rejeicao deterministica
|
||||
|
||||
Quando um modulo/callable nao satisfaz o contrato de entrada executavel:
|
||||
|
||||
1. a rejeicao MUST ser deterministica;
|
||||
2. o diagnostico MUST manter atribuicao de fonte acionavel;
|
||||
3. o frontend/backend MUST NOT degradar silenciosamente para comportamento executavel diferente.
|
||||
|
||||
### 8) Deferrals explicitos
|
||||
|
||||
Ficam deferidos para agendas seguintes:
|
||||
|
||||
1. shape estrutural completo de `IRVM` e algoritmo de lowering (Agenda 18.2);
|
||||
2. layout/encoding final de `BytecodeModule` e marshaling PBX (Agenda 18.3);
|
||||
3. estrategia de otimizacao de backend.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/pbs/specs/13. Lowering IRBackend Specification.md` com adendo backend-facing.
|
||||
@ -65,4 +155,3 @@ Fechar o `IRBackend` como contrato de entrada do backend executável, de forma s
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `../runtime/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 18.2. Backend Workshop 2 - LowerToVM and IRVM Contract
|
||||
# 18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract
|
||||
|
||||
Status: Active (Draft)
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -42,12 +42,109 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB
|
||||
5. Como representar efeitos de stack no `IRVM` para detectar underflow/mismatch antes de emitir bytes?
|
||||
6. Como versionar `IRVM` em relação à linha de ISA do runtime selecionada?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes nesta agenda.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. Esta agenda define o contrato intermediario `IRVM` e as regras obrigatorias de lowering `IRBackend -> IRVM`.
|
||||
2. O objetivo do `IRVM` v1 e permitir emissao mecanica e deterministica de bytecode para runtime `core-v1`.
|
||||
3. Esta agenda NAO define o marshaling binario final `IRVM -> BytecodeModule` (Agenda 18.3).
|
||||
|
||||
### 2) Modelo de IRVM (quase-ISA estendido)
|
||||
|
||||
1. `IRVM` v1 adota modelo quase-ISA:
|
||||
- opcodes da Core ISA alvo;
|
||||
- e opcodes internos estendidos (`IRVM_EXT`) quando necessarios para normalizacao/otimizacao.
|
||||
2. `IRVM_EXT` MUST ser interno ao compilador e MUST NOT aparecer no artefato executavel final.
|
||||
3. Todo opcode `IRVM_EXT` MUST declarar metadados estruturais equivalentes a spec de opcode:
|
||||
- `pops`,
|
||||
- `pushes`,
|
||||
- `is_branch`,
|
||||
- `is_terminator`.
|
||||
4. O backend MUST expandir/reduzir todo `IRVM_EXT` para Core ISA antes da fase de emissao de bytecode.
|
||||
|
||||
### 3) Controle de fluxo e labels
|
||||
|
||||
1. O `IRVM` pode usar labels simbolicos internamente.
|
||||
2. A resolucao final de labels para immediates `u32` de salto MUST ocorrer no `LowerToIRVM`.
|
||||
3. O target final de salto MUST seguir contrato da VM:
|
||||
- offset relativo ao inicio da funcao (`func_start + target_rel` em runtime).
|
||||
4. Todo salto MUST apontar para fronteira valida de instrucao da funcao alvo.
|
||||
5. Caminho alcancavel que cai no fim da funcao sem terminador MUST ser erro de compilacao.
|
||||
|
||||
### 4) IDs deterministas de funcao
|
||||
|
||||
1. O backend MUST produzir `func_id` deterministico para `CALL`, `SPAWN` e `MAKE_CLOSURE`.
|
||||
2. Regra v1:
|
||||
- entrypoint executavel no indice `0`;
|
||||
- demais callables por ordenacao deterministica `(module_key, callable_name, source_start)`.
|
||||
3. O mesmo grafo de entrada admitido MUST produzir os mesmos `func_id`.
|
||||
|
||||
### 5) Contrato de chamadas
|
||||
|
||||
1. `CALL` MUST referenciar `func_id` valido.
|
||||
2. `SPAWN` MUST respeitar aridade exata da funcao de destino.
|
||||
3. `CALL_HOST` no `IRBackend` MUST lower para `HOSTCALL <sysc_index>` em `IRVM` pre-load.
|
||||
4. `CALL_INTRINSIC` no `IRBackend` MUST lower para `INTRINSIC <id_final>` em `IRVM`.
|
||||
5. `CALL_CLOSURE` com callee nao determinavel estaticamente e proibido no v1.
|
||||
|
||||
### 6) Contrato de slots por funcao
|
||||
|
||||
Para cada funcao em `IRVM`, o backend MUST fixar:
|
||||
|
||||
1. `param_slots`,
|
||||
2. `local_slots`,
|
||||
3. `return_slots`,
|
||||
4. `max_stack_slots`.
|
||||
|
||||
`RET` MUST ser consistente com `return_slots` em todos os caminhos alcancaveis.
|
||||
|
||||
### 7) Pre-verificacao obrigatoria no compilador
|
||||
|
||||
Antes de emitir bytecode, o compilador MUST executar pre-verificacao estrutural em `IRVM` (ja em Core ISA, sem `IRVM_EXT`), cobrindo no minimo:
|
||||
|
||||
1. validade de target de saltos;
|
||||
2. coerencia de altura de stack em joins;
|
||||
3. ausencia de underflow e overflow contra `max_stack_slots`;
|
||||
4. consistencia de `RET` com `return_slots`;
|
||||
5. validade de `func_id` referenciado;
|
||||
6. validade de aridade em `CALL`/`SPAWN`/`CALL_CLOSURE`;
|
||||
7. regra de `YIELD` com stack vazia;
|
||||
8. validade estrutural de `HOSTCALL`/`INTRINSIC` no shape de IR.
|
||||
|
||||
O verificador do runtime permanece autoritativo e continua obrigatorio.
|
||||
|
||||
### 8) Regra de YIELD
|
||||
|
||||
`YIELD` com stack nao vazia MUST ser rejeitado no compilador como erro deterministico de lowering/verificacao.
|
||||
|
||||
### 9) Versionamento do IRVM
|
||||
|
||||
1. `IRVM` MUST carregar `vm_profile` explicito.
|
||||
2. Para v1, o perfil normativo e `core-v1`.
|
||||
3. Mismatch entre `vm_profile` e alvo de emissao/verificacao MUST falhar de forma deterministica.
|
||||
|
||||
### 10) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo por fronteira de agenda:
|
||||
|
||||
1. formato binario final de `BytecodeModule` e seccionamento PBX (Agenda 18.3);
|
||||
2. politicas avancadas de otimizacao nao necessarias para conformidade v1.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec: `IRBackend -> IRVM` lowering contract.
|
||||
2. Nova spec: `IRVM` model e invariantes.
|
||||
3. Tabela de mapeamento `IRVM op -> ISA op` por linha de runtime suportada.
|
||||
4. Critérios de testes unitários do `LowerToVMPipelineStage`.
|
||||
4. Critérios de testes unitários do `LowerToIRVMPipelineStage`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
@ -58,7 +155,7 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java`
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/docs/runtime/specs/02-vm-instruction-set.md`
|
||||
- `../runtime/docs/runtime/specs/02a-vm-values-and-calling-convention.md`
|
||||
@ -66,4 +163,3 @@ Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRB
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/opcode_spec.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/decoder.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance
|
||||
|
||||
Status: Active (Draft)
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -44,6 +44,132 @@ Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformida
|
||||
5. Como padronizar mensagens/erros de marshaling para manter diagnóstico determinístico?
|
||||
6. Qual suíte mínima de integração prova “bytecode emitido roda no runtime” sem packer?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes nesta agenda.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. Esta agenda define o contrato normativo de marshaling `IRVM -> BytecodeModule` para runtime `core-v1`.
|
||||
2. O backend executavel MUST produzir artefato pre-load compativel com loader e verifier do runtime.
|
||||
3. Esta agenda nao define packer/cart assembly.
|
||||
|
||||
### 2) Direcao JVM-inspired (adaptada)
|
||||
|
||||
1. O backend adota modelo de referencia simbolica interna antes de indice numerico final:
|
||||
- referencias simbolicas existem em `IRVM` e no emitter interno;
|
||||
- indices finais (`func_id`, `sysc_index`, `intrinsic_id`) sao materializados de forma deterministica no marshaling.
|
||||
2. O runtime continua numeric-only na execucao final.
|
||||
|
||||
### 3) Contrato do BytecodeModule emitido
|
||||
|
||||
O emitter MUST preencher:
|
||||
|
||||
1. `const_pool`,
|
||||
2. `functions`,
|
||||
3. `code`,
|
||||
4. `exports`,
|
||||
5. `syscalls`,
|
||||
6. `debug_info` conforme regra minima desta agenda.
|
||||
|
||||
O emitter MUST gerar secao `SYSC` sempre presente (inclusive vazia), conforme contrato do loader.
|
||||
|
||||
### 4) Politica de ordenacao e IDs
|
||||
|
||||
1. A ordem de funcoes no artefato MUST seguir regra deterministica v1:
|
||||
- entrypoint no indice `0`;
|
||||
- demais funcoes por `(module_key, callable_name, source_start)`.
|
||||
2. O mesmo grafo de entrada admitido MUST produzir os mesmos indices e offsets.
|
||||
3. `SYSC` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia.
|
||||
|
||||
### 5) Layout de codigo por funcao
|
||||
|
||||
1. O emitter SHOULD construir codigo por funcao (modelo method-local) e flatten apenas no passo final.
|
||||
2. No artefato final:
|
||||
- `code_offset` MUST ser crescente e unico por funcao;
|
||||
- `code_len` MUST refletir exatamente o trecho da funcao;
|
||||
- `code_offset + code_len` de cada funcao MUST estar dentro de `code.len`.
|
||||
3. A concatenacao final MUST ser deterministica.
|
||||
|
||||
### 6) Encoding de instrucao
|
||||
|
||||
1. Encoding MUST ser little-endian.
|
||||
2. Layout de instrucao MUST ser `[opcode: u16][immediate]`.
|
||||
3. Saltos MUST usar imediato `u32` relativo ao inicio da funcao.
|
||||
4. O emitter MUST respeitar tamanhos de imediato definidos pela Core ISA alvo.
|
||||
|
||||
### 7) Pre-load vs executable image
|
||||
|
||||
1. Para chamadas host-backed, o backend MUST emitir `HOSTCALL <sysc_index>` no artefato pre-load.
|
||||
2. O backend MUST NOT emitir `SYSCALL <id>` bruto no artefato pre-load.
|
||||
3. Chamadas VM-owned MUST seguir caminho de `INTRINSIC <id_final>` e permanecer distintas de `SYSC`/`HOSTCALL`/`SYSCALL`.
|
||||
4. O backend MUST assumir que patch `HOSTCALL -> SYSCALL` e responsabilidade do loader.
|
||||
|
||||
### 8) Coerencia ABI de host bindings
|
||||
|
||||
1. Cada entrada `SYSC` MUST carregar `module`, `name`, `version`, `arg_slots`, `ret_slots`.
|
||||
2. O emitter MUST validar coerencia de ABI declarada com metadado host conhecido no alvo de compilacao.
|
||||
3. Mismatch detectavel no compile target MUST falhar no compilador antes da serializacao final.
|
||||
|
||||
### 9) Debug minimo v1 (inspirado em line tables)
|
||||
|
||||
1. `debug_info` v1 MUST incluir:
|
||||
- `function_names` para todos os `func_idx` emitidos;
|
||||
- `pc_to_span` para todo inicio de instrucao emitida.
|
||||
2. O objetivo minimo e preservar atribuicao de fonte acionavel para falhas backend/runtime que permaneçam source-atribuiveis.
|
||||
|
||||
### 10) Fronteira de validacao por camada
|
||||
|
||||
Modelo inspirado em separacao JVM (format/link/verify), adaptado:
|
||||
|
||||
1. emitter valida formato e invariantes de marshaling;
|
||||
2. loader valida resolucao canonica, capability e ABI host;
|
||||
3. verifier valida estrutura de controle e pilha na imagem patchada.
|
||||
|
||||
O backend MUST executar prechecks de marshaling sem substituir a autoridade do loader/verifier.
|
||||
|
||||
### 11) Taxonomia de erros de marshaling
|
||||
|
||||
O backend MUST expor codigos estaveis para erros de marshaling em familias:
|
||||
|
||||
1. `MARSHAL_FORMAT_*`,
|
||||
2. `MARSHAL_LINKAGE_*`,
|
||||
3. `MARSHAL_VERIFY_PRECHECK_*`.
|
||||
|
||||
Quando atribuivel, diagnostico MUST incluir ancora de fonte primaria.
|
||||
|
||||
### 12) Otimizacao: criterio de responsabilidade
|
||||
|
||||
1. Otimizacao semantica/estrutural de programa MUST ocorrer no backend (compile-time).
|
||||
2. Runtime MUST permanecer focado em carregamento, validacao e execucao deterministica.
|
||||
3. Ajustes internos de runtime sao permitidos apenas se nao alterarem semantica do programa nem contrato observavel de bytecode.
|
||||
|
||||
### 13) Suite minima Gate I (sem packer)
|
||||
|
||||
A conformidade minima de integracao MUST incluir fixtures:
|
||||
|
||||
1. `SYSC` presente e vazio (caso sem hostcall);
|
||||
2. `HOSTCALL` valido com patch para `SYSCALL`;
|
||||
3. `HOSTCALL` com indice fora de faixa;
|
||||
4. `SYSC` declarado e nao usado;
|
||||
5. `SYSCALL` bruto em artefato pre-load;
|
||||
6. mismatch de ABI (`arg_slots`/`ret_slots`);
|
||||
7. capability insuficiente em load-time;
|
||||
8. caminho com `INTRINSIC` valido.
|
||||
|
||||
### 14) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo por fronteira:
|
||||
|
||||
1. formato de packer/cartucho final;
|
||||
2. superfices avancadas de simbolizacao alem do minimo v1.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
@ -69,4 +195,3 @@ Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformida
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ Closed agendas are moved to `docs/pbs/agendas/archive`.
|
||||
|
||||
1. `18.0. Backend VM Pipeline - Orchestration Agenda.md`
|
||||
2. `18.1. Backend Workshop 1 - IRBackend Input Contract.md`
|
||||
3. `18.2. Backend Workshop 2 - LowerToVM and IRVM Contract.md`
|
||||
3. `18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
|
||||
4. `18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
|
||||
## Purpose
|
||||
|
||||
@ -0,0 +1,64 @@
|
||||
# IRVM Optimization Stage Placement Decision
|
||||
|
||||
Status: Accepted
|
||||
Date: 2026-03-07
|
||||
Related Agendas:
|
||||
|
||||
- `docs/pbs/agendas/18.0. Backend VM Pipeline - Orchestration Agenda.md`
|
||||
- `docs/pbs/agendas/18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract.md`
|
||||
- `docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md`
|
||||
|
||||
## Context
|
||||
|
||||
Ao fechar a trilha backend executavel (`IRBackend -> IRVM -> bytecode`), surgiu a necessidade de definir onde a otimizacao deve ocorrer.
|
||||
|
||||
As opcoes praticas eram:
|
||||
|
||||
1. otimizar no runtime,
|
||||
2. otimizar durante emissao de bytecode,
|
||||
3. otimizar em etapa dedicada sobre `IRVM` antes da emissao.
|
||||
|
||||
O runtime atual privilegia determinismo, loader/verifier estritos e execucao numeric-only.
|
||||
|
||||
## Decision
|
||||
|
||||
PBS adota etapa dedicada de otimizacao entre lowering e emissao:
|
||||
|
||||
1. `LowerToIRVM` gera `IRVM`;
|
||||
2. `OptimizeIRVM` aplica transformacoes `IRVM -> IRVM` semanticamente equivalentes;
|
||||
3. `EmitBytecode` serializa o `IRVM` otimizado em artefato pre-load.
|
||||
|
||||
A etapa `OptimizeIRVM` passa a ser parte canônica do pipeline backend executavel.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. `OptimizeIRVM` e compile-time, nao runtime.
|
||||
2. `OptimizeIRVM` MUST preservar semantica observavel do programa.
|
||||
3. `OptimizeIRVM` MUST preservar contratos de chamada/retorno/slots.
|
||||
4. `OptimizeIRVM` MUST preservar determinismo para o mesmo grafo de entrada admitido.
|
||||
5. `OptimizeIRVM` MUST respeitar `vm_profile` alvo e nao deixar opcodes internos nao-eliminados para a emissao final.
|
||||
6. `EmitBytecode` continua responsavel por produzir artefato pre-load conforme contrato de loader/verifier.
|
||||
7. Runtime nao assume papel de otimizador semantico do programa.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
1. Esta decisao nao define o catalogo completo de passes de otimizacao.
|
||||
2. Esta decisao nao define heuristicas de custo/performance por alvo.
|
||||
3. Esta decisao nao redefine regras de verifier/loader do runtime.
|
||||
4. Esta decisao nao define fluxo de packer/cartucho.
|
||||
|
||||
## Spec Impact
|
||||
|
||||
1. A orquestracao de pipeline em `18.0` passa a incluir `OptimizeIRVM` entre `LowerToIRVM` e `EmitBytecode`.
|
||||
2. A futura spec de `IRVM` (`18.2`) deve explicitar pre/post-condicoes da etapa de otimizacao.
|
||||
3. A futura spec de marshaling (`18.3`) deve explicitar que a emissao opera sobre `IRVM` pos-otimizacao.
|
||||
4. `docs/general/specs/19. Verification and Safety Checks Specification.md` deve refletir cobertura de regressao para pipeline com otimizacao intermediaria.
|
||||
|
||||
## Validation Notes
|
||||
|
||||
Para validacao minima da decisao:
|
||||
|
||||
1. o pipeline executa na ordem `LowerToIRVM -> OptimizeIRVM -> EmitBytecode`;
|
||||
2. fixtures equivalentes com e sem otimizacao produzem comportamento runtime equivalente;
|
||||
3. casos negativos de loader/verifier continuam falhando de forma deterministica apos a introducao de `OptimizeIRVM`.
|
||||
|
||||
@ -19,7 +19,8 @@ public class BuilderPipelineService {
|
||||
new ResolveDepsPipelineStage(),
|
||||
new LoadSourcesPipelineStage(),
|
||||
new FrontendPhasePipelineStage(),
|
||||
new LowerToVMPipelineStage(),
|
||||
new LowerToIRVMPipelineStage(),
|
||||
new OptimizeIRVMPipelineStage(),
|
||||
new EmitBytecodePipelineStage()
|
||||
);
|
||||
INSTANCE = new BuilderPipelineService(stages);
|
||||
|
||||
@ -7,7 +7,7 @@ import p.studio.compiler.workspaces.PipelineStage;
|
||||
import p.studio.utilities.logs.LogAggregator;
|
||||
|
||||
@Slf4j
|
||||
public class LowerToVMPipelineStage implements PipelineStage {
|
||||
public class LowerToIRVMPipelineStage implements PipelineStage {
|
||||
@Override
|
||||
public BuildingIssueSink run(BuilderPipelineContext ctx, LogAggregator logs) {
|
||||
return BuildingIssueSink.empty();
|
||||
@ -0,0 +1,15 @@
|
||||
package p.studio.compiler.workspaces.stages;
|
||||
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import p.studio.compiler.messages.BuildingIssueSink;
|
||||
import p.studio.compiler.models.BuilderPipelineContext;
|
||||
import p.studio.compiler.workspaces.PipelineStage;
|
||||
import p.studio.utilities.logs.LogAggregator;
|
||||
|
||||
@Slf4j
|
||||
public class OptimizeIRVMPipelineStage implements PipelineStage {
|
||||
@Override
|
||||
public BuildingIssueSink run(BuilderPipelineContext ctx, LogAggregator logs) {
|
||||
return BuildingIssueSink.empty();
|
||||
}
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user