implements PLN-0009 compiler pipeline spec propagation

discussion/index.ndjson

@@ -9,4 +9,4 @@
 {"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
 {"type":"discussion","id":"DSC-0009","status":"open","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","debugger","workspace","integration","shell"],"agendas":[{"id":"AGD-0009","file":"AGD-0009-studio-debugger-workspace-integration.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
 {"type":"discussion","id":"DSC-0010","status":"open","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[{"id":"AGD-0010","file":"AGD-0010-studio-code-editor-workspace-foundations.md","status":"open","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[],"plans":[],"lessons":[]}
-{"type":"discussion","id":"DSC-0011","status":"open","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[{"id":"AGD-0011","file":"AGD-0011-compiler-analyze-compile-build-pipeline-split.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[{"id":"DEC-0007","file":"DEC-0007-compiler-analyze-compile-build-pipeline-split.md","status":"in_progress","created_at":"2026-03-30","updated_at":"2026-03-30","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0009","file":"PLN-0009-compiler-pipeline-spec-and-contract-propagation.md","status":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]},{"id":"PLN-0010","file":"PLN-0010-refactor-builder-pipeline-service-into-entrypoints.md","status":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]},{"id":"PLN-0011","file":"PLN-0011-migrate-callsites-and-tests-to-build-compile-analyze.md","status":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]}],"lessons":[]}
+{"type":"discussion","id":"DSC-0011","status":"open","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[{"id":"AGD-0011","file":"AGD-0011-compiler-analyze-compile-build-pipeline-split.md","status":"accepted","created_at":"2026-03-30","updated_at":"2026-03-30"}],"decisions":[{"id":"DEC-0007","file":"DEC-0007-compiler-analyze-compile-build-pipeline-split.md","status":"in_progress","created_at":"2026-03-30","updated_at":"2026-03-30","ref_agenda":"AGD-0011"}],"plans":[{"id":"PLN-0009","file":"PLN-0009-compiler-pipeline-spec-and-contract-propagation.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]},{"id":"PLN-0010","file":"PLN-0010-refactor-builder-pipeline-service-into-entrypoints.md","status":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]},{"id":"PLN-0011","file":"PLN-0011-migrate-callsites-and-tests-to-build-compile-analyze.md","status":"review","created_at":"2026-03-30","updated_at":"2026-03-30","ref_decisions":["DEC-0007"]}],"lessons":[]}

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

@@ -2,9 +2,9 @@
 id: PLN-0009
 ticket: compiler-analyze-compile-build-pipeline-split
 title: Propagate DEC-0007 into compiler pipeline specs and public contracts
-status: review
+status: done
 created: 2026-03-30
-completed:
+completed: 2026-03-30
 tags:
   - compiler
   - pipeline

docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md

@@ -1,18 +1,19 @@
 # Backend Spec-to-Test Conformance Matrix
 
 Status: Draft v1 (Traceability Baseline)  
-Applies to: backend conformance traceability for `IRBackend -> IRVM -> OptimizeIRVM -> EmitBytecode`
+Applies to: compiler/backend conformance traceability for canonical stage order and entrypoint-specific contracts
 
-Last Updated: 2026-03-26
+Last Updated: 2026-03-30
 
 ## 1. Purpose
 
 This matrix maps each normative backend MUST from:
 
-1. `docs/general/specs/19. Verification and Safety Checks Specification.md`
-2. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
-3. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`
-4. `docs/pbs/specs/13. Lowering IRBackend Specification.md` (Section 12 addendum only)
+1. `docs/specs/compiler/19. Verification and Safety Checks Specification.md`
+2. `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
+3. `docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md`
+4. `docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md`
+5. `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md` (Section 12 addendum only)
 
 to concrete positive/negative test evidence and current status.
 
