146 lines
7.1 KiB
Markdown
146 lines
7.1 KiB
Markdown
---
|
|
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.
|