prometeu-studio/discussion/workflow/plans/PLN-0010-refactor-builder-pipeline-service-into-entrypoints.md

id	ticket	title	status	created	completed	tags
PLN-0010	compiler-analyze-compile-build-pipeline-split	Refactor BuilderPipelineService into explicit analyze, compile, and build entrypoints	done	2026-03-30	2026-03-30	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.