prometeu-studio/docs/pbs/agendas/18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance.md

18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance

Status: Active (Draft)

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?

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