prometeu-studio/docs/pbs/agendas/18.1. Backend Workshop 1 - IRBackend Input Contract.md

18.1. Backend Workshop 1 - IRBackend Input Contract

Status: Ready for Closure (v1 Draft Text)

Purpose

Fechar o IRBackend como contrato de entrada do backend executável, de forma suficientemente explícita para permitir lowering determinístico para IRVM.

Context

• A spec atual de IRBackend cobre sobretudo a fronteira frontend e não fecha IRBackend -> IRVM.
• O runtime exige contratos rígidos para chamadas host-backed (SYSC/HOSTCALL) e VM-owned (INTRINSIC).
• O backend precisa receber um IR que preserve semântica e também fatos de artefato necessários para bytecode.

Decisions to Produce

1. Shape mínima obrigatória de IRBackend para backend executável:
   • identidade de módulo/arquivo/callable,
   • assinatura (parâmetros/retorno),
   • corpo executável em forma backend-lowerable,
   • âncoras de source attribution.
2. Modelo de representação para operações VM-owned vs host-backed no IRBackend.
3. Contrato de metadados reservados obrigatório:
   • host bindings canônicos (module, name, version),
   • metadados de intrinsics/builtin VM-owned,
   • requiredCapabilities determinístico.
4. Regras de ordenação/deduplicação obrigatórias ainda no IRBackend.
5. Política de rejeição determinística para formas que não entram no backend executável.

Core Questions

1. O IRBackend deve carregar código em forma estruturada (blocos/expressões) ou linearizada?
2. Quais informações de tipos precisam sobreviver para o backend sem “re-tipagem” implícita?
3. Como representar chamadas host-backed no IRBackend:
   • por identidade canônica,
   • por índice lógico,
   • ou por ambos?
4. Como representar intrinsics VM-owned:
   • identidade canônica apenas,
   • id final já conhecido,
   • ou modelo híbrido?
5. Quais invariantes de estabilidade de ordenação são obrigatórias para conformance?
6. Quais campos mínimos de span/source mapping são mandatórios para erros backend-atribuíveis?

Resolution (v1)

Nao ha open questions bloqueantes para fechar o contrato de entrada IRBackend v1.

As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.

Normative Text (Draft for Closure)

1) Escopo e fronteira

1. IRBackend e o contrato de entrada normativo do backend executavel.
2. O frontend MUST emitir IRBackend completo para toda unidade admitida no Gate U.
3. O backend MUST tratar IRBackend como fonte de verdade para IRBackend -> IRVM.
4. Esta agenda NAO define o formato de IRVM nem o encoding final de bytecode.

2) Obrigacoes minimas por callable

Para cada callable executavel emitido no IRBackend, o frontend MUST preservar:

1. identidade estavel do callable no build atual;
2. assinatura observavel:
   • aridade de entrada;
   • shape de retorno observavel;
3. categoria de callable (ex.: funcao comum vs superficie reservada nao executavel);
4. ancora de atribuicao de fonte (fileId, start, end);
5. corpo backend-lowerable com semantica suficiente para emissao de chamadas e fluxo.

IRFunction apenas com nome/contagem de parametros/span NAO satisfaz este contrato executavel.

3) Classificacao obrigatoria de callsites

Todo callsite executavel no IRBackend MUST estar classificado em exatamente uma categoria:

1. CALL_FUNC (chamada de callable de programa);
2. CALL_HOST (fronteira host-backed);
3. CALL_INTRINSIC (operacao VM-owned).

Implementacoes MUST NOT inferir a categoria por heuristica textual na fase LowerToIRVM.

4) Contrato para host-backed

Todo CALL_HOST MUST carregar identidade canonica:

1. abiModule,
2. abiMethod,
3. abiVersion.

Todo CALL_HOST MUST carregar declaracao de ABI:

1. arg_slots,
2. ret_slots.

O conjunto de bindings host-backed no IRBackend MUST ser deduplicado por (module, name, version) e ordenado por primeira ocorrencia deterministica.

5) Contrato para VM-owned intrinsics e builtins

Todo CALL_INTRINSIC MUST carregar identidade canonica VM-owned:

1. canonicalName,
2. canonicalVersion.

Builtin projections, builtin constants e intrinsic callsites VM-owned MUST NOT ser modelados como host binding.

6) Metadados reservados obrigatorios

IRReservedMetadata MUST preservar, no minimo:

1. host bindings canonicos admitidos;
2. builtin type surfaces relevantes para lowering;
3. builtin const surfaces relevantes para lowering;
4. requiredCapabilities deterministico para assistencia de pipeline/packer.

requiredCapabilities MUST ser deterministico para o mesmo grafo de entrada admitido.

7) Diagnosticos e rejeicao deterministica

Quando um modulo/callable nao satisfaz o contrato de entrada executavel:

1. a rejeicao MUST ser deterministica;
2. o diagnostico MUST manter atribuicao de fonte acionavel;
3. o frontend/backend MUST NOT degradar silenciosamente para comportamento executavel diferente.

8) Deferrals explicitos

Ficam deferidos para agendas seguintes:

1. shape estrutural completo de IRVM e algoritmo de lowering (Agenda 18.2);
2. layout/encoding final de BytecodeModule e marshaling PBX (Agenda 18.3);
3. estrategia de otimizacao de backend.

Expected Spec Material

1. Atualização de docs/pbs/specs/13. Lowering IRBackend Specification.md com adendo backend-facing.
2. Decision record específico para “IRBackend executável v1”.
3. Fixture set de conformance Gate U focado no contrato de entrada do backend.

Non-Goals

• Definir ainda o bytecode final.
• Definir políticas de otimização.
• Definir o formato final de debug/source map rico.
• Introduzir dependência de packer.

Inputs

• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java
• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackendFile.java
• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java
• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java
• docs/pbs/specs/13. Lowering IRBackend Specification.md
• docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md
• docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md
• ../runtime/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md