Stable contract FE/BE
This commit is contained in:
@@ -2,36 +2,43 @@
|
||||
id: AGD-0060
|
||||
ticket: multi-frontend-frontend-backend-contract
|
||||
title: Estabilizar contrato entre frontend e backend comum
|
||||
status: open
|
||||
status: accepted
|
||||
created: 2026-07-15
|
||||
resolved:
|
||||
decision:
|
||||
decision: DEC-0043
|
||||
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
|
||||
---
|
||||
|
||||
# Agenda - Estabilizar o contrato entre frontend e backend
|
||||
# Agenda - Solidificar o contrato existente entre frontend e backend
|
||||
|
||||
## Objetivo
|
||||
|
||||
Domain owner: `compiler/general`, com impacto em `compiler/pbs`.
|
||||
|
||||
Definir o limite exato entre frontend e backend para garantir que o backend receba IR comum, e nao AST, tokens, simbolos ou objetos semanticos 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.
|
||||
- Confirmar se a estrutura atual ja representa uma IR comum.
|
||||
- Identificar qualquer dependencia em AST ou semantica PBS no backend.
|
||||
- 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
|
||||
|
||||
@@ -43,36 +50,44 @@ As specs citam `IRBackend` como handoff executavel em `docs/specs/compiler/20. I
|
||||
|
||||
## Alteracoes propostas
|
||||
|
||||
Opcao A: manter `IRBackend` e documentar/adaptar o contrato como `Prometeu Frontend IR`.
|
||||
Opcao A: manter `IRBackend` e documentar o contrato existente como handoff comum frontend-to-backend.
|
||||
|
||||
Opcao B: criar um novo nome de dominio quando houver divergencia real entre modelo atual e fronteira desejada.
|
||||
Opcao B: renomear ou extrair tipos somente se a auditoria encontrar dependencia real de linguagem no contrato publico.
|
||||
|
||||
Recomendacao inicial: auditar antes de renomear; mudar nomes so quando o modelo atual impedir clareza operacional.
|
||||
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 PBS, e planejar extracoes pequenas para qualquer vazamento.
|
||||
Listar campos e tipos transitivos da IR, classificar cada item como comum ou especifico de linguagem, e separar tres resultados possiveis:
|
||||
|
||||
1. itens ja neutros que devem virar contrato normativo;
|
||||
2. vazamentos apenas documentais ou de naming, que devem virar ajustes editoriais pequenos;
|
||||
3. 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 contem modulos, funcoes, tipos, blocos, calls, exports, lifecycle, spans, diagnostics e capabilities em termos neutros.
|
||||
- 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
|
||||
|
||||
- Nome normativo do handoff.
|
||||
- Lista de tipos permitidos no contrato.
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user