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