canonical path for intrinsics

This commit is contained in:
2026-03-24 13:42:37 +00:00
parent 59e33d6639
commit b33dc7c18d
11 changed files with 677 additions and 738 deletions
@@ -1,121 +0,0 @@
# 18.0. Backend VM Pipeline - Orchestration Agenda
Status: Ready for Closure (v1 Draft Text)
## Purpose
Definir a ordem de fechamento arquitetural para o backend executável:
1. contrato de entrada `IRBackend` vindo do frontend,
2. lowering `IRBackend -> IRVM`,
3. marshaling `IRVM -> bytecode/PBX` executável no runtime.
## Context
- 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.
## Decisions to Produce
1. Ordem oficial de workshops e critérios de saída por etapa.
2. Fronteiras normativas entre:
- frontend (`IRBackend`),
- backend (`IRVM` + emissão),
- runtime (loader/verifier/execução).
3. Critérios de “backend integration-ready” para um artefato bytecode mínimo rodar no runtime.
4. Estratégia de fechamento em docs (`agendas -> decisions -> specs -> PR`).
## Core Questions
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).
2. Nova spec de contrato de `IRVM` (shape, invariantes, diagnóstico).
3. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
4. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
## Non-Goals
- Definir formato final de packer/cartucho.
- Redesenhar ISA do runtime.
- Redesenhar loader/verifier do runtime.
- Fechar otimizações de backend (peephole, SSA, etc.).
## Inputs
- `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`
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
- `../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,157 +0,0 @@
# 18.1. Backend Workshop 1 - IRBackend Input Contract
Status: Ready for Closure (v1 Draft Text)
## Purpose
Fechar o `IRBackend` como contrato de entrada do backend executável, de forma suficientemente explícita para permitir lowering determinístico para `IRVM`.
## Context
- A spec atual de `IRBackend` cobre sobretudo a fronteira frontend e não fecha `IRBackend -> IRVM`.
- O runtime exige contratos rígidos para chamadas host-backed (`SYSC`/`HOSTCALL`) e VM-owned (`INTRINSIC`).
- O backend precisa receber um IR que preserve semântica e também fatos de artefato necessários para bytecode.
## Decisions to Produce
1. Shape mínima obrigatória de `IRBackend` para backend executável:
- identidade de módulo/arquivo/callable,
- assinatura (parâmetros/retorno),
- corpo executável em forma backend-lowerable,
- âncoras de source attribution.
2. Modelo de representação para operações VM-owned vs host-backed no `IRBackend`.
3. Contrato de metadados reservados obrigatório:
- host bindings canônicos `(module, name, version)`,
- metadados de intrinsics/builtin VM-owned,
- `requiredCapabilities` determinístico.
4. Regras de ordenação/deduplicação obrigatórias ainda no `IRBackend`.
5. Política de rejeição determinística para formas que não entram no backend executável.
## Core Questions
1. O `IRBackend` deve carregar código em forma estruturada (blocos/expressões) ou linearizada?
2. Quais informações de tipos precisam sobreviver para o backend sem “re-tipagem” implícita?
3. Como representar chamadas host-backed no `IRBackend`:
- por identidade canônica,
- por índice lógico,
- ou por ambos?
4. Como representar intrinsics VM-owned:
- identidade canônica apenas,
- id final já conhecido,
- ou modelo híbrido?
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.
2. Decision record específico para “IRBackend executável v1”.
3. Fixture set de conformance Gate U focado no contrato de entrada do backend.
## Non-Goals
- Definir ainda o bytecode final.
- Definir políticas de otimização.
- Definir o formato final de debug/source map rico.
- Introduzir dependência de packer.
## Inputs
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java`
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackendFile.java`
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java`
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java`
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
- `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,165 +0,0 @@
# 18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract
Status: Ready for Closure (v1 Draft Text)
## Purpose
Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRBackend -> IRVM`, garantindo que a emissão de bytecode seja mecânica e determinística.
## Context
- O runtime já define ISA e calling rules concretas.
- No runtime atual, jumps usam imediato `u32` absoluto relativo ao início da função.
- O verificador e o loader já têm validações rígidas que devem ser antecipadas pelo backend sempre que possível.
## Decisions to Produce
1. Modelo oficial de `IRVM`:
- unidades (módulo/função/bloco),
- instruções VM-like,
- referência a constantes/globais/locals/callables,
- metadados mínimos por função.
2. Regras de lowering para controle de fluxo:
- labels simbólicos,
- normalização de blocos,
- política de branch/jump target.
3. Regras de lowering para chamadas:
- `CALL`,
- `HOSTCALL` pré-load,
- `INTRINSIC` VM-owned.
4. Regras de layout de função e slots:
- `param_slots`,
- `local_slots`,
- `return_slots`.
5. Política de diagnósticos determinísticos no lowering para rejeições backend-originadas.
## Core Questions
1. `IRVM` permite pseudo-opcodes que não existem na ISA final?
2. Onde ocorre a resolução final de labels para offsets: no próprio lowering ou apenas no emitter?
3. Como garantir que cada função tenha finalização válida (`RET`/terminador) sem depender só do verificador?
4. Qual o limite de checagens estáticas no compiler vs checagens delegadas ao verifier do runtime?
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 `LowerToIRVMPipelineStage`.
## Non-Goals
- Implementar ainda otimizações avançadas.
- Expandir ISA com novos opcodes.
- Resolver políticas de linking multi-artifact além do necessário para execução v1.
- Definir packer/cart assembly.
## Inputs
- `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`
- `../runtime/crates/console/prometeu-bytecode/src/opcode.rs`
- `../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,197 +0,0 @@
# 18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance
Status: Ready for Closure (v1 Draft Text)
## Purpose
Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformidade explícita ao loader/verifier/runtime atual.
## Context
- O runtime já define layout de módulo, parser de seções e invariantes de load-time.
- `SYSC` é seção obrigatória (mesmo vazia), `HOSTCALL` é forma pré-load, `SYSCALL` final só após patching do loader.
- O verifier rejeita `HOSTCALL` não patchado e valida estrutura de controle/stack sobre imagem final.
## Decisions to Produce
1. Contrato de marshaling de `IRVM -> BytecodeModule`:
- `const_pool`,
- `functions`,
- `code`,
- `debug_info` (mínimo obrigatório),
- `exports`,
- `syscalls`.
2. Política de encoding de instruções:
- little-endian,
- `[opcode u16][immediate]`,
- encoding de saltos/calls conforme ISA.
3. Política de emissão de `SYSC`:
- deduplicação por identidade canônica,
- ordenação por primeira ocorrência,
- `arg_slots`/`ret_slots` coerentes com metadado host.
4. Contrato explícito “pre-load artifact vs executable image”:
- backend emite `HOSTCALL` quando host-backed,
- backend não emite `SYSCALL` bruto no artefato pré-load,
- intrinsics VM-owned seguem caminho distinto.
5. Estratégia de conformidade e regressão contra runtime real.
## Core Questions
1. Qual política oficial de ordenação de funções no bytecode (ordem de source, topo sort, entry-first)?
2. Como calcular `code_offset`/`code_len` por função em flatten final de `code`?
3. Quais hooks mínimos de source attribution serão emitidos no `debug_info` v1?
4. Quais validações o emitter faz antes de serializar vs o que é delegado ao loader/verifier?
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`.
2. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
3. Decision record de “bytecode backend v1 marshaling contract”.
4. Plano de testes Gate I para backend executável.
## Non-Goals
- Definir fluxo de empacotamento final de cartucho.
- Alterar o contrato do loader/runtime.
- Definir formato final de symbolication completo.
- Cobrir perf tuning de emissor.
## Inputs
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
- `../runtime/crates/console/prometeu-bytecode/src/model.rs`
- `../runtime/crates/console/prometeu-bytecode/src/assembler.rs`
- `../runtime/crates/console/prometeu-bytecode/src/program_image.rs`
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
- `../runtime/crates/console/prometeu-vm/src/vm_init_error.rs`
- `../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`