prometeu-studio/discussion/workflow/agendas/AGD-0061-multi-frontend-serializable-ir.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0061	multi-frontend-serializable-ir	Manter a IR comum serializavel por design	open	2026-07-15			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.