agendas/decisions/plans for re-shape of compiler pipeline
This commit is contained in:
+105
@@ -0,0 +1,105 @@
|
||||
---
|
||||
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.
|
||||
+124
@@ -0,0 +1,124 @@
|
||||
---
|
||||
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.
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
---
|
||||
id: PLN-0011
|
||||
ticket: compiler-analyze-compile-build-pipeline-split
|
||||
title: Migrate compiler callsites and tests to explicit build, compile, and analyze entrypoints
|
||||
status: review
|
||||
created: 2026-03-30
|
||||
completed:
|
||||
tags:
|
||||
- compiler
|
||||
- pipeline
|
||||
- migration
|
||||
- tests
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Migrate existing compiler callsites and test coverage away from `run` so the codebase consumes the DEC-0007 entrypoints explicitly and preserves current filesystem build behavior under `build`.
|
||||
|
||||
## Background
|
||||
|
||||
The current public caller in `prometeu-build-pipeline` is `Compile.main`, which constructs `BuilderPipelineConfig` and calls `BuilderPipelineService.INSTANCE.run(...)`.
|
||||
|
||||
The test suite also includes service-level and integration coverage that still assumes a monolithic `run` entrypoint or a filesystem-default context built inside the pipeline service.
|
||||
|
||||
DEC-0007 requires the default behavior to survive as `build`, with filesystem context composed outside the pipeline itself.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Replace production and test callsites that invoke the old `run` entrypoint.
|
||||
- Preserve current CLI/default build behavior under explicit `build`.
|
||||
- Add regression tests for side-effect boundaries between `analyze`, `compile`, and `build`.
|
||||
|
||||
### Excluded
|
||||
- The core service refactor itself.
|
||||
- Language/frontend-specific editor or LSP consumers that do not yet exist in this codebase.
|
||||
- Spec writing beyond what is covered in PLN-0009.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Migrate the default CLI/build caller
|
||||
|
||||
**What:** Update the current compiler entrypoint so it performs an explicit `build` call rather than a generic `run`.
|
||||
**How:** Refactor `Compile.main` and any supporting composition helpers so the default filesystem-oriented config/context is assembled before invoking `build`.
|
||||
Keep the effective behavior identical to the current default run mode.
|
||||
**File(s):**
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/Compile.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/messages/BuilderPipelineConfig.java`
|
||||
|
||||
### Step 2 - Replace legacy service consumers in tests
|
||||
|
||||
**What:** Update all service-level and integration tests that still call `BuilderPipelineService.INSTANCE.run(...)`.
|
||||
**How:** Rewrite tests to target the explicit entrypoint they actually mean:
|
||||
1. end-to-end artifact production tests use `build`,
|
||||
2. in-memory executable tests use `compile`,
|
||||
3. analysis-only tests use `analyze`.
|
||||
Where the old tests only asserted canonical stage order or successful artifact write, preserve the same behavior under the new API names.
|
||||
**File(s):**
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/MainProjectPipelineIntegrationTest.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/BuilderPipelineServiceOrderTest.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/**/*.java`
|
||||
|
||||
### Step 3 - Add regression coverage for side-effect boundaries
|
||||
|
||||
**What:** Add explicit regression tests that enforce the no-write guarantees and terminal-stage boundaries required by DEC-0007.
|
||||
**How:** Add tests that prove:
|
||||
1. `analyze` does not execute backend artifact stages,
|
||||
2. `compile` does not write `build/program.pbx`,
|
||||
3. `build` writes the artifact and preserves current filesystem behavior,
|
||||
4. removal of `run` does not reduce PBS-facing executable correctness.
|
||||
**File(s):**
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/integration/`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/test/java/p/studio/compiler/workspaces/`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Update any unit tests that instantiate the service or reason about stage execution to use explicit entrypoints.
|
||||
- Add focused assertions for entrypoint-specific side effects and outputs.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Preserve the existing artifact-producing integration behavior under `build`.
|
||||
- Add at least one integration path that exercises `compile` and asserts artifact absence on disk.
|
||||
- Add at least one analysis path that exercises `analyze` and verifies the minimum snapshot contract.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Confirm there are no remaining production uses of `BuilderPipelineService.INSTANCE.run(...)`.
|
||||
- Confirm the default CLI path still writes the expected artifact to the same build location.
|
||||
- Confirm integration coverage still protects the PBS executable path.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] No production callsite still invokes public `run`.
|
||||
- [ ] Existing default filesystem behavior is preserved under explicit `build`.
|
||||
- [ ] Tests explicitly distinguish `analyze`, `compile`, and `build`.
|
||||
- [ ] Regression coverage exists for the no-write boundary of `compile` and the no-backend boundary of `analyze`.
|
||||
- [ ] The migrated test suite still protects PBS-facing executable correctness.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- PLN-0010 must land first because the new public entrypoints and result contracts must exist before callsite migration.
|
||||
- PLN-0009 should land before or alongside this plan so naming and contracts match the normative docs.
|
||||
|
||||
## Risks
|
||||
|
||||
- Test migration can accidentally preserve old semantics by mechanically renaming `run` without asserting the new side-effect boundaries.
|
||||
- If the CLI/default caller keeps assembling filesystem behavior inside the pipeline service, DEC-0007 will be implemented only nominally.
|
||||
- Weak regression coverage here would allow `compile` and `build` to drift again after the refactor.
|
||||
Reference in New Issue
Block a user