--- 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`