72 lines
4.0 KiB
Markdown
72 lines
4.0 KiB
Markdown
---
|
|
id: PLN-0120
|
|
ticket: multi-frontend-serializable-ir
|
|
title: Audit public IRBackend contract shape
|
|
status: done
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0044]
|
|
tags: [compiler, compiler-general, ir, backend, serialization, multi-frontend]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0044` requires the public `IRBackend` handoff to remain an acyclic, deterministic data graph. Before adding broad tests or changing models, the current public contract must be audited and classified.
|
|
|
|
## Objective
|
|
|
|
Produce a concrete audit of public `IRBackend` contract types and classify each exposed field, record component, constructor parameter, and public method return/parameter as allowed, forbidden, or requiring a later correction plan.
|
|
|
|
## Dependencies
|
|
|
|
- Accepted decision: `DEC-0044`.
|
|
- Recommended predecessor: `PLN-0119`, so the audit uses the same terminology as the spec.
|
|
- Existing model package: `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models`.
|
|
- Existing guardrail test: `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`.
|
|
|
|
## Scope
|
|
|
|
1. Enumerate all public `IRBackend` handoff types currently treated as contract types.
|
|
2. Include nested public types such as executable instructions, host-call metadata, intrinsic metadata, reserved metadata surfaces, origins, globals, synthetic functions, and related enums.
|
|
3. Inspect public API exposure through fields, record components, constructors, getters, and public methods.
|
|
4. Classify types from adjacent packages such as identifiers, source spans, source table references, and `ReadOnlyList`.
|
|
5. Record any concrete leak candidates that must be fixed by `PLN-0123`.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not fix leaks in this plan unless the audit itself cannot compile without a tiny supporting test helper.
|
|
- Do not add a serializer or schema.
|
|
- Do not expand the public contract beyond what current backend lowering needs.
|
|
- Do not infer new product rules beyond `DEC-0044`.
|
|
|
|
## Execution Method
|
|
|
|
1. Build the contract type list from `IRBackendExecutableContractTest.PUBLIC_CONTRACT_TYPES` and compare it with actual public model files under `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models`.
|
|
2. Add missing public contract types to the audit list when they are reachable from `IRBackend`, `IRBackendFile`, executable functions, globals, reserved metadata, or synthetic functions.
|
|
3. Inspect exposed generic types recursively enough to identify:
|
|
- frontend-owned package exposure,
|
|
- callback or functional interface exposure,
|
|
- service/registry/object graph exposure,
|
|
- unordered collection exposure,
|
|
- direct mutable collection exposure,
|
|
- direct object reference patterns that should become ids,
|
|
- and nullable fields that are semantically ambiguous.
|
|
4. Write the audit result in the implementation notes, test assertions, or a short local checklist committed with the implementation. Prefer executable test fixtures where possible; use prose only for items that need human judgment.
|
|
5. Create a list of concrete fix candidates for `PLN-0123`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. Every current public `IRBackend` contract type is accounted for.
|
|
2. The audit identifies which exposed supporting types are intentionally allowed by `DEC-0044`.
|
|
3. Any violation or ambiguous exposure has an exact file/type/member target for `PLN-0123`.
|
|
4. No codec, schema, RPC, or external process choice is introduced.
|
|
|
|
## Tests
|
|
|
|
Run the frontend API test suite or the narrow Gradle test task that executes `IRBackendExecutableContractTest`. If no code changes are made in this plan, verify at minimum that the audit inputs still compile before downstream guardrail plans depend on them.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/...`
|
|
- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`
|
|
- Optional implementation note or checklist artifact only if executable tests cannot represent part of the audit clearly.
|