---
id: PLN-0009
ticket: compiler-analyze-compile-build-pipeline-split
title: Propagate DEC-0007 into compiler pipeline specs and public contracts
status: review
created: 2026-03-30
completed:
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.