Agenda - Solidificar o contrato existente entre frontend e backend

Objetivo

Domain owner: compiler/general, com impacto em compiler/pbs.

Solidificar a fronteira que ja existe entre frontend e backend: o backend comum deve receber IRBackend como handoff comum, nao AST, tokens, simbolos ou objetos semanticos PBS.

A premissa desta agenda e que a direcao atual esta majoritariamente correta. O trabalho nao deve partir de uma reescrita ou renomeacao ampla, mas de registrar o contrato existente, corrigir vazamentos conceituais/documentais e adicionar guardrails para outros frontends.

Contexto atual

As specs citam IRBackend como handoff executavel em docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md e docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md. Testes como IRBackendExecutableContractTest e LowerToIRVMServiceTest ja sugerem um contrato backend direto.

A leitura atual e que os modelos centrais de IRBackend, IRBackendFile e IRBackendExecutableFunction ja vivem em superficie comum e nao carregam tipos PBS diretamente. A dor restante e tornar essa escolha explicita como regra arquitetural e limpar sinais residuais de PBS-by-default, como nomes, specs ou validacoes que parecem especificas de PBS apesar de expressarem obrigacoes neutras do executavel.

Escopo

Auditar tipos publicos de IRBackend e modelos associados para confirmar a neutralidade atual.
Declarar IRBackend como handoff comum frontend-to-backend, salvo divergencia concreta encontrada na auditoria.
Identificar vazamentos reais ou conceituais de PBS no backend comum, em specs, nomes de metodos, testes ou mensagens.
Planejar apenas correcoes pequenas e direcionadas para esses vazamentos.

Fora de escopo

Renomear IRBackend por preferencia estetica.
Reescrever o modelo de IR existente sem evidencia de vazamento real.
Redesenhar o lowering para IRVM.
Implementar serializacao.
Resolver a futura IR serializavel ou o frontend sintetico de testes.

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/...
prometeu-compiler/frontends/prometeu-frontend-pbs/...
docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md
docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md

Alteracoes propostas

Opcao A: manter IRBackend e documentar o contrato existente como handoff comum frontend-to-backend.

Opcao B: renomear ou extrair tipos somente se a auditoria encontrar dependencia real de linguagem no contrato publico.

Recomendacao inicial: seguir a Opcao A. A agenda deve consolidar o que ja esta bom e corrigir apenas os pontos que ainda fazem o backend comum parecer PBS-specific.

Estrategia de implementacao

Listar campos e tipos transitivos da IR, classificar cada item como comum ou especifico de linguagem, e separar tres resultados possiveis:

itens ja neutros que devem virar contrato normativo;
vazamentos apenas documentais ou de naming, que devem virar ajustes editoriais pequenos;
vazamentos reais de tipo ou dependencia, que devem virar extracoes pequenas.

Testes necessarios

Teste construindo IR comum diretamente sem parser PBS.
Teste de backend sem imports de packages PBS.
Teste negativo para tipos AST PBS no contrato publico da IR.
Teste ou checagem arquitetural garantindo que prometeu-build-pipeline backend comum nao dependa de p.studio.compiler.pbs.

Criterios de aceitacao

Backend e testavel com IR montada manualmente.
Contrato existente e descrito como comum em specs gerais, sem linguagem que sugira ownership PBS do backend.
Obrigacoes de lifecycle, entrypoint publicado, boot guard, spans e capabilities sao expressas em termos neutros quando pertencerem ao backend comum.
Contrato nao contem PbsExpression, PbsStatement, PbsToken ou equivalentes.
Qualquer nome, spec ou validacao PBS-specific restante no backend comum tem justificativa explicita ou plano de correcao pequeno.

Riscos

Tratar a agenda como permissao para redesenhar uma fronteira que ja esta funcionando.
Confundir IR comum com modelo de lowering interno de PBS.
Quebrar fixtures existentes por mudanca ampla demais.

Decisoes que devem ser registradas

IRBackend permanece ou nao como nome do handoff comum.
Lista de tipos permitidos no contrato publico.
Limite entre spec geral e spec PBS.
Quais vazamentos, se houver, exigem plano de correcao.

4.8 KiB Raw Blame History