prometeu-studio/discussion/workflow/plans/PLN-0117-common-irbackend-contract-specs.md

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