---
id: PLN-0122
ticket: multi-frontend-serializable-ir
title: Prove deterministic IRBackend ordering
status: done
created: 2026-07-15
ref_decisions: [DEC-0044]
tags: [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`