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`