prometeu-studio/discussion/workflow/plans/PLN-0122-prove-deterministic-irbackend-ordering.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0122	multi-frontend-serializable-ir	Prove deterministic IRBackend ordering	done	2026-07-15	DEC-0044	compiler compiler-general ir backend serialization multi-frontend

Briefing

DEC-0044 requires ordered collections and deterministic output-affecting ordering in the common handoff. The current aggregator already uses ordered lists and insertion-preserving sets in some places; this plan proves the behavior that matters for the public contract.

Objective

Add or extend tests that prove deterministic ordering for IRBackend aggregation, table emission, executable functions, metadata surfaces, required capabilities, and any other public handoff list whose order can affect backend lowering or serialized representation.

Dependencies

• Accepted decision: DEC-0044.
• Recommended predecessor: PLN-0120, so the test targets follow the audited public contract.
• Existing aggregator code: prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java.
• Existing test: prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java.

Scope

1. Test that IRBackend.IRBackendAggregator preserves deterministic file merge order for executable functions, globals, synthetic functions, module pool entries, callable signatures, intrinsic pool entries, reserved metadata surfaces, and required capabilities.
2. Test that duplicate or repeated metadata inputs produce stable emitted ordering when the contract permits duplicates.
3. Test that table-scoped ids are remapped deterministically from local file tables into aggregate tables.
4. Confirm that public handoff APIs expose ordered list contracts, not unordered collections.

Non-Goals

• Do not define semantic sorting where current contract is explicit merge order.
• Do not change function-id assignment in backend lowering unless a deterministic-ordering leak is found and moved to PLN-0123.
• Do not add serialization snapshots or golden wire-format files.
• Do not introduce a new collection library.

Execution Method

1. Extend current aggregation tests in IRBackendExecutableContractTest or create a focused companion test in the same package.
2. Build at least two IRBackendFile fixtures with distinct local module, callable, intrinsic, executable, global, synthetic, metadata, and capability entries.
3. Merge the fixtures in a known order and assert emitted aggregate order and remapped ids.
4. Repeat the merge with equivalent freshly constructed inputs and assert identical aggregate shape.
5. Add a negative or regression-style assertion only if the current API can express a previously unstable shape.
6. Keep tests independent from PBS parser, PBS lowering, and backend lowering services.

Acceptance Criteria

1. Tests prove that public handoff list ordering is deterministic for equivalent admitted inputs.
2. Tests prove that aggregate table ids are remapped deterministically.
3. Tests do not depend on PBS frontend code.
4. No wire format or serializer is introduced.

Tests

Run the narrow Gradle test task for IRBackendExecutableContractTest or the smallest module-level prometeu-frontend-api test task.

Affected Artifacts

• prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java
• Optional companion test under prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/
• prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java only if a deterministic ordering bug is proven and fixed under PLN-0123