# 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`