Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/plans/PLN-0118-common-irbackend-backend-guardrails.md
bQUARKz 26c69d5660
Stable contract FE/BE
2026-07-15 12:07:07 +01:00

6.5 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0118 multi-frontend-frontend-backend-contract Common IRBackend backend guardrails open 2026-07-15
DEC-0043
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