---
id: PLN-0119
ticket: multi-frontend-serializable-ir
title: Document IRBackend serializability invariants
status: done
created: 2026-07-15
ref_decisions: [DEC-0044]
tags: [compiler, compiler-general, ir, backend, serialization, multi-frontend]
---

## Briefing

`DEC-0044` locks the common `IRBackend` handoff as a serializable-by-design data contract. The first implementation step is to make that rule visible in compiler-general specs before changing code or tests.

## Objective

Document the serializability invariants for the common `IRBackend` handoff in the compiler-general backend specification, and connect those invariants to the conformance matrix when a test row is useful.

## Dependencies

- Accepted decision: `DEC-0044`.
- Existing common backend spec: `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
- Existing conformance matrix: `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.

## Scope

1. Add a compiler-general subsection defining `IRBackend` as a serializable-by-design data contract.
2. State the allowed public contract shapes: primitives, strings, enums, immutable values, ordered lists, explicit ids, and source attribution values.
3. State the forbidden public contract shapes: callbacks, service objects, frontend AST/parser/token/semantic/editorial objects, mutable global state, object-identity semantics, unordered contract collections, cyclic public references, lazy process-dependent values, and selected wire formats.
4. Define the relationship between table-scoped ids such as `FileId`, `ModuleId`, `CallableId`, and `IntrinsicId` and future codec eligibility.
5. Add conformance matrix rows only for invariants that have direct test coverage in the follow-up plans.

## Non-Goals

- Do not choose JSON, Protobuf, RPC, process isolation, plugin loading, or any concrete wire format.
- Do not define a schema language.
- Do not change Java model code in this plan.
- Do not move PBS-specific lowering rules into compiler-general specs.

## Execution Method

1. Update `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
   - Add the serializability subsection near the existing common `IRBackend` contract section.
   - Use normative `MUST`, `MUST NOT`, and `SHOULD` language matching `DEC-0044`.
   - Keep the wording data-shape focused, not transport focused.
2. Update `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.
   - Add rows for public-contract serializability guardrails only if the row can name or anticipate concrete tests from `PLN-0121` and `PLN-0122`.
   - Keep rows under compiler-general/backend ownership.
3. Check that PBS lowering spec remains scoped to populating the handoff.
   - If references are needed, link to the compiler-general spec rather than restating the full rule.

## Acceptance Criteria

1. The compiler-general spec states that public `IRBackend` contract types are serializable by design.
2. The spec explicitly forbids callbacks, services, frontend-owned objects, mutable global state, identity-based semantics, unordered output-affecting collections, cycles, process-dependent lazy values, and wire-format selection.
3. The spec preserves `DEC-0044`'s deferral of codecs and external process design.
4. Any conformance matrix changes map to concrete tests planned in `PLN-0121` or `PLN-0122`.

## Tests

Run documentation validation available in the repository, if any. At minimum, run `discussion validate` after the plan's implementation and manually inspect the changed spec section for normative consistency with `DEC-0044`.

## Affected Artifacts

- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
- Optional reference touch only: `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`