Stable contract FE/BE
This commit is contained in:
parent
ffd2975484
commit
26c69d5660
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -1,4 +1,4 @@
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":43,"PLN":117,"LSN":59,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":44,"PLN":119,"LSN":59,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0065","status":"open","ticket":"multi-frontend-avoid-premature-abstractions","title":"Evitar abstracoes prematuras na preparacao multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","multi-frontend","simplicity"],"agendas":[{"id":"AGD-0068","file":"AGD-0068-multi-frontend-avoid-premature-abstractions.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0064","status":"open","ticket":"multi-frontend-architectural-tests","title":"Testes arquiteturais para fronteiras multi-frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","architecture","tests","multi-frontend"],"agendas":[{"id":"AGD-0067","file":"AGD-0067-multi-frontend-architectural-tests.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0063","status":"open","ticket":"multi-frontend-synthetic-test-frontend","title":"Frontend sintetico de teste para provar neutralidade do pipeline","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","frontend","tests","backend","multi-frontend"],"agendas":[{"id":"AGD-0066","file":"AGD-0066-multi-frontend-synthetic-test-frontend.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
@ -7,7 +7,7 @@
|
||||
{"type":"discussion","id":"DSC-0060","status":"open","ticket":"multi-frontend-validation-boundaries","title":"Separar validacoes de linguagem e validacoes de plataforma","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","backend","validation","multi-frontend"],"agendas":[{"id":"AGD-0063","file":"AGD-0063-multi-frontend-validation-boundaries.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0059","status":"open","ticket":"multi-frontend-common-lifecycle","title":"Extrair lifecycle comum das responsabilidades do frontend PBS","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","lifecycle","backend","multi-frontend"],"agendas":[{"id":"AGD-0062","file":"AGD-0062-multi-frontend-common-lifecycle.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0058","status":"open","ticket":"multi-frontend-serializable-ir","title":"Manter a IR comum serializavel por design","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","ir","backend","serialization","multi-frontend"],"agendas":[{"id":"AGD-0061","file":"AGD-0061-multi-frontend-serializable-ir.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0057","status":"open","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[{"id":"AGD-0060","file":"AGD-0060-multi-frontend-frontend-backend-contract.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0057","status":"in_progress","ticket":"multi-frontend-frontend-backend-contract","title":"Estabilizar contrato entre frontend e backend comum","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","ir","backend","multi-frontend"],"agendas":[{"id":"AGD-0060","file":"AGD-0060-multi-frontend-frontend-backend-contract.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15"}],"decisions":[{"id":"DEC-0043","file":"DEC-0043-common-irbackend-frontend-backend-handoff.md","status":"accepted","created_at":"2026-07-15","updated_at":"2026-07-15","ref_agenda":"AGD-0060"}],"plans":[{"id":"PLN-0117","file":"PLN-0117-common-irbackend-contract-specs.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0043"]},{"id":"PLN-0118","file":"PLN-0118-common-irbackend-backend-guardrails.md","status":"open","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0043"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0056","status":"done","ticket":"multi-frontend-remove-pbs-branches","title":"Generalizar o contrato LSP/editorial para frontends","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","compiler-pbs","studio","frontend","coupling","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0058","file":"discussion/lessons/DSC-0056-multi-frontend-remove-pbs-branches/LSN-0058-generic-frontend-editorial-contract-for-lsp.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0055","status":"done","ticket":"multi-frontend-compiler-vs-language-services","title":"Separar compilacao de servicos editoriais de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","lsp","editor","frontend","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0055-multi-frontend-compiler-vs-language-services/LSN-0056-compile-first-frontends-with-optional-editorial-capabilities.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
{"type":"discussion","id":"DSC-0054","status":"done","ticket":"multi-frontend-provider-contract","title":"Introduzir provider completo de frontend","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["compiler","compiler-general","studio","frontend","registry","multi-frontend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -0,0 +1,145 @@
|
||||
---
|
||||
id: DEC-0043
|
||||
ticket: multi-frontend-frontend-backend-contract
|
||||
title: IRBackend is the common frontend-to-backend handoff
|
||||
status: accepted
|
||||
created: 2026-07-15
|
||||
accepted:
|
||||
agenda: AGD-0060
|
||||
plans: []
|
||||
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
|
||||
---
|
||||
|
||||
# Decision - IRBackend is the common frontend-to-backend handoff
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
AGD-0060 had no remaining substantive open question after the scope was narrowed to consolidation of the existing boundary.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `compiler/general`, with impact on `compiler/pbs`.
|
||||
|
||||
The compiler already has an executable handoff named `IRBackend`. The central public models live in the common frontend API surface and are consumed by the backend lowering path:
|
||||
|
||||
- `IRBackend`
|
||||
- `IRBackendFile`
|
||||
- `IRBackendExecutableFunction`
|
||||
- associated common identifiers, pools, spans, reserved metadata, globals, synthetic functions, and callable metadata
|
||||
|
||||
The current architecture is already directionally correct: the common backend does not need PBS AST nodes, PBS tokens, or PBS semantic objects to lower executable code. The remaining risk is not a known broken boundary. The risk is that residual PBS-specific names, spec wording, tests, or validation names may make the common backend look owned by PBS and may invite future coupling when additional frontends are introduced.
|
||||
|
||||
## Decision
|
||||
|
||||
`IRBackend` SHALL remain the normative common frontend-to-backend executable handoff.
|
||||
|
||||
The compiler MUST treat `IRBackend` as a language-neutral contract emitted by frontends and consumed by common backend stages. The common backend MUST consume `IRBackend` and associated common compiler model types only; it MUST NOT consume PBS AST, PBS tokens, PBS parser structures, PBS semantic objects, or any equivalent language-owned frontend object.
|
||||
|
||||
This decision does not authorize a redesign of the existing IR model. The correct implementation direction is to preserve the working boundary, document it as common, and remove or justify residual PBS-specific leaks.
|
||||
|
||||
## Rationale
|
||||
|
||||
The existing model already has the right operational shape:
|
||||
|
||||
1. Frontends lower their language-specific source models into `IRBackend`.
|
||||
2. The common backend lowers `IRBackend` into IRVM and bytecode-facing structures.
|
||||
3. PBS-specific parsing, binding, and semantic analysis remain upstream of the handoff.
|
||||
|
||||
Renaming or redesigning the model without a concrete leak would create churn and risk. The useful work is to make the existing boundary explicit, testable, and resistant to future PBS-by-default assumptions.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### Common Contract
|
||||
|
||||
The public `IRBackend` contract MAY include common compiler concepts required by executable backend lowering:
|
||||
|
||||
- source identity and spans;
|
||||
- modules and module ids;
|
||||
- callable identities, signatures, names, arity, and type-shape surfaces;
|
||||
- executable functions;
|
||||
- instruction kinds and instruction metadata;
|
||||
- globals and global origins;
|
||||
- synthetic executable functions and synthetic origins;
|
||||
- host-call metadata;
|
||||
- intrinsic metadata;
|
||||
- reserved metadata required for backend lowering;
|
||||
- required runtime or platform capabilities.
|
||||
|
||||
The contract MUST express these concepts in language-neutral terms. When a concept currently originates from PBS, the common contract MUST describe the backend obligation rather than the PBS syntax or PBS semantic rule that produced it.
|
||||
|
||||
### Forbidden Coupling
|
||||
|
||||
The common backend contract MUST NOT expose or require:
|
||||
|
||||
- `PbsExpression`, `PbsStatement`, `PbsToken`, or equivalent PBS-owned syntax objects;
|
||||
- PBS parser cursors, parse contexts, parse nodes, or token kinds;
|
||||
- PBS semantic validator internals;
|
||||
- PBS editorial or language-service objects;
|
||||
- any type under a PBS frontend package as part of the public backend handoff.
|
||||
|
||||
Equivalent objects from future frontends are also forbidden at the common backend boundary.
|
||||
|
||||
### Naming and Documentation
|
||||
|
||||
The codebase MAY keep the name `IRBackend`.
|
||||
|
||||
PBS-specific names inside common backend code, specs, tests, or diagnostics MUST be audited. If the behavior is actually common, naming and documentation SHOULD be changed to neutral language. If a PBS-specific name remains, the implementation plan MUST record why it is intentionally PBS-specific and why it does not belong to the common contract.
|
||||
|
||||
Examples of items that need audit include lifecycle, published entrypoint, wrapper, boot guard, and capability wording. These may be common executable obligations even if PBS is currently the only frontend producing them.
|
||||
|
||||
### Spec Ownership
|
||||
|
||||
General compiler specs MUST own the common `IRBackend -> IRVM` contract and backend obligations.
|
||||
|
||||
PBS specs MUST own only the PBS-specific lowering path into `IRBackend`: how PBS AST and PBS semantics are admitted, rejected, or translated into the common handoff.
|
||||
|
||||
PBS specs MUST NOT be the canonical source for common backend behavior once that behavior is expressible independently of PBS.
|
||||
|
||||
### Tests and Guardrails
|
||||
|
||||
Implementation plans derived from this decision MUST include focused guardrails:
|
||||
|
||||
- a test that constructs executable `IRBackend` directly without the PBS parser and lowers it through the backend;
|
||||
- an architectural test or equivalent check that common backend code does not depend on `p.studio.compiler.pbs`;
|
||||
- a negative check preventing PBS AST/token/semantic types from becoming part of the public `IRBackend` contract;
|
||||
- regression coverage for any renamed or neutralized lifecycle/entrypoint validation.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Do not rename `IRBackend` for aesthetic reasons.
|
||||
- Do not rewrite the IR model unless a concrete language-owned dependency is found.
|
||||
- Do not redesign `IRBackend -> IRVM` lowering as part of this decision.
|
||||
- Do not implement serialization as part of this decision.
|
||||
- Do not fold the serializable IR discussion or synthetic test frontend discussion into this decision.
|
||||
- Do not weaken accepted backend behavior while neutralizing names or specs.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- Specs:
|
||||
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
- Code:
|
||||
- `prometeu-compiler/prometeu-frontend-api/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/...`
|
||||
- Tests:
|
||||
- `IRBackendExecutableContractTest`
|
||||
- `LowerToIRVMServiceTest`
|
||||
- architectural tests for backend/frontend package boundaries
|
||||
- Docs:
|
||||
- any compiler-general or PBS spec text that describes `IRBackend` as PBS-owned instead of common.
|
||||
|
||||
## References
|
||||
|
||||
- Agenda: `discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md`
|
||||
- Related lessons:
|
||||
- `discussion/lessons/DSC-0054-multi-frontend-provider-contract/LSN-0055-static-frontend-providers-before-plugin-architecture.md`
|
||||
- `discussion/lessons/DSC-0055-multi-frontend-compiler-vs-language-services/LSN-0056-compile-first-frontends-with-optional-editorial-capabilities.md`
|
||||
- `discussion/lessons/DSC-0056-multi-frontend-remove-pbs-branches/LSN-0058-generic-frontend-editorial-contract-for-lsp.md`
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-07-15: Initial draft from AGD-0060.
|
||||
@ -0,0 +1,100 @@
|
||||
---
|
||||
id: PLN-0117
|
||||
ticket: multi-frontend-frontend-backend-contract
|
||||
title: Common IRBackend contract specs
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0043]
|
||||
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Worker: Spec Editorial Worker.
|
||||
|
||||
Domain owner: `compiler/general`, with explicit propagation to `compiler/pbs`.
|
||||
|
||||
DEC-0043 accepts the current `IRBackend` shape as the common frontend-to-backend executable handoff. This plan propagates that decision into specs and conformance docs so the common backend is no longer described as PBS-owned by implication.
|
||||
|
||||
## Objective
|
||||
|
||||
Update compiler-general and PBS specs to state that `IRBackend` is the language-neutral executable handoff emitted by frontends and consumed by common backend stages, while PBS specs describe only PBS-specific admission and lowering into that handoff.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0043`.
|
||||
- No code implementation is required before this plan.
|
||||
- PLN-0118 may run after or in parallel, but this plan owns normative wording and spec ownership.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Update `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` so it is clearly a compiler-general backend contract, not a PBS backend contract.
|
||||
- Update `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md` to include the common handoff obligations and the required guardrail tests.
|
||||
- Update `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` so it owns PBS lowering into `IRBackend`, not the common backend contract itself.
|
||||
- Replace PBS-specific wording in common spec text when the obligation is actually common: executable handoff, lifecycle wrapper, published entrypoint, boot guard, spans, capabilities, host calls, intrinsics.
|
||||
- Add explicit forbidden-coupling language: common backend specs must not require PBS AST, tokens, parser structures, semantic validators, editorial objects, or equivalent objects from future frontends.
|
||||
- Preserve existing behavior and conformance obligations.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not rename `IRBackend`.
|
||||
- Do not redesign the IR model.
|
||||
- Do not change `IRBackend -> IRVM` lowering behavior.
|
||||
- Do not define serialization.
|
||||
- Do not resolve synthetic test frontend design beyond referencing the need for guardrails already required by DEC-0043.
|
||||
- Do not move PBS-specific language rules into compiler-general specs.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Audit current spec ownership.
|
||||
- Read `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
||||
- Read `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.
|
||||
- Read `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`.
|
||||
- Mark each `IRBackend` obligation as common backend, PBS lowering, or test/conformance bookkeeping.
|
||||
|
||||
2. Rewrite the compiler-general lowering spec.
|
||||
- Change the title and introduction if they imply PBS ownership.
|
||||
- State that `IRBackend` is the common executable frontend-to-backend handoff.
|
||||
- Describe allowed common concepts: source identity, spans, modules, callables, executable functions, instruction metadata, globals, synthetic functions, host/intrinsic metadata, reserved metadata, capabilities.
|
||||
- Describe forbidden language-owned inputs at the backend boundary.
|
||||
- Express lifecycle, published entrypoint, boot guard, and capability obligations in neutral backend terms.
|
||||
|
||||
3. Rewrite the PBS lowering spec boundary.
|
||||
- Keep PBS-specific parser, AST, semantic, source admission, and lowering rules in the PBS spec.
|
||||
- State that PBS emits the common `IRBackend` contract rather than owning it.
|
||||
- Replace any common backend obligation duplicated in PBS with a reference to the compiler-general spec unless PBS-specific lowering detail is required.
|
||||
|
||||
4. Update the conformance matrix.
|
||||
- Add or adjust rows for DEC-0043 obligations.
|
||||
- Reference PLN-0118 tests for direct manual `IRBackend` lowering, backend package independence from `p.studio.compiler.pbs`, and public-contract negative checks.
|
||||
- Keep existing PBS conformance rows only where they verify PBS lowering obligations.
|
||||
|
||||
5. Cross-check terminology.
|
||||
- Search specs for wording that says or implies PBS owns common backend behavior.
|
||||
- Leave PBS terms only when they describe PBS source or PBS lowering before the handoff.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Compiler-general specs state that `IRBackend` is the common frontend-to-backend executable handoff.
|
||||
- [ ] Compiler-general specs do not describe common backend behavior as PBS-owned.
|
||||
- [ ] PBS lowering specs describe how PBS emits `IRBackend` and defer common backend obligations to compiler-general specs.
|
||||
- [ ] Forbidden coupling is explicit for PBS AST, tokens, parser structures, semantic objects, editorial objects, and future frontend equivalents.
|
||||
- [ ] Lifecycle, published entrypoint, boot guard, spans, and capabilities are written in neutral terms when they are backend obligations.
|
||||
- [ ] Conformance matrix maps DEC-0043 obligations to tests or planned tests without weakening existing coverage.
|
||||
|
||||
## Tests
|
||||
|
||||
Validation:
|
||||
|
||||
- Run `discussion validate`.
|
||||
- Run a docs/spec search for `PBS IRBackend`, `PBS backend`, and similar phrases in compiler-general specs; remaining occurrences must be intentional and tied to PBS-specific references.
|
||||
- If the repository has markdown lint or docs validation, run the established command.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
- `discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md`
|
||||
@ -0,0 +1,114 @@
|
||||
---
|
||||
id: PLN-0118
|
||||
ticket: multi-frontend-frontend-backend-contract
|
||||
title: Common IRBackend backend guardrails
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0043]
|
||||
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Worker: Code Implementation Worker.
|
||||
|
||||
Domain owner: `compiler/general`, with impact on PBS frontend tests only where PBS currently emits `IRBackend`.
|
||||
|
||||
DEC-0043 accepts `IRBackend` as the common frontend-to-backend executable handoff and requires guardrails preventing PBS AST, tokens, parser state, semantic internals, or future language-owned frontend objects from entering the common backend contract.
|
||||
|
||||
## Objective
|
||||
|
||||
Add focused code and test guardrails that prove the common backend can lower manually constructed `IRBackend` without PBS and cannot accidentally depend on PBS frontend packages or PBS-owned public contract types.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0043`.
|
||||
- PLN-0117 should define the final spec wording before conformance matrix rows are finalized, but this plan can implement tests in parallel.
|
||||
- Existing tests named in DEC-0043: `IRBackendExecutableContractTest` and `LowerToIRVMServiceTest`.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Audit common backend and frontend API packages for imports or public contract references to `p.studio.compiler.pbs`.
|
||||
- Rename or neutralize PBS-specific helper names in common backend code only when behavior is common. The expected example is lifecycle validation wording in `LowerToIRVMService`.
|
||||
- Add a backend test that constructs a valid executable `IRBackend` manually, without PBS parser/compiler helpers, and lowers it through `LowerToIRVMService`.
|
||||
- Add an architectural test or equivalent regression check that common backend code does not import or depend on `p.studio.compiler.pbs`.
|
||||
- Add a public-contract negative check that `IRBackend` model classes do not expose PBS AST, token, parser, semantic, or editorial types.
|
||||
- Preserve all existing executable lowering behavior.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not rename `IRBackend`.
|
||||
- Do not redesign `IRBackend`, `IRBackendFile`, or `IRBackendExecutableFunction`.
|
||||
- Do not redesign `IRBackend -> IRVM` lowering.
|
||||
- Do not implement IR serialization.
|
||||
- Do not introduce the synthetic test frontend from a separate discussion.
|
||||
- Do not change PBS language semantics or parser behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Audit package dependencies.
|
||||
- Search `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend`.
|
||||
- Search `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models`.
|
||||
- Confirm there are no imports of `p.studio.compiler.pbs` in common backend or `IRBackend` public model classes.
|
||||
|
||||
2. Neutralize common backend naming.
|
||||
- Inspect `LowerToIRVMService`.
|
||||
- Rename common helper names that imply PBS ownership when the behavior is actually common. The known target is `validatePbsLifecycleStructure`, which should become neutral lifecycle/executable-entrypoint validation language.
|
||||
- Update related test method names and expected diagnostic messages only when they are common backend wording.
|
||||
- Do not change the validation logic unless a test proves behavior was incorrectly tied to PBS.
|
||||
|
||||
3. Add direct backend lowering coverage.
|
||||
- Extend `LowerToIRVMServiceTest` or add a focused backend test in the same test package.
|
||||
- Build `IRBackend` manually using common model types, module/callable/intrinsic pools, executable functions, spans, and metadata required by the backend.
|
||||
- Lower it through `LowerToIRVMService`.
|
||||
- Assert the produced IRVM/bytecode-facing result is valid and does not require PBS parser or PBS frontend services.
|
||||
|
||||
4. Add architectural dependency guard.
|
||||
- Add a JUnit test in an appropriate compiler/backend or build-pipeline test package that scans compiled classes or source imports for forbidden `p.studio.compiler.pbs` dependencies in common backend packages.
|
||||
- The check must fail if common backend code imports PBS frontend packages.
|
||||
- If the project already has an architectural-test pattern, follow it; otherwise use a small source-tree scan test scoped to known common backend source roots.
|
||||
|
||||
5. Add public-contract type guard.
|
||||
- Add or extend a test in `prometeu-frontend-api` test scope, likely near `IRBackendExecutableContractTest`.
|
||||
- Inspect public fields, record components, method return types, constructor parameters, and nested public model types for forbidden PBS package names.
|
||||
- Fail if any `IRBackend` public contract type exposes `p.studio.compiler.pbs`.
|
||||
|
||||
6. Update conformance references if PLN-0117 has already landed.
|
||||
- Ensure test names match conformance matrix entries.
|
||||
- If PLN-0117 is not landed yet, record the final test names for the spec plan.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Common backend source code has no dependency on `p.studio.compiler.pbs`.
|
||||
- [ ] Public `IRBackend` contract types expose no PBS AST, token, parser, semantic, or editorial classes.
|
||||
- [ ] A backend test manually constructs executable `IRBackend` and lowers it without invoking PBS parser or PBS frontend compiler services.
|
||||
- [ ] Common backend lifecycle/entrypoint validation names and diagnostics are neutral where the behavior is common.
|
||||
- [ ] Existing PBS frontend lowering tests still pass.
|
||||
- [ ] Existing backend lowering tests still pass.
|
||||
- [ ] No IR model redesign or `IRBackend` rename was introduced.
|
||||
|
||||
## Tests
|
||||
|
||||
Required automated tests:
|
||||
|
||||
- `IRBackendExecutableContractTest` or equivalent public-contract guard test.
|
||||
- `LowerToIRVMServiceTest` or equivalent direct manual `IRBackend` lowering test.
|
||||
- Architectural/backend dependency guard for `p.studio.compiler.pbs` imports in common backend source.
|
||||
- Existing PBS frontend tests that prove PBS still emits valid `IRBackend`.
|
||||
|
||||
Validation commands:
|
||||
|
||||
- Run the focused Gradle test tasks for `prometeu-frontend-api`, `prometeu-build-pipeline`, and PBS frontend modules.
|
||||
- Run the broader compiler test task if available and practical.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`
|
||||
- Any new architectural test file under the appropriate compiler test module.
|
||||
- PBS frontend tests only if expected names or neutralized backend diagnostics require updates.
|
||||
- `discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md`
|
||||
Loading…
x
Reference in New Issue
Block a user