70 lines
3.8 KiB
Markdown
70 lines
3.8 KiB
Markdown
---
|
|
id: PLN-0121
|
|
ticket: multi-frontend-serializable-ir
|
|
title: Add serializable IRBackend reflection guardrails
|
|
status: done
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0044]
|
|
tags: [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.
|