prometeu-studio/discussion/workflow/plans/PLN-0009-compiler-pipeline-spec-and-contract-propagation.md

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