68 lines
3.8 KiB
Markdown
68 lines
3.8 KiB
Markdown
---
|
|
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`
|