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: 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