Stable contract FE/BE

This commit is contained in:
2026-07-15 12:07:07 +01:00
parent ffd2975484
commit 26c69d5660
5 changed files with 391 additions and 17 deletions
@@ -0,0 +1,100 @@
---
id: PLN-0117
ticket: multi-frontend-frontend-backend-contract
title: Common IRBackend contract specs
status: open
created: 2026-07-15
ref_decisions: [DEC-0043]
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
---
## Briefing
Worker: Spec Editorial Worker.
Domain owner: `compiler/general`, with explicit propagation to `compiler/pbs`.
DEC-0043 accepts the current `IRBackend` shape as the common frontend-to-backend executable handoff. This plan propagates that decision into specs and conformance docs so the common backend is no longer described as PBS-owned by implication.
## Objective
Update compiler-general and PBS specs to state that `IRBackend` is the language-neutral executable handoff emitted by frontends and consumed by common backend stages, while PBS specs describe only PBS-specific admission and lowering into that handoff.
## Dependencies
- Accepted decision: `DEC-0043`.
- No code implementation is required before this plan.
- PLN-0118 may run after or in parallel, but this plan owns normative wording and spec ownership.
## Scope
Included:
- Update `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md` so it is clearly a compiler-general backend contract, not a PBS backend contract.
- Update `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md` to include the common handoff obligations and the required guardrail tests.
- Update `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` so it owns PBS lowering into `IRBackend`, not the common backend contract itself.
- Replace PBS-specific wording in common spec text when the obligation is actually common: executable handoff, lifecycle wrapper, published entrypoint, boot guard, spans, capabilities, host calls, intrinsics.
- Add explicit forbidden-coupling language: common backend specs must not require PBS AST, tokens, parser structures, semantic validators, editorial objects, or equivalent objects from future frontends.
- Preserve existing behavior and conformance obligations.
## Non-Goals
- Do not rename `IRBackend`.
- Do not redesign the IR model.
- Do not change `IRBackend -> IRVM` lowering behavior.
- Do not define serialization.
- Do not resolve synthetic test frontend design beyond referencing the need for guardrails already required by DEC-0043.
- Do not move PBS-specific language rules into compiler-general specs.
## Execution Method
1. Audit current spec ownership.
- Read `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
- Read `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.
- Read `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`.
- Mark each `IRBackend` obligation as common backend, PBS lowering, or test/conformance bookkeeping.
2. Rewrite the compiler-general lowering spec.
- Change the title and introduction if they imply PBS ownership.
- State that `IRBackend` is the common executable frontend-to-backend handoff.
- Describe allowed common concepts: source identity, spans, modules, callables, executable functions, instruction metadata, globals, synthetic functions, host/intrinsic metadata, reserved metadata, capabilities.
- Describe forbidden language-owned inputs at the backend boundary.
- Express lifecycle, published entrypoint, boot guard, and capability obligations in neutral backend terms.
3. Rewrite the PBS lowering spec boundary.
- Keep PBS-specific parser, AST, semantic, source admission, and lowering rules in the PBS spec.
- State that PBS emits the common `IRBackend` contract rather than owning it.
- Replace any common backend obligation duplicated in PBS with a reference to the compiler-general spec unless PBS-specific lowering detail is required.
4. Update the conformance matrix.
- Add or adjust rows for DEC-0043 obligations.
- Reference PLN-0118 tests for direct manual `IRBackend` lowering, backend package independence from `p.studio.compiler.pbs`, and public-contract negative checks.
- Keep existing PBS conformance rows only where they verify PBS lowering obligations.
5. Cross-check terminology.
- Search specs for wording that says or implies PBS owns common backend behavior.
- Leave PBS terms only when they describe PBS source or PBS lowering before the handoff.
## Acceptance Criteria
- [ ] Compiler-general specs state that `IRBackend` is the common frontend-to-backend executable handoff.
- [ ] Compiler-general specs do not describe common backend behavior as PBS-owned.
- [ ] PBS lowering specs describe how PBS emits `IRBackend` and defer common backend obligations to compiler-general specs.
- [ ] Forbidden coupling is explicit for PBS AST, tokens, parser structures, semantic objects, editorial objects, and future frontend equivalents.
- [ ] Lifecycle, published entrypoint, boot guard, spans, and capabilities are written in neutral terms when they are backend obligations.
- [ ] Conformance matrix maps DEC-0043 obligations to tests or planned tests without weakening existing coverage.
## Tests
Validation:
- Run `discussion validate`.
- Run a docs/spec search for `PBS IRBackend`, `PBS backend`, and similar phrases in compiler-general specs; remaining occurrences must be intentional and tied to PBS-specific references.
- If the repository has markdown lint or docs validation, run the established command.
## Affected Artifacts
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
- `discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md`
@@ -0,0 +1,114 @@
---
id: PLN-0118
ticket: multi-frontend-frontend-backend-contract
title: Common IRBackend backend guardrails
status: open
created: 2026-07-15
ref_decisions: [DEC-0043]
tags: [compiler, compiler-general, compiler-pbs, ir, backend, multi-frontend]
---
## Briefing
Worker: Code Implementation Worker.
Domain owner: `compiler/general`, with impact on PBS frontend tests only where PBS currently emits `IRBackend`.
DEC-0043 accepts `IRBackend` as the common frontend-to-backend executable handoff and requires guardrails preventing PBS AST, tokens, parser state, semantic internals, or future language-owned frontend objects from entering the common backend contract.
## Objective
Add focused code and test guardrails that prove the common backend can lower manually constructed `IRBackend` without PBS and cannot accidentally depend on PBS frontend packages or PBS-owned public contract types.
## Dependencies
- Accepted decision: `DEC-0043`.
- PLN-0117 should define the final spec wording before conformance matrix rows are finalized, but this plan can implement tests in parallel.
- Existing tests named in DEC-0043: `IRBackendExecutableContractTest` and `LowerToIRVMServiceTest`.
## Scope
Included:
- Audit common backend and frontend API packages for imports or public contract references to `p.studio.compiler.pbs`.
- Rename or neutralize PBS-specific helper names in common backend code only when behavior is common. The expected example is lifecycle validation wording in `LowerToIRVMService`.
- Add a backend test that constructs a valid executable `IRBackend` manually, without PBS parser/compiler helpers, and lowers it through `LowerToIRVMService`.
- Add an architectural test or equivalent regression check that common backend code does not import or depend on `p.studio.compiler.pbs`.
- Add a public-contract negative check that `IRBackend` model classes do not expose PBS AST, token, parser, semantic, or editorial types.
- Preserve all existing executable lowering behavior.
## Non-Goals
- Do not rename `IRBackend`.
- Do not redesign `IRBackend`, `IRBackendFile`, or `IRBackendExecutableFunction`.
- Do not redesign `IRBackend -> IRVM` lowering.
- Do not implement IR serialization.
- Do not introduce the synthetic test frontend from a separate discussion.
- Do not change PBS language semantics or parser behavior.
## Execution Method
1. Audit package dependencies.
- Search `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend`.
- Search `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models`.
- Confirm there are no imports of `p.studio.compiler.pbs` in common backend or `IRBackend` public model classes.
2. Neutralize common backend naming.
- Inspect `LowerToIRVMService`.
- Rename common helper names that imply PBS ownership when the behavior is actually common. The known target is `validatePbsLifecycleStructure`, which should become neutral lifecycle/executable-entrypoint validation language.
- Update related test method names and expected diagnostic messages only when they are common backend wording.
- Do not change the validation logic unless a test proves behavior was incorrectly tied to PBS.
3. Add direct backend lowering coverage.
- Extend `LowerToIRVMServiceTest` or add a focused backend test in the same test package.
- Build `IRBackend` manually using common model types, module/callable/intrinsic pools, executable functions, spans, and metadata required by the backend.
- Lower it through `LowerToIRVMService`.
- Assert the produced IRVM/bytecode-facing result is valid and does not require PBS parser or PBS frontend services.
4. Add architectural dependency guard.
- Add a JUnit test in an appropriate compiler/backend or build-pipeline test package that scans compiled classes or source imports for forbidden `p.studio.compiler.pbs` dependencies in common backend packages.
- The check must fail if common backend code imports PBS frontend packages.
- If the project already has an architectural-test pattern, follow it; otherwise use a small source-tree scan test scoped to known common backend source roots.
5. Add public-contract type guard.
- Add or extend a test in `prometeu-frontend-api` test scope, likely near `IRBackendExecutableContractTest`.
- Inspect public fields, record components, method return types, constructor parameters, and nested public model types for forbidden PBS package names.
- Fail if any `IRBackend` public contract type exposes `p.studio.compiler.pbs`.
6. Update conformance references if PLN-0117 has already landed.
- Ensure test names match conformance matrix entries.
- If PLN-0117 is not landed yet, record the final test names for the spec plan.
## Acceptance Criteria
- [ ] Common backend source code has no dependency on `p.studio.compiler.pbs`.
- [ ] Public `IRBackend` contract types expose no PBS AST, token, parser, semantic, or editorial classes.
- [ ] A backend test manually constructs executable `IRBackend` and lowers it without invoking PBS parser or PBS frontend compiler services.
- [ ] Common backend lifecycle/entrypoint validation names and diagnostics are neutral where the behavior is common.
- [ ] Existing PBS frontend lowering tests still pass.
- [ ] Existing backend lowering tests still pass.
- [ ] No IR model redesign or `IRBackend` rename was introduced.
## Tests
Required automated tests:
- `IRBackendExecutableContractTest` or equivalent public-contract guard test.
- `LowerToIRVMServiceTest` or equivalent direct manual `IRBackend` lowering test.
- Architectural/backend dependency guard for `p.studio.compiler.pbs` imports in common backend source.
- Existing PBS frontend tests that prove PBS still emits valid `IRBackend`.
Validation commands:
- Run the focused Gradle test tasks for `prometeu-frontend-api`, `prometeu-build-pipeline`, and PBS frontend modules.
- Run the broader compiler test task if available and practical.
- Run `discussion validate`.
## Affected Artifacts
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/irvm/LowerToIRVMService.java`
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/irvm/LowerToIRVMServiceTest.java`
- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`
- Any new architectural test file under the appropriate compiler test module.
- PBS frontend tests only if expected names or neutralized backend diagnostics require updates.
- `discussion/workflow/decisions/DEC-0043-common-irbackend-frontend-backend-handoff.md`