106 lines
4.6 KiB
Markdown
106 lines
4.6 KiB
Markdown
---
|
|
id: PLN-0009
|
|
ticket: compiler-analyze-compile-build-pipeline-split
|
|
title: Propagate DEC-0007 into compiler pipeline specs and public contracts
|
|
status: done
|
|
created: 2026-03-30
|
|
completed: 2026-03-30
|
|
tags:
|
|
- compiler
|
|
- pipeline
|
|
- specs
|
|
- contracts
|
|
---
|
|
|
|
## Objective
|
|
|
|
Propagate DEC-0007 into the normative compiler spec surface so that `analyze`, `compile`, and `build` become explicit operational contracts before code migration starts.
|
|
|
|
## Background
|
|
|
|
DEC-0007 locks one canonical pipeline with three entrypoints, removes `run` as a public concept, requires a minimum `AnalysisSnapshot` contract, and requires propagation into compiler specs and callsite-facing documentation.
|
|
|
|
The current shared compiler spec set contains backend and conformance chapters, but it does not yet define canonical compiler entrypoints or their result contracts as first-class normative surfaces.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Add or update shared compiler specs to define `analyze`, `compile`, and `build`.
|
|
- Document the minimum required shape of `AnalysisSnapshot`, the compile result, and the build result.
|
|
- Update compiler spec navigation and cross-references so DEC-0007 becomes discoverable from the shared spec surface.
|
|
- Update conformance-facing documentation to reflect entrypoint-specific expectations.
|
|
|
|
### Excluded
|
|
- Java implementation changes in `prometeu-build-pipeline`.
|
|
- Editor or LSP callsite integration work.
|
|
- Removal of legacy Java APIs by itself.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Add canonical compiler entrypoint specification
|
|
|
|
**What:** Introduce a new shared compiler spec chapter that defines the canonical pipeline, the terminal stage for each entrypoint, and the mandatory result contracts.
|
|
**How:** Create a new chapter under `docs/specs/compiler/` covering:
|
|
1. canonical stage order,
|
|
2. `analyze = ResolveDeps + LoadSources + FrontendPhase`,
|
|
3. `compile = analyze + LowerToIRVM + OptimizeIRVM + EmitBytecode + LinkBytecode + VerifyBytecode`,
|
|
4. `build = compile + WriteBytecodeArtifact`,
|
|
5. minimum `AnalysisSnapshot` surface,
|
|
6. validated in-memory compile result contract,
|
|
7. filesystem build contract,
|
|
8. removal of `run` as a public entrypoint.
|
|
**File(s):**
|
|
- `docs/specs/compiler/README.md`
|
|
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
|
|
|
|
### Step 2 - Align conformance-facing shared docs
|
|
|
|
**What:** Update shared compiler conformance documentation to refer to entrypoint contracts rather than one monolithic build invocation.
|
|
**How:** Extend the existing conformance matrix and any related shared references so tests can be mapped to `analyze`, `compile`, and `build` responsibilities separately, including stage-boundary assertions and artifact-side-effect boundaries.
|
|
**File(s):**
|
|
- `docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md`
|
|
|
|
### Step 3 - Document migration expectations for callsites
|
|
|
|
**What:** State the public migration rule that current default filesystem behavior is now expressed through `build`, not `run`.
|
|
**How:** Capture, in the new or updated spec text, that:
|
|
1. `run` is not a normative public entrypoint,
|
|
2. filesystem-default composition happens outside the pipeline itself,
|
|
3. CLI and other callsites must migrate to explicit entrypoints.
|
|
**File(s):**
|
|
- `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
|
|
- `docs/specs/compiler/README.md`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- No Java unit tests are required for this editorial plan.
|
|
|
|
### Integration Tests
|
|
|
|
- No runtime integration tests are required for this editorial plan.
|
|
|
|
### Manual Verification
|
|
|
|
- Verify the new chapter is reachable from `docs/specs/compiler/README.md`.
|
|
- Verify the new chapter uses the exact DEC-0007 stage boundaries and does not reintroduce `run`.
|
|
- Verify the conformance matrix distinguishes analysis, in-memory compile, and filesystem build responsibilities.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Shared compiler specs explicitly define `analyze`, `compile`, and `build` as the canonical entrypoints.
|
|
- [ ] The minimum `AnalysisSnapshot` contract is written normatively in the shared compiler spec surface.
|
|
- [ ] The shared docs state that `run` is removed as a public entrypoint and that filesystem-default composition belongs outside the pipeline.
|
|
- [ ] Conformance-facing documentation reflects entrypoint-specific obligations rather than a single monolithic pipeline invocation.
|
|
|
|
## Dependencies
|
|
|
|
- DEC-0007 accepted content.
|
|
- No code implementation dependency is required before this plan can start.
|
|
|
|
## Risks
|
|
|
|
- A too-editorial-only writeup may drift from the exact Java module boundaries that later code work needs.
|
|
- If the result contracts are written loosely, the implementation plans may inherit avoidable ambiguity.
|