---
id: PLN-0010
ticket: compiler-analyze-compile-build-pipeline-split
title: Refactor BuilderPipelineService into explicit analyze, compile, and build entrypoints
status: review
created: 2026-03-30
completed:
tags:
  - compiler
  - pipeline
  - implementation
  - api
---

## Objective

Implement the canonical pipeline entrypoints from DEC-0007 in `prometeu-build-pipeline`, replacing the monolithic public `run` surface with explicit `analyze`, `compile`, and `build` operations.

## Background

The current `BuilderPipelineService` exposes one public `run(config, logs)` entrypoint and internally constructs a filesystem-anchored `BuilderPipelineContext`.

DEC-0007 requires:
1. one canonical pipeline with fixed stage ordering,
2. `analyze`, `compile`, and `build` as explicit public entrypoints,
3. stable result contracts rather than leaking `BuilderPipelineContext`,
4. filesystem-default context construction outside the pipeline itself.

## Scope

### Included
- Refactor `BuilderPipelineService` public API to explicit entrypoints.
- Introduce stable result models for `analyze`, `compile`, and `build`.
- Refactor context/config construction so filesystem-default composition is no longer hardcoded inside the pipeline service.
- Keep the canonical stage ordering unchanged.

### Excluded
- Updating downstream callsites and tests outside the core pipeline module.
- Editor/LSP-specific consumers beyond the generic context/config model.
- Housekeeping deletion of historical docs or discussion artifacts.

## Execution Steps

### Step 1 - Introduce explicit result contracts

**What:** Add stable result types for each public entrypoint so the service no longer exposes `BuilderPipelineContext` as the external contract.
**How:** Define result models with the minimum DEC-0007 requirements:
1. `AnalysisSnapshot` or equivalent for `analyze`,
2. an in-memory compile result carrying validated executable artifacts for `compile`,
3. a build result carrying the persisted artifact location and compile payload for `build`.
Keep internal mutable pipeline state in `BuilderPipelineContext`, but add explicit adapters from context to public result objects.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/BuilderPipelineContext.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/`

### Step 2 - Split service entrypoints by terminal stage

**What:** Refactor `BuilderPipelineService` so each public entrypoint stops at the DEC-0007 terminal stage.
**How:** Replace the public `run` flow with explicit methods that execute the same canonical stage list through bounded terminal stages:
1. `analyze` stops after `FrontendPhasePipelineStage`,
2. `compile` stops after `VerifyBytecodePipelineStage`,
3. `build` stops after `WriteBytecodeArtifactPipelineStage`.
Use one shared stage execution helper so the implementation does not fork stage order or error handling logic across entrypoints.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/PipelineStage.java`

### Step 3 - Externalize context construction

**What:** Remove the implicit filesystem-default context construction from inside the pipeline service.
**How:** Refactor `BuilderPipelineContext.compilerContext(...)` and surrounding config flow so entrypoints receive the context/config composition required for their caller.
Preserve filesystem support, but move its construction into explicit factories or caller-side composition helpers rather than hardcoding it as the only pipeline-owned mode.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/models/BuilderPipelineContext.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/BuilderPipelineConfig.java`
- `prometeu-compiler/prometeu-compiler-core/src/main/java/p/studio/compiler/utilities/SourceProviderFactory.java`

### Step 4 - Keep canonical stage behavior intact

**What:** Ensure the refactor preserves the semantic order and gating behavior of the current executable pipeline.
**How:** Keep the stage order fixed, preserve current error propagation, and ensure `compile` still covers lowering, optimization, emission, link precheck, and verification before any build-specific artifact write occurs.
**File(s):**
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/BuilderPipelineService.java`
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/*.java`

## Test Requirements

### Unit Tests

- Add service-level tests proving each entrypoint stops at its required terminal stage.
- Add tests proving `analyze` produces the minimum snapshot contract and does not populate backend artifact outputs.
- Add tests proving `compile` returns validated in-memory artifacts without writing to disk.
- Add tests proving `build` extends `compile` only with artifact persistence.

### Integration Tests

- Preserve or replace the existing end-to-end pipeline integration coverage with explicit `build`-based integration tests.
- Add an integration test that exercises `compile` against a real project root and asserts no artifact file is written.

### Manual Verification

- Inspect the public API of `BuilderPipelineService` to confirm `run` is gone.
- Verify the default filesystem composition is not hardcoded as the only context path inside the service.
- Verify stage order remains unchanged from DEC-0007.

## Acceptance Criteria

- [ ] `BuilderPipelineService` exposes explicit `analyze`, `compile`, and `build` entrypoints and no longer exposes public `run`.
- [ ] Public result types exist and `BuilderPipelineContext` is no longer the external contract.
- [ ] `analyze`, `compile`, and `build` stop exactly at the DEC-0007 terminal stages.
- [ ] Filesystem-default behavior is still supported but is composed outside the pipeline core.
- [ ] The canonical executable path preserves current PBS-facing correctness through emit, link, and verify.

## Dependencies

- PLN-0009 should land first or in parallel if the spec wording is stable.
- No downstream callsite migration should begin until the new entrypoints and result models exist.

## Risks

- Refactoring context ownership without a clear composition boundary can accidentally leave filesystem behavior embedded in the service.
- Result models that mirror the mutable context too closely will leak internal implementation details back into the public API.
- If stage slicing is duplicated per method instead of shared, drift between `compile` and `build` can reappear immediately.