101 lines
5.6 KiB
Markdown
101 lines
5.6 KiB
Markdown
---
|
|
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`
|