# 18.1. Backend Workshop 1 - IRBackend Input Contract

Status: Active (Draft)

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

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