prometeu-studio/docs/pbs/pull-requests/PR-033-backend-bytecode-function-layout-and-debug-minimum.md

PR-033 - Backend Function Layout and Debug Minimum

Briefing

Implementar o builder de layout final de funcoes (code_offset, code_len) e o contrato minimo de debug (function_names, pc_to_span) antes de integrar com stages do pipeline.

Target

• Construir flatten deterministico de codigo por funcao.
• Preencher functions[] com offsets/len coerentes.
• Preencher debug_info minimo v1.

Method

• Adicionar um layout builder que recebe codigo por funcao e produz code unico.
• Garantir code_offset monotonicos e unicos.
• Garantir code_len exato por funcao.
• Gerar debug_info.function_names e debug_info.pc_to_span no momento de materializacao final.
• Seguir invariantes de consumo do runtime (ProgramImage e verifier).

Acceptance Criteria

1. code_offset + code_len de cada funcao fica dentro de code.len.
2. Ordem de flatten e offsets sao deterministicos.
3. function_names contem todos os func_idx emitidos.
4. pc_to_span cobre cada inicio de instrucao emitida.

Tests

1. Teste unitario de layout com multiplas funcoes.
2. Teste unitario de limites invalidos rejeitados deterministicamente.
3. Teste unitario de cobertura de debug minimo.

Affected Documents

• docs/general/specs/15. Bytecode and PBX Mapping Specification.md