Unique and Serializable IR
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: PLN-0119
|
||||
ticket: multi-frontend-serializable-ir
|
||||
title: Document IRBackend serializability invariants
|
||||
status: in_progress
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0044]
|
||||
tags: [compiler, compiler-general, ir, backend, serialization, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0044` locks the common `IRBackend` handoff as a serializable-by-design data contract. The first implementation step is to make that rule visible in compiler-general specs before changing code or tests.
|
||||
|
||||
## Objective
|
||||
|
||||
Document the serializability invariants for the common `IRBackend` handoff in the compiler-general backend specification, and connect those invariants to the conformance matrix when a test row is useful.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0044`.
|
||||
- Existing common backend spec: `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
||||
- Existing conformance matrix: `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.
|
||||
|
||||
## Scope
|
||||
|
||||
1. Add a compiler-general subsection defining `IRBackend` as a serializable-by-design data contract.
|
||||
2. State the allowed public contract shapes: primitives, strings, enums, immutable values, ordered lists, explicit ids, and source attribution values.
|
||||
3. State the forbidden public contract shapes: callbacks, service objects, frontend AST/parser/token/semantic/editorial objects, mutable global state, object-identity semantics, unordered contract collections, cyclic public references, lazy process-dependent values, and selected wire formats.
|
||||
4. Define the relationship between table-scoped ids such as `FileId`, `ModuleId`, `CallableId`, and `IntrinsicId` and future codec eligibility.
|
||||
5. Add conformance matrix rows only for invariants that have direct test coverage in the follow-up plans.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not choose JSON, Protobuf, RPC, process isolation, plugin loading, or any concrete wire format.
|
||||
- Do not define a schema language.
|
||||
- Do not change Java model code in this plan.
|
||||
- Do not move PBS-specific lowering rules into compiler-general specs.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Update `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`.
|
||||
- Add the serializability subsection near the existing common `IRBackend` contract section.
|
||||
- Use normative `MUST`, `MUST NOT`, and `SHOULD` language matching `DEC-0044`.
|
||||
- Keep the wording data-shape focused, not transport focused.
|
||||
2. Update `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`.
|
||||
- Add rows for public-contract serializability guardrails only if the row can name or anticipate concrete tests from `PLN-0121` and `PLN-0122`.
|
||||
- Keep rows under compiler-general/backend ownership.
|
||||
3. Check that PBS lowering spec remains scoped to populating the handoff.
|
||||
- If references are needed, link to the compiler-general spec rather than restating the full rule.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. The compiler-general spec states that public `IRBackend` contract types are serializable by design.
|
||||
2. The spec explicitly forbids callbacks, services, frontend-owned objects, mutable global state, identity-based semantics, unordered output-affecting collections, cycles, process-dependent lazy values, and wire-format selection.
|
||||
3. The spec preserves `DEC-0044`'s deferral of codecs and external process design.
|
||||
4. Any conformance matrix changes map to concrete tests planned in `PLN-0121` or `PLN-0122`.
|
||||
|
||||
## Tests
|
||||
|
||||
Run documentation validation available in the repository, if any. At minimum, run `discussion validate` after the plan's implementation and manually inspect the changed spec section for normative consistency with `DEC-0044`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
||||
- Optional reference touch only: `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: PLN-0120
|
||||
ticket: multi-frontend-serializable-ir
|
||||
title: Audit public IRBackend contract shape
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0044]
|
||||
tags: [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.
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: PLN-0121
|
||||
ticket: multi-frontend-serializable-ir
|
||||
title: Add serializable IRBackend reflection guardrails
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0044]
|
||||
tags: [compiler, compiler-general, ir, backend, serialization, multi-frontend]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0044` requires lightweight guardrails that prevent the public `IRBackend` handoff from exposing non-serializable process-local shapes. Existing tests already prevent PBS type exposure; this plan expands that guardrail to the broader serializability contract.
|
||||
|
||||
## Objective
|
||||
|
||||
Add reflection-based tests that fail when public `IRBackend` contract types expose callbacks, services, mutable/unordered collections, frontend-owned objects, or other forbidden public shapes.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Accepted decision: `DEC-0044`.
|
||||
- Recommended predecessor: `PLN-0119` for spec terminology.
|
||||
- Recommended predecessor: `PLN-0120` for the complete contract type list and allowed supporting type classification.
|
||||
- Existing test: `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`.
|
||||
|
||||
## Scope
|
||||
|
||||
1. Extend the public contract type list to cover all current `IRBackend` handoff types found by `PLN-0120`.
|
||||
2. Add reflection checks for forbidden package exposure beyond PBS when the exposed type is frontend-owned.
|
||||
3. Add checks that public API signatures do not expose callbacks, functional interfaces, service-like objects, registries, direct mutable collections, or unordered collection contracts.
|
||||
4. Add an allowlist for value wrappers that are accepted by `DEC-0044`, such as identifier wrappers, spans, enums, strings, primitives, boxed scalar values where already present, and `ReadOnlyList`.
|
||||
5. Keep failure messages actionable by reporting the exact contract type and member.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not assert one mandatory serializer.
|
||||
- Do not reject all non-record classes automatically; reject public exposed shapes that violate the decision.
|
||||
- Do not rewrite model classes in this plan except for tiny test-support adjustments.
|
||||
- Do not use ArchUnit or a new dependency unless repository maintainers separately approve it.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Refactor `IRBackendExecutableContractTest` only enough to support reusable inspection helpers.
|
||||
2. Keep the existing PBS exposure test intact or fold it into a broader public-contract exposure test with equivalent failure coverage.
|
||||
3. Implement recursive inspection of public fields, record components, public constructors, and public methods.
|
||||
4. Treat generic type arguments as part of the public shape.
|
||||
5. Add explicit classification helpers:
|
||||
- `isAllowedScalarOrValueType`,
|
||||
- `isAllowedCollectionType`,
|
||||
- `isForbiddenCallbackOrServiceShape`,
|
||||
- `isForbiddenFrontendOwnedType`.
|
||||
6. Run the narrow test suite and fix only test logic defects in this plan.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. A public `IRBackend` contract type exposing a callback or functional interface would fail the test.
|
||||
2. A public `IRBackend` contract type exposing `java.util.Map`, `java.util.Set`, mutable list classes, or unordered collection interfaces would fail unless explicitly represented as an ordered contract type.
|
||||
3. A public `IRBackend` contract type exposing frontend-owned AST/parser/token/semantic/editorial objects would fail.
|
||||
4. Failure output names the exact member that violates the contract.
|
||||
5. Existing PBS neutrality guardrail coverage is preserved.
|
||||
|
||||
## Tests
|
||||
|
||||
Run the narrow Gradle test task for `IRBackendExecutableContractTest`. If the repo's Gradle structure makes a narrower invocation unreliable, run the smallest module-level test task for `prometeu-frontend-api`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/test/java/p/studio/compiler/models/IRBackendExecutableContractTest.java`
|
||||
- Potential test-only helpers in the same test package.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
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`
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
id: PLN-0123
|
||||
ticket: multi-frontend-serializable-ir
|
||||
title: Fix concrete IRBackend serialization leaks
|
||||
status: open
|
||||
created: 2026-07-15
|
||||
ref_decisions: [DEC-0044]
|
||||
tags: [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
|
||||
Reference in New Issue
Block a user