prometeu-studio/discussion/workflow/plans/PLN-0121-add-serializable-irbackend-reflection-guardrails.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0121	multi-frontend-serializable-ir	Add serializable IRBackend reflection guardrails	open	2026-07-15	DEC-0044	compiler compiler-general ir backend serialization multi-frontend

Briefing

DEC-0044 requires lightweight guardrails that prevent the public IRBackend handoff from exposing non-serializable process-local shapes. Existing tests already prevent PBS type exposure; this plan expands that guardrail to the broader serializability contract.

Objective

Add reflection-based tests that fail when public IRBackend contract types expose callbacks, services, mutable/unordered collections, frontend-owned objects, or other forbidden public shapes.

Dependencies

• Accepted decision: DEC-0044.
• Recommended predecessor: PLN-0119 for spec terminology.
• Recommended predecessor: PLN-0120 for the complete contract type list and allowed supporting type classification.
• Existing test: prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java.

Scope

1. Extend the public contract type list to cover all current IRBackend handoff types found by PLN-0120.
2. Add reflection checks for forbidden package exposure beyond PBS when the exposed type is frontend-owned.
3. Add checks that public API signatures do not expose callbacks, functional interfaces, service-like objects, registries, direct mutable collections, or unordered collection contracts.
4. Add an allowlist for value wrappers that are accepted by DEC-0044, such as identifier wrappers, spans, enums, strings, primitives, boxed scalar values where already present, and ReadOnlyList.
5. Keep failure messages actionable by reporting the exact contract type and member.

Non-Goals

• Do not assert one mandatory serializer.
• Do not reject all non-record classes automatically; reject public exposed shapes that violate the decision.
• Do not rewrite model classes in this plan except for tiny test-support adjustments.
• Do not use ArchUnit or a new dependency unless repository maintainers separately approve it.

Execution Method

1. Refactor IRBackendExecutableContractTest only enough to support reusable inspection helpers.
2. Keep the existing PBS exposure test intact or fold it into a broader public-contract exposure test with equivalent failure coverage.
3. Implement recursive inspection of public fields, record components, public constructors, and public methods.
4. Treat generic type arguments as part of the public shape.
5. Add explicit classification helpers:
   • isAllowedScalarOrValueType,
   • isAllowedCollectionType,
   • isForbiddenCallbackOrServiceShape,
   • isForbiddenFrontendOwnedType.
6. Run the narrow test suite and fix only test logic defects in this plan.

Acceptance Criteria

1. A public IRBackend contract type exposing a callback or functional interface would fail the test.
2. A public IRBackend contract type exposing java.util.Map, java.util.Set, mutable list classes, or unordered collection interfaces would fail unless explicitly represented as an ordered contract type.
3. A public IRBackend contract type exposing frontend-owned AST/parser/token/semantic/editorial objects would fail.
4. Failure output names the exact member that violates the contract.
5. Existing PBS neutrality guardrail coverage is preserved.

Tests

Run the narrow Gradle test task for IRBackendExecutableContractTest. If the repo's Gradle structure makes a narrower invocation unreliable, run the smallest module-level test task for prometeu-frontend-api.

Affected Artifacts

• prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java
• Potential test-only helpers in the same test package.