discussion framework migration
This commit is contained in:
@@ -0,0 +1,210 @@
|
||||
# PBS Lowering IRBackend Specification
|
||||
|
||||
Status: Draft v1 (Frontend Scope + Backend Handoff Addendum)
|
||||
Applies to: first lowering boundary from bound PBS frontend model into `IRBackend`/`IRBackendFile`, plus executable-backend handoff obligations at this boundary
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines the normative frontend lowering contract from PBS source semantics to `IRBackend`.
|
||||
|
||||
Its purpose is to keep the first lowering deterministic and shared across implementations while PBS and backend design evolve.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- required preconditions before lowering starts,
|
||||
- AST invariants that lowering may assume as hard contract,
|
||||
- semantic obligations preserved in `IRBackend`,
|
||||
- deterministic rejection behavior for unsupported frontend-lowering forms,
|
||||
- diagnostics attribution obligations for lowering failures in frontend scope,
|
||||
- and executable-backend handoff obligations at the `IRBackend` boundary.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- VM lowering (`IRVM`),
|
||||
- bytecode/PBX mapping,
|
||||
- runtime execution behavior,
|
||||
- verifier/loader internals.
|
||||
|
||||
Those concerns belong to shared acceptance specs under `docs/general/specs`.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `3. Core Syntax Specification.md`
|
||||
2. `4. Static Semantics Specification.md`
|
||||
3. `11. AST Specification.md`
|
||||
4. `12. Diagnostics Specification.md`
|
||||
5. This document
|
||||
|
||||
If a lowering rule here conflicts with higher-precedence syntax/semantics rules, the higher-precedence rule wins.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `3. Core Syntax Specification.md`
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
||||
|
||||
## 5. Lowering Preconditions
|
||||
|
||||
Frontend lowering into `IRBackend` may start only when:
|
||||
|
||||
1. source has been tokenized and parsed,
|
||||
2. required syntax diagnostics have been emitted,
|
||||
3. AST output satisfies `11` required invariants for this source unit, including:
|
||||
- one root per file,
|
||||
- deterministic child ordering,
|
||||
- mandatory node attribution (`file/start/end`) on nodes consumed by lowering,
|
||||
- mandatory declaration metadata on declaration nodes required by the active source slice,
|
||||
- and structural coherence after any parser recovery.
|
||||
4. linking/name-resolution outcomes required for the current lowering slice are available,
|
||||
5. and no unresolved semantic ambiguity is deferred to lowering.
|
||||
|
||||
Lowering must not invent unresolved semantic answers that belong to syntax/static/linking phases.
|
||||
|
||||
## 6. IRBackend Preserved Obligations
|
||||
|
||||
For each admitted source unit and callable in the current lowering slice, `IRBackend` must preserve at minimum:
|
||||
|
||||
1. callable identity (name/category as applicable),
|
||||
2. callable arity,
|
||||
3. declared return surface information,
|
||||
4. source attribution anchor (`file + span`) for diagnostics and traceability,
|
||||
5. source-observable parse intent for statement/expression structure (including precedence/associativity outcome already fixed by AST shape).
|
||||
6. deterministic `requiredCapabilities` derived from admitted host-binding metadata for packer/runtime-manifest assistance.
|
||||
7. frontend-declared executable `EntrypointRef` (`entryPointCallableName` + `entryPointModuleId`) for backend handoff.
|
||||
|
||||
Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.
|
||||
|
||||
The normative contract is obligation-based, not tied to one mandatory in-memory class graph.
|
||||
|
||||
## 7. Deterministic Rejection Policy
|
||||
|
||||
If a source form is outside current frontend-lowering support:
|
||||
|
||||
1. rejection must be deterministic,
|
||||
2. diagnostics must expose stable `code`, `severity`, `phase`, `message template id`, and primary attribution,
|
||||
3. and unsupported forms must not silently degrade into different valid lowered behavior.
|
||||
|
||||
Lowering must not convert a required syntax/static rejection into accepted lowered behavior.
|
||||
|
||||
For multi-module builds, lowering admission must apply dependency-scoped fail-fast:
|
||||
|
||||
1. a module rejected in syntax, static semantics, linking, host-admission, or load-facing gates must not be emitted;
|
||||
2. any module that imports a rejected module (directly or transitively) must also be excluded from `IRBackend` emission;
|
||||
3. modules independent from the rejected dependency subgraph may continue to lower and emit in the same build.
|
||||
|
||||
## 8. Conformance Boundary
|
||||
|
||||
`IRBackend` is the first lowering boundary (frontend responsibility).
|
||||
|
||||
Conformance-valid claims at this boundary require Gate U evidence from `docs/general/specs/13. Conformance Test Specification.md`.
|
||||
|
||||
For this frontier, Gate U evidence is expected to cover at minimum:
|
||||
|
||||
- lexer behavior for covered inputs,
|
||||
- parser behavior and AST shape invariants required by `11`,
|
||||
- lowering outcomes at `IRBackend` boundary,
|
||||
- and deterministic diagnostics identity/attribution for rejection cases.
|
||||
|
||||
Conformance at this boundary may be claimed only when the full claimed PBS source surface is implemented at `IRBackend` level.
|
||||
|
||||
## 9. Explicit Deferrals
|
||||
|
||||
The following are intentionally out of scope for this document:
|
||||
|
||||
- `IRBackend -> IRVM` lowering,
|
||||
- artifact encoding and binary layout,
|
||||
- runtime lifecycle behavior,
|
||||
- verifier and loader checks.
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
- Freezing one optimizer strategy.
|
||||
- Freezing one compiler architecture.
|
||||
- Repeating runtime or bytecode authority.
|
||||
|
||||
## 11. Exit Criteria
|
||||
|
||||
This document is healthy when:
|
||||
|
||||
1. lowering preconditions are explicit,
|
||||
2. preserved `IRBackend` obligations are explicit,
|
||||
3. deterministic rejection policy is explicit and test-backed,
|
||||
4. and scope boundaries with general/backend acceptance specs are explicit.
|
||||
|
||||
## 12. Executable Backend Handoff Addendum (v1)
|
||||
|
||||
For executable backends, the `IRBackend` output from this frontend boundary must satisfy the additional handoff obligations below.
|
||||
|
||||
### 12.1 Callable obligations
|
||||
|
||||
For each executable callable admitted into `IRBackend`, the frontend must preserve:
|
||||
|
||||
1. stable callable identity in the current build graph,
|
||||
2. observable callable signature (input arity and return shape),
|
||||
3. callable category needed by downstream lowering,
|
||||
4. source attribution anchor (`fileId`, `start`, `end`),
|
||||
5. and executable body representation that is backend-lowerable.
|
||||
|
||||
### 12.2 Callsite classification obligations
|
||||
|
||||
Each executable callsite in `IRBackend` must be classified into exactly one category:
|
||||
|
||||
1. `CALL_FUNC`,
|
||||
2. `CALL_HOST`,
|
||||
3. `CALL_INTRINSIC`.
|
||||
|
||||
Backend lowering must not infer this category by textual heuristics.
|
||||
|
||||
### 12.3 Host-backed metadata obligations
|
||||
|
||||
Each host-backed callsite admitted at this boundary must preserve canonical host identity:
|
||||
|
||||
1. `module`,
|
||||
2. `name`,
|
||||
3. `version`.
|
||||
|
||||
When available at this boundary, declared host ABI shape (`arg_slots`, `ret_slots`) must also be preserved for downstream validation.
|
||||
|
||||
### 12.4 VM-owned metadata obligations
|
||||
|
||||
VM-owned intrinsic callsites admitted at this boundary must preserve canonical intrinsic identity:
|
||||
|
||||
1. `canonicalName`,
|
||||
2. `canonicalVersion`.
|
||||
|
||||
VM-owned builtin projections/constants/intrinsics must not be reclassified as host bindings.
|
||||
|
||||
### 12.5 Deterministic capability obligations
|
||||
|
||||
`requiredCapabilities` derived at this boundary must be deterministic for the same admitted input graph.
|
||||
|
||||
### 12.6 Boundary with backend lowering specs
|
||||
|
||||
This addendum defines obligations preserved at the `IRBackend` boundary only.
|
||||
|
||||
It does not replace:
|
||||
|
||||
1. `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`,
|
||||
2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`,
|
||||
3. or `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
|
||||
### 12.7 FrontendSpec Entry Point Obligation
|
||||
|
||||
For executable language frontends, `FrontendSpec` must declare one canonical qualified entrypoint reference (`EntrypointRef`):
|
||||
|
||||
1. `entryPointCallableName`,
|
||||
2. `entryPointModuleId`.
|
||||
|
||||
At `IRBackend` emission time:
|
||||
|
||||
1. frontend must copy this declaration into `IRBackend.entryPointCallableName` and `IRBackend.entryPointModuleId`,
|
||||
2. both values must be non-blank/non-none and deterministic for the same language/spec version,
|
||||
3. and backend stages must treat this qualified reference as authoritative for entrypoint selection instead of name-only fallbacks or hardcoded language-agnostic names.
|
||||
Reference in New Issue
Block a user