From 26c69d56604acbe050560db328fb6a97830efa0f Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 15 Jul 2026 12:07:07 +0100 Subject: [PATCH 1/4] Stable contract FE/BE --- discussion/index.ndjson | 4 +- ...ulti-frontend-frontend-backend-contract.md | 45 ++++-- ...mmon-irbackend-frontend-backend-handoff.md | 145 ++++++++++++++++++ ...LN-0117-common-irbackend-contract-specs.md | 100 ++++++++++++ ...118-common-irbackend-backend-guardrails.md | 114 ++++++++++++++ 5 files changed, 391 insertions(+), 17 deletions(-) create mode 100644 discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md create mode 100644 discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md create mode 100644 discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 0e5a5b24..ea60bf8a 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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"}]} diff --git a/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md b/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md index 2ba5ade4..c36ef6ec 100644 --- a/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md +++ b/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md @@ -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. diff --git a/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md b/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md new file mode 100644 index 00000000..93adade4 --- /dev/null +++ b/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md @@ -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. diff --git a/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md b/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md new file mode 100644 index 00000000..1215794e --- /dev/null +++ b/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md @@ -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` diff --git a/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md b/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md new file mode 100644 index 00000000..8183639b --- /dev/null +++ b/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.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` -- 2.47.2 From bde999f1fe53c996fb3174cbb12501299523c507 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 15 Jul 2026 12:10:10 +0100 Subject: [PATCH 2/4] implements PLN-0117 --- discussion/index.ndjson | 2 +- ...LN-0117-common-irbackend-contract-specs.md | 14 +++--- .../13. Lowering IRBackend Specification.md | 37 +++++++------- ...RBackend to IRVM Lowering Specification.md | 50 ++++++++++++++++--- ...Backend Spec-to-Test Conformance Matrix.md | 11 ++-- 5 files changed, 77 insertions(+), 37 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index ea60bf8a..503cee44 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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":"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-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":"done","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"}]} diff --git a/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md b/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md index 1215794e..4260aa41 100644 --- a/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md +++ b/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md @@ -2,7 +2,7 @@ id: PLN-0117 ticket: multi-frontend-frontend-backend-contract title: Common IRBackend contract specs -status: open +status: done created: 2026-07-15 ref_decisions: [DEC-0043] tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend] @@ -77,12 +77,12 @@ Included: ## 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. +- [x] Compiler-general specs state that `IRBackend` is the common frontend-to-backend executable handoff. +- [x] Compiler-general specs do not describe common backend behavior as PBS-owned. +- [x] PBS lowering specs describe how PBS emits `IRBackend` and defer common backend obligations to compiler-general specs. +- [x] Forbidden coupling is explicit for PBS AST, tokens, parser structures, semantic objects, editorial objects, and future frontend equivalents. +- [x] Lifecycle, published entrypoint, boot guard, spans, and capabilities are written in neutral terms when they are backend obligations. +- [x] Conformance matrix maps DEC-0043 obligations to tests or planned tests without weakening existing coverage. ## Tests diff --git a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md index 907040c0..43b7ea64 100644 --- a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md +++ b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md @@ -1,13 +1,13 @@ # PBS Lowering IRBackend Specification -Status: Draft v1 (Frontend Scope + Backend Handoff Addendum) -Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile`, plus executable-backend handoff obligations at this boundary +Status: Draft v1 (PBS Frontend Scope + Common Handoff Emission) +Applies to: first lowering boundary from bound PBS frontend model into the common `IRBackend`/`IRBackendFile` handoff ## 1. Purpose -This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`. +This document defines the normative frontend lowering contract from PBS source semantics to the common `IRBackend` handoff. -Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve. +Its purpose is to keep PBS lowering deterministic while preserving the common frontend-to-backend contract owned by compiler-general backend specs. ## 2. Scope @@ -18,7 +18,7 @@ This document defines: - semantic obligations preserved in `IRBackend`, - deterministic rejection behavior for unsupported frontend-lowering forms, - diagnostics attribution obligations for lowering failures in frontend scope, -- executable-backend handoff obligations at the `IRBackend` boundary, +- PBS obligations for emitting the common executable `IRBackend` handoff, - and backend-owned symbolic lowering obligations for asset-facing references. This document does not define: @@ -26,7 +26,8 @@ This document does not define: - VM lowering (`IRVM`), - bytecode/PBX mapping, - runtime execution behavior, -- verifier/loader internals. +- verifier/loader internals, +- or common backend ownership of the `IRBackend -> IRVM` contract. Those concerns belong to shared acceptance specs under `docs/specs/compiler`. @@ -75,9 +76,9 @@ When the active source slice depends on a backend-owned symbolic surface such as - the frontend must not query domain services directly to discover operational assets; - and lowering must preserve enough identity for the backend to complete final operational resolution. -## 6. IRBackend Preserved Obligations +## 6. PBS IRBackend Emission Obligations -For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum: +For each admitted PBS source unit and callable in the current lowering slice, PBS lowering must emit `IRBackend` that preserves at minimum: 1. callable identity (name/category as applicable), 2. callable arity, @@ -93,6 +94,8 @@ Lowering must not collapse source categories in a way that erases required decla The normative contract is obligation-based, not tied to one mandatory in-memory class graph. +`IRBackend` itself is the common frontend-to-backend executable handoff. This PBS spec owns only the PBS-specific admission and translation path into that handoff. Common backend rules for consuming `IRBackend` are owned by `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`. + ## 7. Deterministic Rejection Policy If a source form is outside current frontend-lowering support: @@ -111,7 +114,7 @@ For multi-module builds, lowering admission must apply dependency-scoped fail-fa ## 8. Conformance Boundary -`IRBackend` is the first lowering boundary (frontend responsibility). +PBS emission into `IRBackend` is the first PBS lowering boundary (frontend responsibility). Conformance-valid claims at this boundary require Gate U evidence from `docs/specs/compiler/13. Conformance Test Specification.md`. @@ -148,9 +151,9 @@ This document is healthy when: 3. deterministic rejection policy is explicit and test-backed, 4. and scope boundaries with general/backend acceptance specs are explicit. -## 12. Executable Backend Handoff Addendum (v1) +## 12. PBS Executable Handoff Emission Obligations (v1) -For executable backends, the `IRBackend` output from this frontend boundary must satisfy the additional handoff obligations below. +For executable backends, PBS lowering must emit `IRBackend` satisfying the additional handoff obligations below before common backend lowering starts. ### 12.1 Callable obligations @@ -170,7 +173,7 @@ Each executable callsite in `IRBackend` must be classified into exactly one cate 2. `CALL_HOST`, 3. `CALL_INTRINSIC`. -Backend lowering must not infer this category by textual heuristics. +PBS lowering must not leave this category for backend inference by textual heuristics. ### 12.3 Host-backed metadata obligations @@ -187,11 +190,11 @@ When a host-backed callsite also depends on backend-owned symbolic asset lowerin - the frontend boundary MUST preserve which callsite argument is asset-facing; - for PBS v1 this asset-facing designation is carried by reserved host metadata `[AssetLowering(param = N)]`; - the preserved symbolic operand MUST remain attributable to a backend-provided `Addressable` identity; -- backend stages MUST be able to rewrite that symbolic operand into runtime-facing `asset_id` before the final low-level host path is emitted. +- common backend stages MUST be able to rewrite that symbolic operand into runtime-facing `asset_id` before the final low-level host path is emitted. When an expression statement leaves a materialized runtime value on the stack: -- `IRBackend` lowering MUST emit explicit discard behavior rather than relying on implicit backend stack cleanup; +- PBS lowering into `IRBackend` MUST emit explicit discard behavior rather than relying on implicit backend stack cleanup; - for single-slot materialized values this discard is represented by `POP`; - and the discard path MUST preserve stack-accounting validity for subsequent backend lowering stages. @@ -220,7 +223,7 @@ It does not replace: ### 12.7 Executable Lifecycle and Published Wrapper Obligation -For executable PBS frontends, backend handoff must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint. +For executable PBS frontends, PBS lowering must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint. At `IRBackend` emission time: @@ -230,8 +233,8 @@ At `IRBackend` emission time: - module init, - project init when present, - and the published frame wrapper, -2. the published frame wrapper must be the effective entrypoint identity handed to backend stages, +2. the published frame wrapper must be the effective entrypoint identity handed to common backend stages, 3. the userland callable marked with `[Frame]` must remain distinguishable as the logical frame root, 4. the wrapper must own final `FRAME_RET`, -5. backend stages must not reintroduce manifest-owned or `FrontendSpec`-owned nominal entrypoint authority, +5. common backend stages must not reintroduce manifest-owned or `FrontendSpec`-owned nominal entrypoint authority, 6. and hidden compiler-owned lifecycle state such as the boot guard must remain structurally distinguishable from user globals. diff --git a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md index 24470f49..b137119b 100644 --- a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md +++ b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md @@ -1,7 +1,7 @@ -# PBS IRBackend to IRVM Lowering Specification +# IRBackend to IRVM Lowering Specification Status: Draft v1 (Backend Baseline) -Applies to: executable-backend lowering from `IRBackend` handoff into `IRVM` +Applies to: executable-backend lowering from the common `IRBackend` handoff into `IRVM` ## 1. Purpose @@ -9,11 +9,14 @@ This document defines the normative lowering contract from executable `IRBackend Its purpose is to make backend lowering deterministic, reviewable, and compatible with runtime ISA/verification authority. +`IRBackend` is the common frontend-to-backend executable handoff. It is emitted by frontends and consumed by common backend stages. Backend lowering MUST NOT require PBS AST nodes, PBS tokens, PBS parser structures, PBS semantic objects, PBS editorial objects, or equivalent language-owned objects from future frontends. + ## 2. Scope This document defines: - required backend preconditions before `IRBackend -> IRVM` starts, +- allowed language-neutral `IRBackend` contract concepts at the backend boundary, - `IRVM` structural obligations needed before optimization/emission, - deterministic function-id assignment and control-flow lowering obligations, - callsite lowering obligations across function, host-backed, and VM-owned intrinsic paths, @@ -25,7 +28,8 @@ This document does not define: - binary PBX layout details, - loader patching internals, - runtime execution internals, -- or one mandatory optimizer implementation. +- one mandatory optimizer implementation, +- or frontend-specific lowering rules before `IRBackend` emission. ## 3. Authority and Precedence @@ -33,8 +37,8 @@ Normative precedence: 1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`) 2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`) -3. `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` -4. This document +3. This document +4. Frontend-specific lowering specifications, including `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` If a rule here conflicts with higher-precedence authorities, it is invalid. @@ -42,12 +46,38 @@ If a rule here conflicts with higher-precedence authorities, it is invalid. This document depends on: -- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` - `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md` - `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md` +- frontend-specific lowering specifications that emit the common `IRBackend` handoff - `15. Bytecode and PBX Mapping Specification.md` - `21. IRVM Optimization Pipeline Specification.md` +## 4.1 Common IRBackend Contract + +At this boundary, `IRBackend` may contain only language-neutral compiler concepts required by executable backend lowering: + +1. source identity and spans, +2. modules and module identifiers, +3. callable identities, signatures, names, arity, and type-shape surfaces, +4. executable functions, +5. instruction kinds and instruction metadata, +6. globals and global origins, +7. synthetic executable functions and synthetic origins, +8. host-call metadata, +9. intrinsic metadata, +10. reserved metadata required for backend lowering, +11. and required runtime or platform capabilities. + +The common backend contract MUST express these concepts as backend obligations, not as PBS syntax or PBS semantic rules. When a concept currently originates from PBS, the backend contract still owns only the language-neutral obligation carried by `IRBackend`. + +The common backend contract MUST NOT expose or require: + +1. `PbsExpression`, `PbsStatement`, `PbsToken`, or equivalent PBS-owned syntax objects, +2. PBS parser cursors, parse contexts, parse nodes, or token kinds, +3. PBS semantic validator internals, +4. PBS editorial or language-service objects, +5. or any type under a language frontend package as part of the public backend handoff. + ## 5. Backend Entry Preconditions Lowering from `IRBackend` to `IRVM` may start only when: @@ -104,6 +134,8 @@ For PBS executable lowering: - the wrapper path must contain final `FRAME_RET`, - and lowering must preserve that distinction through `IRVM`. +These PBS-facing names describe the current frontend source of the lifecycle structure. The backend-owned obligation is the neutral requirement that the compiler-selected published wrapper be the physical entrypoint and that lifecycle state remain explicit in `IRBackend`. + ## 9. Callsite Lowering Obligations ### 9.1 Function calls @@ -150,7 +182,7 @@ Before bytecode emission, backend must run structural pre-verification on lowere 7. and structural validity of host/intrinsic call forms. 8. and structural validity of backend-owned symbolic-to-operational rewrites such as `Addressable -> asset_id`. -For PBS host-backed asset calls in v1, this validation includes the rewrite selected by preserved host metadata such as `[AssetLowering(param = N)]`. +For host-backed asset calls in v1, this validation includes backend-owned symbolic-to-operational rewrites selected by preserved host metadata. PBS currently emits this designation from metadata such as `[AssetLowering(param = N)]`, but final operational resolution is a common backend obligation. This pre-verification does not replace runtime verifier authority. @@ -184,4 +216,6 @@ This document is healthy when: 1. `IRBackend -> IRVM` obligations are explicit and testable, 2. deterministic function/call/control-flow lowering rules are explicit, 3. mandatory pre-verification boundary is explicit, -4. and scope boundaries with optimization/emission specs are explicit. +4. common backend obligations are not described as owned by PBS, +5. frontend-specific lowering specs only own emission into `IRBackend`, +6. and scope boundaries with optimization/emission specs are explicit. diff --git a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md index 2cbb6586..88cf6ca7 100644 --- a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md +++ b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md @@ -3,7 +3,7 @@ Status: Draft v1 (Traceability Baseline) Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts -Last Updated: 2026-03-30 +Last Updated: 2026-07-15 ## 1. Purpose @@ -13,7 +13,7 @@ This matrix maps each normative backend MUST from: 2. `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` 3. `docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md` 4. `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md` -5. `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` (Section 12 addendum only) +5. `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` (PBS lowering obligations only) to concrete positive/negative test evidence and current status. @@ -56,6 +56,9 @@ to concrete positive/negative test evidence and current status. | G20-11.1 | Lowering rejection MUST be deterministic. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | same | pass | | | G20-11.2 | Diagnostics identity/phase MUST remain stable. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Stable rejection families are exercised. | | G20-11.3 | Source attribution MUST be preserved when source-actionable. | `LowerToIRVMPipelineStageTest#runMustAttachSourceAttributionForLoweringFailure`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | Stage-level failure now carries explicit `file/start/end` attribution for lowering errors. | +| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | +| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | +| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | | G21-5 | `OptimizeIRVM` MUST NOT be skipped in canonical pipeline order. | `BuilderPipelineServiceOrderTest#canonicalOrderMustContainOptimizeBetweenLowerAndEmit` | N/A | pass | Canonical stage order is enforced. | | G21-6.1 | Optimize input MUST satisfy lowering obligations/profile/structural validity. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMPipelineStageTest#runMustRejectUnsupportedVmProfile` | pass | Input validation occurs before pass execution. | | G21-6.2 | Optimize output MUST preserve semantics/contracts and remain emission-valid. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture`; `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Equivalence harness now validates on/off semantics and emission validity over CFG corpus with host/intrinsic paths. | @@ -74,7 +77,7 @@ to concrete positive/negative test evidence and current status. | G23-7.1 | `AnalysisSnapshot` MUST expose the minimum shared analysis contract. | `MainProjectPipelineIntegrationTest#analyzeShouldNotWriteProgramBytecode`; `BuilderPipelinePublicSurfaceTest#analysisSnapshotMustExposeMinimumSharedContract` | N/A | pass | Both executable and structural contract checks now cover the shared minimum analysis payload. | | G23-8.1 | Caller-specific configs/contexts MUST NOT redefine canonical stage semantics. | N/A | N/A | missing | Requires explicit multi-entrypoint composition tests once non-filesystem contexts are implemented. | | G23-9.1 | Legacy public `run` MUST be removed as the normative entrypoint and filesystem-default behavior MUST be expressed through `build`. | `BuilderPipelinePublicSurfaceTest#publicServiceSurfaceMustExposeExplicitEntrypointsAndNoPublicRun`; `MainProjectPipelineIntegrationTest#buildShouldWriteProgramBytecode` | N/A | partial | Public service coverage now proves `run` is no longer public and `build` is the filesystem artifact path, but the CLI composition path is not yet exercised by a dedicated automated test. | -| PBS13-12.0 | Executable backend handoff MUST satisfy addendum obligations. | `IRBackendExecutableContractTest` suite; `PBSFrontendPhaseServiceTest#shouldSynthesizePositiveTopic19FixtureAcrossFileInitProjectInitAndFrame` | `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticWrapperEntrypointIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenHiddenBootGuardIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticCallableOriginIsMissing` | pass | Row group `PBS13-12.x` details each obligation; topic 19 closure now includes lifecycle wrapper/guard/origin evidence. | +| PBS13-12.0 | PBS executable lowering MUST emit `IRBackend` satisfying frontend handoff obligations before common backend lowering. | `IRBackendExecutableContractTest` suite; `PBSFrontendPhaseServiceTest#shouldSynthesizePositiveTopic19FixtureAcrossFileInitProjectInitAndFrame` | `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticWrapperEntrypointIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenHiddenBootGuardIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticCallableOriginIsMissing` | pass | Row group `PBS13-12.x` verifies PBS emission into the common handoff; common backend ownership is covered by G20 rows. | | PBS13-12.1.1 | Callable identity MUST be preserved at handoff. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableFunctionOrderDeterministically` | N/A | pass | | | PBS13-12.1.2 | Observable callable signature MUST be preserved at handoff. | `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass | | | PBS13-12.1.3 | Callable category MUST be preserved at handoff. | `PbsFrontendCompilerTest#shouldLowerExecutableFunctionsWithCallsiteCategories` | N/A | pass | | @@ -103,7 +106,7 @@ to concrete positive/negative test evidence and current status. 1. Any backend PR that changes conformance-relevant behavior in FE/BE pipeline MUST update this matrix. 2. If requirement coverage changes, update: mapped tests, status, and `Last Updated` date. -3. New normative MUSTs in specs `19/20/21` or PBS `13` addendum MUST add a new matrix row before merge. +3. New normative MUSTs in specs `19/20/21` or PBS `13` lowering obligations MUST add a new matrix row before merge. 4. Conformance-relevant FE/BE code paths for hard-gate are: - `prometeu-compiler/prometeu-build-pipeline/` - `prometeu-compiler/frontends/prometeu-frontend-pbs/` -- 2.47.2 From e8079b67fb564dd9f916b23779887cebe3c97aec Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 15 Jul 2026 12:13:40 +0100 Subject: [PATCH 3/4] implements PLN-0118 --- discussion/index.ndjson | 2 +- ...118-common-irbackend-backend-guardrails.md | 16 ++-- ...Backend Spec-to-Test Conformance Matrix.md | 6 +- .../backend/irvm/LowerToIRVMService.java | 4 +- .../backend/irvm/LowerToIRVMServiceTest.java | 29 +++++++ .../BackendConformanceMatrixSpecTest.java | 3 + .../specs/CommonBackendArchitectureTest.java | 60 ++++++++++++++ .../IRBackendExecutableContractTest.java | 79 +++++++++++++++++++ 8 files changed, 185 insertions(+), 14 deletions(-) create mode 100644 prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 503cee44..caacab81 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -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":"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":"done","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-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":"done","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":"done","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"}]} diff --git a/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md b/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md index 8183639b..9e570501 100644 --- a/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md +++ b/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md @@ -2,7 +2,7 @@ id: PLN-0118 ticket: multi-frontend-frontend-backend-contract title: Common IRBackend backend guardrails -status: open +status: done created: 2026-07-15 ref_decisions: [DEC-0043] tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend] @@ -81,13 +81,13 @@ Included: ## 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. +- [x] Common backend source code has no dependency on `p.studio.compiler.pbs`. +- [x] Public `IRBackend` contract types expose no PBS AST, token, parser, semantic, or editorial classes. +- [x] A backend test manually constructs executable `IRBackend` and lowers it without invoking PBS parser or PBS frontend compiler services. +- [x] Common backend lifecycle/entrypoint validation names and diagnostics are neutral where the behavior is common. +- [x] Existing PBS frontend lowering tests still pass. +- [x] Existing backend lowering tests still pass. +- [x] No IR model redesign or `IRBackend` rename was introduced. ## Tests diff --git a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md index 88cf6ca7..43f970d7 100644 --- a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md +++ b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md @@ -40,6 +40,9 @@ to concrete positive/negative test evidence and current status. | G19-5.2.6 | Gate S-I MUST reject missing capability at load-time. | N/A | `BackendGateIIntegrationTest#gateI_rejectMissingCapability` | pass | | | G19-5.2.7 | Gate S-I MUST cover valid VM-owned intrinsic path. | `BackendGateIIntegrationTest#gateI_validIntrinsicPath` | N/A | pass | | | G19-5.2.8 | Gate S-I MUST cover repeatability across runtime line. | `RuntimeBackedCompatibilityAdapterTest#checkMustPassInStrictModeWhenRuntimeCommandIsValid`; `RuntimeBackedCompatibilityAdapterTest#checkMustBeRepeatableAcrossDeclaredRuntimeLinesInStrictMode` | `RuntimeBackedCompatibilityAdapterTest#checkMustFailInStrictModeWhenRuntimeCommandIsUnavailable` | pass | Multi-line repeatability is asserted with strict runtime-backed checks over distinct declared runtime lines. | +| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | pass | Direct backend lowering from manually constructed common IRBackend proves PBS parser/frontend services are not required. | +| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | pass | Source-level architectural guard rejects PBS frontend imports in common backend packages. | +| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | pass | Reflection guard covers public contract fields, constructors, methods, and record components. | | G20-6.2 | `IRVM_EXT` MUST declare structural metadata (`pops/pushes/is_branch/is_terminator`). | `IRVMValidatorTest#validateMustApplyStructuralMetadataForCustomInternalExtension`; `IRVMValidatorTest#validateMustRejectCustomInternalExtensionWhenStructuralMetadataUnderflowsStack`; `IRVMOp` record contract (`pops/pushes/branch/terminator/internal`) | N/A | pass | Dedicated extension fixtures now assert structural metadata is consumed by validation behavior. | | G20-6.3 | `IRVM_EXT` MUST be eliminable before bytecode emission. | `OptimizeIRVMServiceTest#optimizeDefaultPassesMustEliminateUnreachableInternalExtensionBeforeEmission` | `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemain`; `EmitBytecodePipelineStageTest#runMustFailWhenInternalOpcodesRemainEvenWithNonEmptyEmissionPlan`; `IRVMValidatorTest#validateMustRejectInternalOpcodeWhenConfigured` | pass | Optimizer elimination path and emit-stage hard rejection path are both covered. | | G20-6.4 | IRVM MUST preserve per-function slot and identity headers. | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | `IRVMProgramTest#constructorMustRejectModuleAndEmissionPlanMismatch` | pass | Header mismatch is rejected deterministically. | @@ -56,9 +59,6 @@ to concrete positive/negative test evidence and current status. | G20-11.1 | Lowering rejection MUST be deterministic. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | same | pass | | | G20-11.2 | Diagnostics identity/phase MUST remain stable. | `BackendSafetyGateSUTest#lowerStageMustExposeDeterministicFailureCodeForSameInvalidInput` | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically` | pass | Stable rejection families are exercised. | | G20-11.3 | Source attribution MUST be preserved when source-actionable. | `LowerToIRVMPipelineStageTest#runMustAttachSourceAttributionForLoweringFailure`; `LowerToIRVMServiceTest#lowerMustMapHostAndIntrinsicCallsites` | `LowerToIRVMServiceTest#lowerMustRejectMissingCallee` | pass | Stage-level failure now carries explicit `file/start/end` attribution for lowering errors. | -| G20-4.1.1 | `IRBackend` MUST be the common frontend-to-backend executable handoff. | `LowerToIRVMServiceTest#lowerMustAcceptManuallyConstructedCommonIRBackend` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | -| G20-4.1.2 | Common backend code MUST NOT depend on `p.studio.compiler.pbs`. | `CommonBackendArchitectureTest#commonBackendMustNotImportPbsFrontendPackages` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | -| G20-4.1.3 | Public `IRBackend` contract MUST NOT expose PBS AST, token, parser, semantic, or editorial types. | `IRBackendExecutableContractTest#publicIRBackendContractMustNotExposePbsTypes` | N/A | missing | Required by DEC-0043; PLN-0118 adds the named evidence. | | G21-5 | `OptimizeIRVM` MUST NOT be skipped in canonical pipeline order. | `BuilderPipelineServiceOrderTest#canonicalOrderMustContainOptimizeBetweenLowerAndEmit` | N/A | pass | Canonical stage order is enforced. | | G21-6.1 | Optimize input MUST satisfy lowering obligations/profile/structural validity. | `OptimizeIRVMPipelineStageTest#runMustAcceptSupportedNonDefaultVmProfile` | `OptimizeIRVMPipelineStageTest#runMustRejectUnsupportedVmProfile` | pass | Input validation occurs before pass execution. | | G21-6.2 | Optimize output MUST preserve semantics/contracts and remain emission-valid. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture`; `EmitBytecodePipelineStageTest#runMustEmitBytecodeWhenPreconditionsAreSatisfied` | `OptimizeIRVMServiceTest#optimizeMustRejectPassThatMutatesVmProfile` | pass | Equivalence harness now validates on/off semantics and emission validity over CFG corpus with host/intrinsic paths. | diff --git a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java index bfc62e20..4703fe8d 100644 --- a/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java +++ b/prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java @@ -40,7 +40,7 @@ public class LowerToIRVMService { "IRBackend has no executable functions"); } - validatePbsLifecycleStructure(backend); + validateCommonLifecycleStructure(backend); final var ordered = orderFunctions(backend); final var funcIdByCallableId = new HashMap(); for (var i = 0; i < ordered.size(); i++) { @@ -499,7 +499,7 @@ public class LowerToIRVMService { return ReadOnlyList.wrap(ordered); } - private void validatePbsLifecycleStructure(final IRBackend backend) { + private void validateCommonLifecycleStructure(final IRBackend backend) { if (backend.getSyntheticFunctions().isEmpty()) { return; } diff --git a/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java index bec0f3fe..51a4bbf9 100644 --- a/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java +++ b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java @@ -229,6 +229,35 @@ class LowerToIRVMServiceTest { assertTrue(emissionOps.stream().allMatch(op -> op.span() != null)); } + @Test + void lowerMustAcceptManuallyConstructedCommonIRBackend() { + final var backend = IRBackend.builder() + .entryPointCallableName("tick") + .entryPointModuleId(new ModuleId(0)) + .modulePool(ReadOnlyList.from(new ModuleReference("game", ReadOnlyList.from("runtime")))) + .executableFunctions(ReadOnlyList.from( + fnWithModule("tick", "game/runtime", 0, 10, ReadOnlyList.from( + callHost("timer", "poll", 1, 0, 0), + callIntrinsic("input.pad", 1, 0), + callFuncWithExpected("game/runtime", "helper", 20, 0, 0), + ret())), + fnWithModule("helper", "game/runtime", 0, 20, ReadOnlyList.from( + ret())))) + .intrinsicPool(ReadOnlyList.from(new IntrinsicReference("input.pad", 1))) + .build(); + + final var lowered = new LowerToIRVMService().lower(backend); + + assertEquals(2, lowered.module().functions().size()); + assertEquals("tick", lowered.module().functions().getFirst().name()); + final var instructions = lowered.module().functions().getFirst().instructions(); + assertEquals(IRVMOp.HOSTCALL, instructions.get(0).op()); + assertEquals(IRVMOp.INTRINSIC, instructions.get(1).op()); + assertEquals(IRVMOp.CALL, instructions.get(2).op()); + assertEquals(1, instructions.get(2).immediate()); + assertEquals(IRVMOp.RET, instructions.get(3).op()); + } + @Test void lowerMustRejectUnterminatedFunction() { final var backend = IRBackend.builder() diff --git a/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/BackendConformanceMatrixSpecTest.java b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/BackendConformanceMatrixSpecTest.java index a1f0ee72..46c847b0 100644 --- a/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/BackendConformanceMatrixSpecTest.java +++ b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/BackendConformanceMatrixSpecTest.java @@ -36,6 +36,9 @@ class BackendConformanceMatrixSpecTest { "G19-5.2.6", "G19-5.2.7", "G19-5.2.8", + "G20-4.1.1", + "G20-4.1.2", + "G20-4.1.3", "G20-6.2", "G20-6.3", "G20-6.4", diff --git a/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java new file mode 100644 index 00000000..e4fd1faf --- /dev/null +++ b/prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java @@ -0,0 +1,60 @@ +package p.studio.compiler.specs; + +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; + +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.fail; + +class CommonBackendArchitectureTest { + private static final String BACKEND_SOURCE_ROOT = + "prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend"; + private static final String FORBIDDEN_PBS_PACKAGE = "p.studio.compiler.pbs"; + + @Test + void commonBackendMustNotImportPbsFrontendPackages() throws IOException { + final var backendRoot = locateRepoRoot().resolve(BACKEND_SOURCE_ROOT); + final var violations = new ArrayList(); + + try (final var paths = Files.walk(backendRoot)) { + paths.filter(path -> path.toString().endsWith(".java")) + .forEach(path -> assertNoPbsImport(path, violations)); + } + + assertTrue( + violations.isEmpty(), + "common backend must not import PBS frontend packages: " + violations); + } + + private static void assertNoPbsImport( + final Path path, + final ArrayList violations) { + try { + final var content = Files.readString(path); + if (content.contains("import " + FORBIDDEN_PBS_PACKAGE) + || content.contains("import static " + FORBIDDEN_PBS_PACKAGE)) { + violations.add(locateRepoRoot().relativize(path).toString()); + } + } catch (IOException e) { + throw new IllegalStateException("failed to read source file: " + path, e); + } + } + + private static Path locateRepoRoot() { + var cursor = Path.of(System.getProperty("user.dir")).toAbsolutePath().normalize(); + while (cursor != null) { + final var hasDocs = Files.isDirectory(cursor.resolve("docs/specs/compiler")); + final var hasCompiler = Files.isDirectory(cursor.resolve("prometeu-compiler")); + if (hasDocs && hasCompiler) { + return cursor; + } + cursor = cursor.getParent(); + } + fail("could not locate repository root from working directory"); + throw new IllegalStateException("unreachable"); + } +} diff --git a/prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java b/prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java index 82628bd7..842dffb2 100644 --- a/prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java +++ b/prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java @@ -11,9 +11,75 @@ import p.studio.compiler.source.tables.IntrinsicReference; import p.studio.compiler.source.tables.ModuleReference; import p.studio.utilities.structures.ReadOnlyList; +import java.lang.reflect.Modifier; +import java.lang.reflect.Type; +import java.util.ArrayList; +import java.util.List; + import static org.junit.jupiter.api.Assertions.*; class IRBackendExecutableContractTest { + private static final String FORBIDDEN_PBS_PACKAGE = "p.studio.compiler.pbs"; + private static final List> PUBLIC_CONTRACT_TYPES = List.of( + IRBackend.class, + IRBackend.IRBackendAggregator.class, + IRBackendReader.class, + IRBackendFile.class, + IRBackendExecutableFunction.class, + IRBackendExecutableFunction.Instruction.class, + IRBackendExecutableFunction.InstructionKind.class, + IRBackendExecutableFunction.HostCallMetadata.class, + IRBackendExecutableFunction.IntrinsicCallMetadata.class, + IRFunction.class, + IRSyntheticFunction.class, + IRSyntheticCallableKind.class, + IRSyntheticOrigin.class, + IRGlobal.class, + IRGlobalOrigin.class, + IRGlobalVisibility.class, + IRHiddenGlobalKind.class, + IRReservedMetadata.class, + IRReservedMetadata.HostMethodBinding.class, + IRReservedMetadata.BuiltinTypeSurface.class, + IRReservedMetadata.BuiltinFieldSurface.class, + IRReservedMetadata.IntrinsicSurface.class, + IRReservedMetadata.BuiltinConstSurface.class); + + @Test + void publicIRBackendContractMustNotExposePbsTypes() { + final var violations = new ArrayList(); + + for (final var contractType : PUBLIC_CONTRACT_TYPES) { + inspectType(contractType.getName(), contractType, violations); + for (final var field : contractType.getFields()) { + inspectType(contractType.getName() + "#" + field.getName(), field.getGenericType(), violations); + } + for (final var constructor : contractType.getConstructors()) { + for (final var parameterType : constructor.getGenericParameterTypes()) { + inspectType(contractType.getName() + "#", parameterType, violations); + } + } + for (final var method : contractType.getMethods()) { + if (method.getDeclaringClass().equals(Object.class) + || !Modifier.isPublic(method.getModifiers())) { + continue; + } + inspectType(contractType.getName() + "#" + method.getName(), method.getGenericReturnType(), violations); + for (final var parameterType : method.getGenericParameterTypes()) { + inspectType(contractType.getName() + "#" + method.getName(), parameterType, violations); + } + } + if (contractType.isRecord()) { + for (final var component : contractType.getRecordComponents()) { + inspectType(contractType.getName() + "#" + component.getName(), component.getGenericType(), violations); + } + } + } + + assertTrue( + violations.isEmpty(), + "public IRBackend contract must not expose PBS frontend types: " + violations); + } @Test void callInstructionMustRequireCategorySpecificMetadata() { @@ -366,4 +432,17 @@ class IRBackendExecutableContractTest { assertEquals(0, backend.getCallableSignatures().get(0).moduleId().getIndex()); assertEquals(1, backend.getCallableSignatures().get(1).moduleId().getIndex()); } + + private static void inspectType( + final String owner, + final Type type, + final ArrayList violations) { + if (type == null) { + return; + } + final var typeName = type.getTypeName(); + if (typeName.contains(FORBIDDEN_PBS_PACKAGE)) { + violations.add(owner + " -> " + typeName); + } + } } -- 2.47.2 From b9a32e460aeb78f258e72237ad08836c3e98b20a Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 15 Jul 2026 12:18:44 +0100 Subject: [PATCH 4/4] housekeep DSC-0057 --- discussion/index.ndjson | 4 +- ...rbackend-handoff-and-backend-guardrails.md | 98 ++++++++++++ ...ulti-frontend-frontend-backend-contract.md | 93 ----------- ...mmon-irbackend-frontend-backend-handoff.md | 145 ------------------ ...LN-0117-common-irbackend-contract-specs.md | 100 ------------ ...118-common-irbackend-backend-guardrails.md | 114 -------------- 6 files changed, 100 insertions(+), 454 deletions(-) create mode 100644 discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md delete mode 100644 discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md delete mode 100644 discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md delete mode 100644 discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md delete mode 100644 discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md diff --git a/discussion/index.ndjson b/discussion/index.ndjson index caacab81..45ec4ad5 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,4 +1,4 @@ -{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":44,"PLN":119,"LSN":59,"CLSN":1}} +{"type":"meta","next_id":{"DSC":66,"AGD":69,"DEC":44,"PLN":119,"LSN":60,"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":"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":"done","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":"done","created_at":"2026-07-15","updated_at":"2026-07-15","ref_decisions":["DEC-0043"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0057","status":"done","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":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0059","file":"discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]} {"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"}]} diff --git a/discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md b/discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md new file mode 100644 index 00000000..48446c4e --- /dev/null +++ b/discussion/lessons/DSC-0057-multi-frontend-frontend-backend-contract/LSN-0059-common-irbackend-handoff-and-backend-guardrails.md @@ -0,0 +1,98 @@ +--- +id: LSN-0059 +ticket: multi-frontend-frontend-backend-contract +title: Common IRBackend handoff and backend guardrails +created: 2026-07-15 +tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend] +--- + +# Common IRBackend handoff and backend guardrails + +## Context + +The multi-frontend work needed a clear boundary between language-specific frontends and common backend stages. + +The existing code was already close to the desired architecture: PBS parsing, AST construction, and semantic analysis lowered into `IRBackend`, while the backend consumed `IRBackend` and lowered it into `IRVM`. The risk was not a known broken dependency. The risk was that common backend behavior still looked PBS-owned in specs, names, and missing guardrails, which could invite future coupling when another frontend is introduced. + +## Key Decisions + +### `IRBackend` is the common executable handoff + +**What:** `IRBackend` remains the normative frontend-to-backend executable handoff. Frontends emit it; common backend stages consume it. + +**Why:** The existing model already provides a language-neutral executable contract with modules, callable identities, executable functions, instruction metadata, globals, synthetic functions, host calls, intrinsics, spans, and capabilities. Renaming or redesigning it without a concrete leak would add churn without improving the boundary. + +**Trade-offs:** Keeping the name `IRBackend` means the architecture relies on documentation and tests to communicate its common role. That is acceptable because the name is already established and the guardrails now enforce the boundary. + +### PBS owns lowering into `IRBackend`, not backend consumption of it + +**What:** PBS specs describe PBS admission and translation into `IRBackend`. Compiler-general specs describe the common `IRBackend -> IRVM` contract and backend obligations. + +**Why:** PBS is currently the only rich frontend producing executable `IRBackend`, so many examples naturally come from PBS. Specs must still separate source-language obligations from backend obligations so future frontends do not inherit PBS-specific rules by accident. + +**Trade-offs:** Some PBS-facing examples remain useful, especially around lifecycle wrappers and asset metadata. They must be phrased as current frontend sources of a common backend obligation, not as backend ownership by PBS. + +## Implementation Result + +The completed work: + +1. rewrote the general backend spec so `IRBackend -> IRVM` is explicitly compiler-general; +2. rewrote the PBS lowering spec so PBS emits the common handoff instead of owning backend behavior; +3. updated the conformance matrix with DEC-0043 guardrail rows; +4. added a direct backend test that manually constructs common `IRBackend` and lowers it without PBS parser or frontend services; +5. added an architectural test preventing common backend imports from `p.studio.compiler.pbs`; +6. added a reflection-based contract test preventing public `IRBackend` model types from exposing PBS packages; +7. renamed the common lifecycle helper from `validatePbsLifecycleStructure` to `validateCommonLifecycleStructure`. + +## Patterns and Algorithms + +### Boundary consolidation before abstraction + +When an existing boundary is already technically sound, prefer consolidation over redesign: + +1. document the current contract as normative; +2. identify only concrete leaks; +3. add tests that would fail if the boundary regresses; +4. avoid renames or model extraction until there is evidence of real coupling. + +This keeps multi-frontend preparation focused on preventing regressions rather than inventing abstractions prematurely. + +### Guardrails for common backend neutrality + +A useful backend neutrality guardrail has two layers: + +1. source/package guard: common backend source must not import language frontend packages; +2. public-contract guard: common handoff types must not expose language-owned types through fields, constructors, methods, or record components. + +The package guard catches implementation coupling. The reflection guard catches API coupling. + +### Direct handoff construction test + +A backend test should be able to construct executable `IRBackend` manually using only common model types and lower it through `LowerToIRVMService`. + +That test proves the backend consumes the contract, not a specific frontend pipeline. + +## Pitfalls + +- Do not treat the presence of PBS examples as proof that the backend is PBS-owned. +- Do not move PBS source rules into compiler-general specs. +- Do not let lifecycle terms such as published wrapper, boot guard, or frame root hide whether the obligation is common or PBS-specific. +- Do not rename `IRBackend` for aesthetics when the real problem is missing ownership language and missing guardrails. +- Do not use a future synthetic test frontend as a substitute for simple direct `IRBackend` construction tests. + +## Takeaways + +- `IRBackend` is the common executable handoff. +- PBS owns PBS-to-`IRBackend` lowering; compiler-general owns `IRBackend -> IRVM`. +- Common backend code must not depend on `p.studio.compiler.pbs`. +- Public `IRBackend` contract types must not expose PBS AST, token, parser, semantic, or editorial types. +- Multi-frontend preparation should first lock existing good boundaries before introducing new abstractions. + +## References + +- `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` +- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java` +- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/specs/CommonBackendArchitectureTest.java` +- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java` diff --git a/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md b/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md deleted file mode 100644 index c36ef6ec..00000000 --- a/discussion/workflow/agendas/AGD-0060-multi-frontend-frontend-backend-contract.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -id: AGD-0060 -ticket: multi-frontend-frontend-backend-contract -title: Estabilizar contrato entre frontend e backend comum -status: accepted -created: 2026-07-15 -resolved: -decision: DEC-0043 -tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend] ---- - -# 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: - -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 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. diff --git a/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md b/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md deleted file mode 100644 index 93adade4..00000000 --- a/discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -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. diff --git a/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md b/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md deleted file mode 100644 index 4260aa41..00000000 --- a/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: PLN-0117 -ticket: multi-frontend-frontend-backend-contract -title: Common IRBackend contract specs -status: done -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 - -- [x] Compiler-general specs state that `IRBackend` is the common frontend-to-backend executable handoff. -- [x] Compiler-general specs do not describe common backend behavior as PBS-owned. -- [x] PBS lowering specs describe how PBS emits `IRBackend` and defer common backend obligations to compiler-general specs. -- [x] Forbidden coupling is explicit for PBS AST, tokens, parser structures, semantic objects, editorial objects, and future frontend equivalents. -- [x] Lifecycle, published entrypoint, boot guard, spans, and capabilities are written in neutral terms when they are backend obligations. -- [x] 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` diff --git a/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md b/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md deleted file mode 100644 index 9e570501..00000000 --- a/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -id: PLN-0118 -ticket: multi-frontend-frontend-backend-contract -title: Common IRBackend backend guardrails -status: done -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 - -- [x] Common backend source code has no dependency on `p.studio.compiler.pbs`. -- [x] Public `IRBackend` contract types expose no PBS AST, token, parser, semantic, or editorial classes. -- [x] A backend test manually constructs executable `IRBackend` and lowers it without invoking PBS parser or PBS frontend compiler services. -- [x] Common backend lifecycle/entrypoint validation names and diagnostics are neutral where the behavior is common. -- [x] Existing PBS frontend lowering tests still pass. -- [x] Existing backend lowering tests still pass. -- [x] 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` -- 2.47.2