prometeu-studio/discussion/workflow/plans/PLN-0123-fix-concrete-irbackend-serialization-leaks.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0123	multi-frontend-serializable-ir	Fix concrete IRBackend serialization leaks	open	2026-07-15	DEC-0044	compiler compiler-general ir backend serialization multi-frontend

Briefing

DEC-0044 allows incremental correction of concrete leaks found by audit and guardrail tests. This plan is intentionally last because it must operate on proven violations rather than speculative redesign.

Objective

Fix only the concrete public IRBackend serialization leaks identified by PLN-0120, PLN-0121, or PLN-0122, while preserving the accepted contract that no codec or transport is introduced.

Dependencies

• Accepted decision: DEC-0044.
• Required predecessor: PLN-0120, to identify exact leak targets.
• Required predecessor when tests exist: PLN-0121, so non-serializable exposure is protected by tests.
• Required predecessor when ordering is involved: PLN-0122, so deterministic behavior is protected by tests.

Scope

1. Replace public direct object references with explicit ids or stable symbolic keys when the audit proves they are part of the public handoff and violate DEC-0044.
2. Replace public unordered or mutable collection exposure with ordered contract surfaces.
3. Remove or encapsulate public callback, service, registry, visitor, or process-local lazy value exposure if any exists in the handoff.
4. Add typed ids only for concrete leak targets where existing ids or stable symbolic keys are insufficient.
5. Preserve backwards-compatible constructors or adapters only when they do not keep the forbidden shape in the public contract.

Non-Goals

• Do not redesign IRBackend.
• Do not migrate all textual identities to typed ids unless the audit proves a concrete contract leak.
• Do not introduce JSON, Protobuf, schema files, RPC, plugin loading, or process boundaries.
• Do not change PBS source semantics or backend lowering behavior except where required to consume the corrected handoff shape.

Execution Method

1. Start from the exact violation list produced by PLN-0120 and failing tests from PLN-0121 or PLN-0122.
2. For each violation, choose the smallest correction that satisfies DEC-0044:
   • direct reference to another handoff object becomes an explicit id or ordered table entry;
   • unordered collection becomes an ordered list of value entries;
   • mutable collection exposure becomes ReadOnlyList or another existing immutable/read-only contract type;
   • callback/service exposure is removed from the public handoff and moved behind compiler-side assembly code.
3. Update constructors, aggregators, lowerers, and tests that consume the corrected contract.
4. Keep PBS-specific changes inside PBS lowering if PBS emitted the old shape.
5. Run all relevant frontend API and backend tests after each correction group.

Acceptance Criteria

1. Every concrete leak identified by predecessor plans is either fixed or explicitly documented as not part of the public IRBackend handoff.
2. Reflection guardrails from PLN-0121 pass.
3. Deterministic ordering tests from PLN-0122 pass.
4. Existing backend lowering tests continue to pass.
5. No codec, schema language, RPC, external process, or plugin runtime is introduced.

Tests

Run:

1. the prometeu-frontend-api tests covering IRBackend contract models;
2. backend lowering tests that consume IRBackend, including LowerToIRVMServiceTest when available;
3. any conformance or architecture tests touched by the corrected public shape.

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/...
• prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/backend/... only when a corrected handoff shape requires backend consumer updates
• prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/backend/...
• PBS lowering files only when PBS emits a corrected handoff shape