280 lines
10 KiB
Markdown
280 lines
10 KiB
Markdown
# 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`
|
|
- the frontend-owned semantic presentation contract published through `FrontendSpec`
|
|
|
|
## 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.
|
|
|
|
## 8.1 FrontendSpec-Owned Semantic Presentation Contract
|
|
|
|
`FrontendSpec` MUST remain the canonical static contract surface for frontend-owned semantic presentation metadata.
|
|
|
|
At minimum, that contract MUST allow frontend publication of:
|
|
|
|
1. stable frontend-owned `semanticKeys`,
|
|
2. frontend-owned `resources`,
|
|
3. and enough static metadata for downstream semantic consumers to derive a consumable descriptor without inventing host-owned fallback semantics.
|
|
|
|
This contract MUST NOT:
|
|
|
|
1. move frontend semantic presentation ownership into Studio,
|
|
2. move frontend semantic presentation ownership into LSP,
|
|
3. or force frontend semantic output into a shared artificial host vocabulary.
|
|
|
|
Tooling consumers such as integrated LSP and Studio MAY derive downstream descriptors from `FrontendSpec`, but they MUST treat `FrontendSpec` as the canonical source rather than a host-owned replacement contract.
|
|
|
|
## 8.2 Frontend-Owned Inline Hint Contract Authority
|
|
|
|
Frontend-owned inline hint semantics MUST remain frontend-authored even when transported through tooling consumers.
|
|
|
|
When downstream semantic consumers require static contract metadata for inline hints, that metadata MUST come from `FrontendSpec` or from another accepted frontend-owned contract surface explicitly introduced for that purpose.
|
|
|
|
At minimum, any accepted frontend-owned inline hint contract authority MUST preserve:
|
|
|
|
1. frontend ownership of hint existence policy,
|
|
2. frontend ownership of hint semantic meaning,
|
|
3. enough contract metadata for `prometeu-lsp` to transport hint payloads without inventing host-owned semantics,
|
|
4. and enough contract clarity for Studio to render hints mechanically rather than semantically reinterpret them.
|
|
|
|
This authority model MUST NOT:
|
|
|
|
1. move semantic inline hint ownership into Studio,
|
|
2. move semantic inline hint policy into LSP,
|
|
3. or imply that the host editor may synthesize semantic hints when the frontend did not publish them.
|
|
|
|
## 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.
|