diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 15ef5907..a23868bf 100644 --- a/discussion/index.ndjson +++ b/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":[]} diff --git a/discussion/workflow/plans/PLN-0009-compiler-pipeline-spec-and-contract-propagation.md b/discussion/workflow/plans/PLN-0009-compiler-pipeline-spec-and-contract-propagation.md index d68be1cf..a975bed2 100644 --- a/discussion/workflow/plans/PLN-0009-compiler-pipeline-spec-and-contract-propagation.md +++ b/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 diff --git a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md b/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md index b664a119..5094ca69 100644 --- a/docs/specs/compiler/22. Backend Spec-to-Test Conformance Matrix.md +++ b/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 | | diff --git a/docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md b/docs/specs/compiler/23. Compiler Pipeline Entry Points Specification.md new file mode 100644 index 00000000..949b1908 --- /dev/null +++ b/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. diff --git a/docs/specs/compiler/README.md b/docs/specs/compiler/README.md index 8ef3606d..44f36d1d 100644 --- a/docs/specs/compiler/README.md +++ b/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