prometeu-studio/discussion/workflow/plans/PLN-0120-audit-public-irbackend-contract-shape.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0120	multi-frontend-serializable-ir	Audit public IRBackend contract shape	done	2026-07-15	DEC-0044	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.