@@ -66,6 +67,13 @@ to concrete positive/negative test evidence and current status.
 | G21-9.1 | Validation MUST include optimized-vs-non-optimized equivalence fixtures. | `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLoweredHostIntrinsicFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForConditionalJoinFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForSimpleLoopFixture`; `OptimizeIRVMEquivalenceHarnessTest#optimizeOnOffMustPreserveObservableTraceForLinearCallFixture` | N/A | pass | Dedicated opt on/off harness with reusable interpreter and deterministic trace assertions is in place. |
 | G21-9.2 | Validation MUST preserve known negative loader/verifier behavior. | `BackendSafetyGateSUTest#emitStageMustExposeMarshalingLinkageFailureDeterministically`; `BackendGateIIntegrationTest` rejection suite | N/A | pass |  |
 | G21-9.3 | Validation MUST preserve deterministic artifact-level invariants. | `BackendSafetyGateSUTest#fullPipelineMustProduceDeterministicBytecodeForSameInput`; `BytecodeEmitterTest#emitMustRemainDeterministicAfterInterning` | N/A | pass |  |
+| G23-5.1 | Canonical compiler pipeline MUST preserve the shared stage order through `WriteBytecodeArtifact`. | `BuilderPipelineServiceOrderTest#canonicalOrderMustContainOptimizeBetweenLowerAndEmit` | N/A | partial | Current evidence covers the shared order through optimize/emission boundaries; explicit write-stage and entrypoint-boundary coverage still needs implementation. |
+| G23-6.1 | `analyze` MUST terminate after `FrontendPhase` and MUST NOT execute backend artifact stages. | N/A | N/A | missing | DEC-0007 and Chapter 23 are accepted; executable evidence will be added when explicit `analyze` entrypoint exists. |
+| G23-6.2 | `compile` MUST terminate after `VerifyBytecode` and MUST return a validated in-memory executable result without disk write. | N/A | N/A | missing | Requires explicit service-level and integration coverage after entrypoint refactor. |
+| G23-6.3 | `build` MUST extend `compile` only with terminal artifact persistence. | `MainProjectPipelineIntegrationTest#shouldCompileMainProjectAndWriteProgramBytecode` | N/A | partial | Existing build-path evidence predates the public `build` name and still needs migration to the explicit entrypoint API. |
+| G23-7.1 | `AnalysisSnapshot` MUST expose the minimum shared analysis contract. | N/A | N/A | missing | No executable contract object exists yet. |
+| G23-8.1 | Caller-specific configs/contexts MUST NOT redefine canonical stage semantics. | N/A | N/A | missing | Requires explicit multi-entrypoint composition tests once non-filesystem contexts are implemented. |
+| G23-9.1 | Legacy public `run` MUST be removed as the normative entrypoint and filesystem-default behavior MUST be expressed through `build`. | N/A | N/A | missing | Requires callsite migration and public API refactor. |
 | PBS13-12.0 | Executable backend handoff MUST satisfy addendum obligations. | `IRBackendExecutableContractTest` suite; `PBSFrontendPhaseServiceTest#shouldSynthesizePositiveTopic19FixtureAcrossFileInitProjectInitAndFrame` | `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticWrapperEntrypointIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenHiddenBootGuardIsMissing`; `LowerToIRVMServiceTest#lowerMustRejectWhenSyntheticCallableOriginIsMissing` | pass | Row group `PBS13-12.x` details each obligation; topic 19 closure now includes lifecycle wrapper/guard/origin evidence. |
 | PBS13-12.1.1 | Callable identity MUST be preserved at handoff. | `IRBackendExecutableContractTest#aggregatorMustPreserveExecutableFunctionOrderDeterministically` | N/A | pass |  |
 | PBS13-12.1.2 | Observable callable signature MUST be preserved at handoff. | `IRBackendExecutableContractTest#functionContractMustRejectInvalidSlotAndSpanBounds` | N/A | pass |  |

docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md

