---
id: AGD-0061
ticket: multi-frontend-serializable-ir
title: Manter a IR comum serializavel por design
status: open
created: 2026-07-15
resolved:
decision:
tags: [compiler, compiler-general, ir, backend, serialization, multi-frontend]
---

# Agenda - Manter a IR serializavel por design

## Objetivo

Domain owner: `compiler/general`.

Avaliar se a IR comum pode atravessar futuramente uma fronteira de processo sem redesenho, evitando callbacks, estado global, ciclos e identity equality como parte do contrato.

## Contexto atual

O pipeline atual roda na JVM, mas frontends futuros podem ser externos. O alinhamento proibe escolher JSON, Protobuf, RPC ou processo externo agora; a discussao deve focar no formato dos dados.

## Escopo

- Auditar records/classes da IR comum.
- Identificar referencias a servicos, objetos mutaveis, ciclos e IDs implicitos.
- Definir principios de modelagem: IDs explicitos, listas ordenadas, enums e valores primitivos.

## Fora de escopo

- Implementar codec.
- Serializar a saida do PBS dentro do mesmo processo.
- Escolher wire format.

## Arquivos e componentes a inspecionar

- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/...`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/...`
- testes `IRBackendExecutableContractTest` e `LowerToIRVMServiceTest`
- docs de specs do compiler geral

## Alteracoes propostas

Opcao A: documentar invariantes de serializabilidade e corrigir apenas vazamentos claros.

Opcao B: criar tipos de ID e spans onde hoje houver identidade textual ou referencias diretas instaveis.

Recomendacao inicial: comecar por auditoria e testes de reflexao leves antes de qualquer migracao estrutural.

## Estrategia de implementacao

Gerar uma lista de tipos publicos da IR, revisar construtores e campos, e propor correcoes incrementais para pontos que impediriam um codec futuro.

## Testes necessarios

- Teste de reflexao sobre campos publicos/record components da IR.
- Teste de determinismo de ordenacao.
- Teste de ausencia de referencias a AST, servicos ou callbacks.

## Criterios de aceitacao

- A IR pode ser descrita como grafo de dados aciclico ou com referencias por ID.
- Nenhuma escolha prematura de wire format e introduzida.

## Riscos

- Overengineering de IDs onde o contrato ainda nao exige.
- Quebrar ergonomia de testes ao tornar todos os objetos verbosos.

## Decisoes que devem ser registradas

- Regras minimas de serializabilidade.
- Tipos de ID que devem existir agora.
- Itens explicitamente adiados para codec futuro.