65 lines
3.6 KiB
Markdown
65 lines
3.6 KiB
Markdown
---
|
|
id: PLN-0122
|
|
ticket: multi-frontend-serializable-ir
|
|
title: Prove deterministic IRBackend ordering
|
|
status: open
|
|
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`
|