@@ -0,0 +1,241 @@
+# Compiler Pipeline Entry Points Specification
+
+Status: Draft v1 (Operational Entry-Point Baseline)  
+Applies to: canonical compiler entrypoints, stage-terminal boundaries, and result contracts for `analyze`, `compile`, and `build`
+
+## 1. Purpose
+
+This document defines the canonical operational entrypoints of the shared compiler pipeline.
+
+Its purpose is to make the compiler usable through explicit entrypoints instead of one monolithic public build invocation, while preserving one shared semantic pipeline for all supported frontends.
+
+## 2. Scope
+
+This document defines:
+
+- the canonical stage order shared by compiler entrypoints,
+- the terminal stage and mandatory behavior of `analyze`,
+- the terminal stage and mandatory behavior of `compile`,
+- the terminal stage and mandatory behavior of `build`,
+- the minimum public result contracts for those entrypoints,
+- and the context/config constraints that allow different callers without creating parallel pipeline semantics.
+
+This document does not define:
+
+- one mandatory Java class or package layout,
+- editor-specific source providers or document-session providers,
+- frontend-specific semantic facts beyond the minimum shared `AnalysisSnapshot` contract,
+- or one mandatory CLI architecture.
+
+## 3. Authority and Precedence
+
+Normative precedence:
+
+1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
+2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
+3. `14. Name Resolution and Module Linking Specification.md`
+4. `20. IRBackend to IRVM Lowering Specification.md`
+5. `21. IRVM Optimization Pipeline Specification.md`
+6. `15. Bytecode and PBX Mapping Specification.md`
+7. `19. Verification and Safety Checks Specification.md`
+8. This document
+
+If a rule here conflicts with a higher-precedence authority, it is invalid.
+
+## 4. Normative Inputs
+
+This document depends on:
+
+- `14. Name Resolution and Module Linking Specification.md`
+- `15. Bytecode and PBX Mapping Specification.md`
+- `19. Verification and Safety Checks Specification.md`
+- `20. IRBackend to IRVM Lowering Specification.md`
+- `21. IRVM Optimization Pipeline Specification.md`
+- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
+
+## 5. Canonical Shared Pipeline
+
+The compiler MUST expose one canonical shared pipeline.
+
+The canonical stage order is:
+
+1. `ResolveDepsPipelineStage`
+2. `LoadSourcesPipelineStage`
+3. `FrontendPhasePipelineStage`
+4. `LowerToIRVMPipelineStage`
+5. `OptimizeIRVMPipelineStage`
+6. `EmitBytecodePipelineStage`
+7. `LinkBytecodePipelineStage`
+8. `VerifyBytecodePipelineStage`
+9. `WriteBytecodeArtifactPipelineStage`
+
+Public entrypoints MAY terminate early according to this document, but they MUST NOT:
+
+1. reorder these stages,
+2. redefine their shared semantic meaning,
+3. or create parallel compiler pipelines under the same public entrypoint names.
+
+## 6. Entry Point Contracts
+
+### 6.1 `analyze`
+
+`analyze` MUST terminate at `FrontendPhasePipelineStage`.
+
+`analyze` is defined as:
+
+1. `ResolveDeps`
+2. `LoadSources`
+3. `FrontendPhase`
+
+`analyze` MUST:
+
+1. resolve workspace/dependency inputs needed by the frontend,
+2. load source surfaces admitted by the selected compiler configuration,
+3. run frontend semantic analysis,
+4. return an `AnalysisSnapshot` or equivalent result contract,
+5. and remain free of backend artifact side effects.
+
+`analyze` MUST NOT:
+
+1. lower to IRVM,
+2. optimize IRVM,
+3. emit bytecode,
+4. run bytecode link/verify gates,
+5. or persist artifact files.
+
+### 6.2 `compile`
+
+`compile` MUST terminate at `VerifyBytecodePipelineStage`.
+
+`compile` is defined as:
+
+1. `analyze`
+2. `LowerToIRVM`
+3. `OptimizeIRVM`
+4. `EmitBytecode`
+5. `LinkBytecode`
+6. `VerifyBytecode`
+
+`compile` MUST:
+
+1. preserve the canonical executable path used to produce an in-memory executable artifact,
+2. produce a validated executable result in memory,
+3. include bytecode emission, bytecode link precheck, and bytecode verification,
+4. and preserve the correctness expectations of the current executable path used by PBS.
+
+`compile` MUST NOT persist artifact files.
+
+### 6.3 `build`
+
+`build` MUST terminate at `WriteBytecodeArtifactPipelineStage`.
+
+`build` is defined as:
+
+1. `compile`
+2. `WriteBytecodeArtifact`
+
+`build` MUST:
+
+1. preserve the current default filesystem-oriented artifact behavior,
+2. write the executable artifact only after the `compile` contract has been satisfied,
+3. and remain the canonical artifact-materialization entrypoint for filesystem-backed callers.
+
+## 7. Result Contracts
+
+### 7.1 `AnalysisSnapshot`
+
+`AnalysisSnapshot` is the minimum shared result contract for `analyze`.
+
+`AnalysisSnapshot` MUST expose at minimum:
+
+1. diagnostics,
+2. semantic facts produced by the frontend,
+3. stable references to loaded sources, including the equivalent of `FileTable`,
+4. and workspace-resolution metadata required by tooling consumers.
+
+Implementations MAY add fields, but they MUST NOT omit those minimum elements.
+
+### 7.2 Compile result
+
+The `compile` result MUST expose at minimum:
+
+1. the validated in-memory executable artifact,
+2. the equivalent of `bytecodeModule`,
+3. the equivalent of serialized bytecode bytes,
+4. and enough metadata to allow `build` to persist the artifact without recompiling through another semantic path.
+
+### 7.3 Build result
+
+The `build` result MUST expose at minimum:
+
+1. the persisted artifact location,
+2. the compile payload from which the artifact was produced or an equivalent stable bridge to it,
+3. and the outcome needed by filesystem-backed callers to confirm successful artifact materialization.
+
+## 8. Context and Configuration Model
+
+The compiler MAY accept distinct config/context inputs per entrypoint in order to support CLI, editor, LSP, and other callers.
+
+Those configs/contexts MAY vary:
+
+1. source acquisition strategies,
+2. sinks or collectors,
+3. composition helpers,
+4. and the exact shape of public result wrappers.
+
+Those configs/contexts MUST NOT:
+
+1. change the canonical stage order for a given entrypoint,
+2. redefine stage semantics,
+3. or create an alternate semantic pipeline under the public names `analyze`, `compile`, or `build`.
+
+Filesystem-default composition MUST happen outside the pipeline core.
+
+## 9. Public Surface Rule
+
+The shared compiler public surface MUST expose explicit entrypoints equivalent in meaning to:
+
+1. `analyze(config, logs)`
+2. `compile(config, logs)`
+3. `build(config, logs)`
+
+The exact method or service names MAY vary, but the semantic split MUST remain explicit.
+
+The legacy public concept `run` MUST NOT remain the normative public entrypoint.
+The behavior previously associated with default `run` MUST be expressed as `build` with filesystem-oriented config/context assembled outside the pipeline itself.
+
+## 10. Compatibility Rule
+
+This document MUST preserve compatibility with the current executable path that produces artifacts for PBS.
+
+At minimum, that compatibility covers:
+
+1. the same semantic stage ordering up to executable artifact production,
+2. the same correctness envelope for the in-memory executable artifact before persistence,
+3. and no regression in emit/link/verify safety behavior.
+
+PBS is a baseline correctness consumer for this path, but PBS MUST NOT become an exclusive semantic owner of the public compiler entrypoint surface.
+
+## 11. Explicit Deferrals
+
+The following remain deferred:
+
+- editor-specific source-provider contracts,
+- richer multi-profile result types beyond the minimum contracts in this document,
+- and frontend-specific analysis payload extensions beyond the required shared `AnalysisSnapshot` minimum.
+
+## 12. Non-Goals
+
+- Creating separate public pipelines per frontend.
+- Replacing backend, bytecode, or runtime authority documents.
+- Freezing one internal implementation architecture prematurely.
+
+## 13. Exit Criteria
+
+This document is healthy when:
+
+1. the compiler entrypoints are explicit and stable,
+2. the terminal stage for each entrypoint is unambiguous,
+3. the minimum result contracts are explicit,
+4. `run` no longer acts as a normative public concept,
+5. and caller-specific contexts are constrained without opening semantic drift.

docs/specs/compiler/README.md

@@ -18,6 +18,7 @@ Current backend-facing chapter additions:
 - `20. IRBackend to IRVM Lowering Specification.md`
 - `21. IRVM Optimization Pipeline Specification.md`
 - `22. Backend Spec-to-Test Conformance Matrix.md`
+- `23. Compiler Pipeline Entry Points Specification.md`
 
 ## Rule