prometeu-studio/discussion/workflow/plans/PLN-0119-document-irbackend-serializability-invariants.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0119	multi-frontend-serializable-ir	Document IRBackend serializability invariants	done	2026-07-15	DEC-0044	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