implements PR-19.1 normative spec propagation
This commit is contained in:
parent
38d8c25bba
commit
82d2bfafb8
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -75,7 +75,8 @@ Mandatory declaration metadata on required declaration nodes includes:
|
||||
1. declaration name,
|
||||
2. declared signature/surface when applicable (parameters/return),
|
||||
3. declaration-level syntactic flags/attributes required by later phases,
|
||||
4. stable `file/start/end` attribution.
|
||||
4. stable `file/start/end` attribution,
|
||||
5. lifecycle-marker metadata when a declaration carries `[Init]` or `[Frame]`.
|
||||
|
||||
Missing required attribution or metadata on mandatory nodes is non-conformant.
|
||||
|
||||
@ -91,11 +92,18 @@ The v1 AST must represent, at minimum, declaration families for:
|
||||
- `error`,
|
||||
- `enum`,
|
||||
- `callback`,
|
||||
- `declare global`,
|
||||
- `declare const`,
|
||||
- and declaration nodes required by barrel/linking flow.
|
||||
|
||||
Declaration identity must be preserved at AST boundary; implementations must not prematurely merge/collapse declarations (including overload sets).
|
||||
|
||||
Lifecycle-observable declarations must preserve marker metadata explicitly:
|
||||
|
||||
- top-level `fn` marked with `[Init]`,
|
||||
- top-level `fn` marked with `[Frame]`,
|
||||
- and host method signatures marked with `[InitAllowed]`.
|
||||
|
||||
## 9. Mandatory Statement and Expression Families
|
||||
|
||||
The v1 AST must represent statement/expression families for the supported core syntax slice, including at minimum:
|
||||
@ -130,7 +138,7 @@ For conformance, required diagnostic identity is keyed by stable machine fields,
|
||||
|
||||
## 12. Conformance and Gate U Evidence
|
||||
|
||||
AST conformance evidence is provided through Gate U fixtures as defined in `docs/general/specs/13. Conformance Test Specification.md`.
|
||||
AST conformance evidence is provided through Gate U fixtures as defined in `docs/specs/compiler/13. Conformance Test Specification.md`.
|
||||
|
||||
At minimum, Gate U must include:
|
||||
|
||||
|
||||
@ -67,9 +67,9 @@ This document depends on, at minimum:
|
||||
|
||||
Relevant backend-facing integration points also include:
|
||||
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
|
||||
- `docs/general/specs/19. Verification and Safety Checks Specification.md`
|
||||
- `docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/specs/compiler/16. Runtime Execution and Initialization Specification.md`
|
||||
- `docs/specs/compiler/19. Verification and Safety Checks Specification.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
@ -82,6 +82,7 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
||||
- Stable source span metadata is required at the token level and must remain useful to later diagnostics.
|
||||
- Traps are fatal runtime outcomes rather than a recoverable userland diagnostic flow.
|
||||
- Qualitative cost facts such as retention-bearing operations and host-boundary crossings are normative, but quantitative performance metrics are not.
|
||||
- Topic `19` requires deterministic diagnostics for globals, lifecycle markers, init admission, and published-wrapper structural failures.
|
||||
|
||||
## 6. Required Diagnostic Phases
|
||||
|
||||
@ -179,6 +180,25 @@ At minimum, the PBS diagnostics baseline must cover:
|
||||
5. malformed, unauthorized, or capability-rejected host usage required by `6.2. Host ABI Binding and Loader Resolution Specification.md` and `7. Cartridge Manifest and Runtime Capabilities Specification.md`,
|
||||
6. source-attributable backend-originated failures that remain user-actionable under normative lowering or load-facing rules.
|
||||
7. dependency-scoped fail-fast admission at frontend boundary: when one module is rejected, modules that import it (directly or transitively) must not be emitted, while diagnostics collection for independent modules must continue.
|
||||
8. lifecycle and globals diagnostics required by topic `19`, including:
|
||||
- `global initializer uses unsupported form`,
|
||||
- `global dependency cycle detected`,
|
||||
- `global import must resolve through a global barrel entry`,
|
||||
- `imported symbol shadows existing visible symbol; alias required`,
|
||||
- `init function must have signature fn name() -> void`,
|
||||
- `frame function must have signature fn name() -> void`,
|
||||
- `multiple module init functions detected`,
|
||||
- `multiple project init functions detected`,
|
||||
- `multiple frame functions detected`,
|
||||
- `missing frame function for executable project`,
|
||||
- `project init must be colocated with frame`,
|
||||
- `Init attribute target invalid`,
|
||||
- `InitAllowed is valid only on SDK host methods`,
|
||||
- `host call not allowed during init`,
|
||||
- `synthetic wrapper entrypoint missing`,
|
||||
- `published entrypoint is not function index 0`,
|
||||
- `hidden boot guard is missing`,
|
||||
- `synthetic callable origin missing`.
|
||||
|
||||
At minimum, host-admission diagnostics must cover missing or malformed host capability metadata and unknown or undeclared capability names.
|
||||
|
||||
|
||||
@ -27,7 +27,7 @@ This document does not define:
|
||||
- runtime execution behavior,
|
||||
- verifier/loader internals.
|
||||
|
||||
Those concerns belong to shared acceptance specs under `docs/general/specs`.
|
||||
Those concerns belong to shared acceptance specs under `docs/specs/compiler`.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
@ -49,7 +49,7 @@ This document depends on:
|
||||
- `4. Static Semantics Specification.md`
|
||||
- `11. AST Specification.md`
|
||||
- `12. Diagnostics Specification.md`
|
||||
- `docs/general/specs/20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`
|
||||
|
||||
## 5. Lowering Preconditions
|
||||
|
||||
@ -78,7 +78,8 @@ For each admitted source unit and callable in the current lowering slice, `IRBac
|
||||
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.
|
||||
7. compiler-selected published-wrapper entrypoint identity for backend handoff,
|
||||
8. explicit global and synthetic lifecycle structure required by executable lowering.
|
||||
|
||||
Lowering must not collapse source categories in a way that erases required declaration/callable identity needed by downstream diagnostics or conformance assertions.
|
||||
|
||||
@ -104,7 +105,7 @@ For multi-module builds, lowering admission must apply dependency-scoped fail-fa
|
||||
|
||||
`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`.
|
||||
Conformance-valid claims at this boundary require Gate U evidence from `docs/specs/compiler/13. Conformance Test Specification.md`.
|
||||
|
||||
For this frontier, Gate U evidence is expected to cover at minimum:
|
||||
|
||||
@ -192,19 +193,24 @@ 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`.
|
||||
1. `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`,
|
||||
2. `docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md`,
|
||||
3. or `docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md`.
|
||||
|
||||
### 12.7 FrontendSpec Entry Point Obligation
|
||||
### 12.7 Executable Lifecycle and Published Wrapper Obligation
|
||||
|
||||
For executable language frontends, `FrontendSpec` must declare one canonical qualified entrypoint reference (`EntrypointRef`):
|
||||
|
||||
1. `entryPointCallableName`,
|
||||
2. `entryPointModuleId`.
|
||||
For executable PBS frontends, backend handoff must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint.
|
||||
|
||||
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.
|
||||
1. the lowered graph must contain explicit lifecycle structure for:
|
||||
- user-authored globals,
|
||||
- file init fragments,
|
||||
- module init,
|
||||
- project init when present,
|
||||
- and the published frame wrapper,
|
||||
2. the published frame wrapper must be the effective entrypoint identity handed to backend stages,
|
||||
3. the userland callable marked with `[Frame]` must remain distinguishable as the logical frame root,
|
||||
4. the wrapper must own final `FRAME_RET`,
|
||||
5. backend stages must not reintroduce manifest-owned or `FrontendSpec`-owned nominal entrypoint authority,
|
||||
6. and hidden compiler-owned lifecycle state such as the boot guard must remain structurally distinguishable from user globals.
|
||||
|
||||
@ -77,7 +77,7 @@ Active keywords in `.pbs`:
|
||||
|
||||
- `import`, `from`, `as`
|
||||
- `service`, `host`, `fn`, `apply`, `bind`, `new`, `implements`, `using`, `ctor`
|
||||
- `declare`, `struct`, `contract`, `error`, `enum`, `callback`, `Self`, `this`
|
||||
- `declare`, `struct`, `contract`, `error`, `enum`, `callback`, `global`, `Self`, `this`
|
||||
- `pub`, `mut`
|
||||
- `let`, `const`
|
||||
- `if`, `else`, `switch`, `default`, `for`, `from`, `until`, `step`, `while`, `break`, `continue`, `return`
|
||||
@ -154,6 +154,7 @@ BarrelItem ::= BarrelFnItem
|
||||
| BarrelErrorItem
|
||||
| BarrelEnumItem
|
||||
| BarrelServiceItem
|
||||
| BarrelGlobalItem
|
||||
| BarrelConstItem
|
||||
| BarrelCallbackItem
|
||||
BarrelVisibility ::= 'mod' | 'pub'
|
||||
@ -165,6 +166,7 @@ BarrelHostItem ::= BarrelVisibility 'host' Identifier ';'
|
||||
BarrelErrorItem ::= BarrelVisibility 'error' Identifier ';'
|
||||
BarrelEnumItem ::= BarrelVisibility 'enum' Identifier ';'
|
||||
BarrelServiceItem ::= BarrelVisibility 'service' Identifier ';'
|
||||
BarrelGlobalItem ::= BarrelVisibility 'global' Identifier ';'
|
||||
BarrelConstItem ::= BarrelVisibility 'const' Identifier ';'
|
||||
BarrelCallbackItem ::= BarrelVisibility 'callback' Identifier ';'
|
||||
```
|
||||
@ -187,6 +189,7 @@ Rules:
|
||||
- A `struct` barrel entry governs the visibility of the struct declaration and of all methods declared directly in that struct body.
|
||||
- A `host` barrel entry governs the visibility of the host declaration and of all method signatures declared directly in that host body.
|
||||
- A `service` barrel entry governs the visibility of the service declaration, its canonical singleton value, and all methods declared directly in that service body.
|
||||
- A `global` barrel entry governs visibility of one top-level `declare global` declaration.
|
||||
- Methods declared inside a `struct`, `host`, or `service` are never exported independently through `mod.barrel`.
|
||||
|
||||
Example:
|
||||
@ -199,6 +202,7 @@ pub contract TickLike;
|
||||
pub host Gfx;
|
||||
pub enum GameState;
|
||||
pub service Physics;
|
||||
pub global Palette;
|
||||
pub callback TickCb;
|
||||
```
|
||||
|
||||
@ -245,7 +249,9 @@ Rules:
|
||||
- An attribute attaches syntactic metadata to the declaration surface that immediately follows it.
|
||||
- Attributes do not introduce values, types, callables, or modules by themselves.
|
||||
- In v1 core, ordinary user-authored modules MUST reject attributes unless another specification explicitly permits them.
|
||||
- Ordinary userland source MAY use `[Init]` and `[Frame]` only on top-level `fn` declarations.
|
||||
- Reserved stdlib/toolchain interface modules MAY use attributes where explicitly allowed by syntax and semantics.
|
||||
- Reserved stdlib/toolchain interface modules MAY additionally use `[InitAllowed]` only on `declare host` method signatures where another specification explicitly permits it.
|
||||
- Attribute interpretation is compile-time only unless another specification explicitly lowers its effect into runtime-facing metadata.
|
||||
- Reserved attribute names used by builtin-type and intrinsic shells do not become ordinary value-level syntax.
|
||||
- `Slot(...)` is not part of the v1 attribute surface; source that uses `Slot` must be rejected in syntax phase.
|
||||
@ -253,7 +259,7 @@ Rules:
|
||||
### 6.2 Top-level declarations
|
||||
|
||||
```ebnf
|
||||
TopDecl ::= TypeDecl | CallbackDecl | FunctionDecl | ConstDecl | ImplDecl
|
||||
TopDecl ::= TypeDecl | CallbackDecl | FunctionDecl | GlobalDecl | ConstDecl | ImplDecl
|
||||
```
|
||||
|
||||
Top-level `let` forms and top-level executable statements are forbidden.
|
||||
@ -294,6 +300,7 @@ EnumCaseDecl ::= Identifier ('=' IntLit)?
|
||||
ImplDecl ::= 'implements' Identifier 'for' Identifier 'using' Identifier ImplBody
|
||||
ImplBody ::= '{' ImplMethodDecl* '}'
|
||||
ImplMethodDecl ::= 'fn' Identifier ParamList ReturnAnn? Block
|
||||
GlobalDecl ::= 'declare' 'global' Identifier ':' TypeRef '=' Expr ';'
|
||||
```
|
||||
|
||||
Rules:
|
||||
@ -329,6 +336,11 @@ Rules:
|
||||
- Builtin method signatures MAY carry reserved VM-owned metadata such as `IntrinsicCall(...)`.
|
||||
- `declare error` bodies contain only error case labels.
|
||||
- `declare enum` uses a parenthesized case list and ends with `;`.
|
||||
- `declare global Name: T = expr;` declares module-owned runtime storage.
|
||||
- `declare global` requires an explicit type annotation and an explicit initializer.
|
||||
- `declare global` is distinct from `declare const` and is not syntactic sugar for `const`.
|
||||
- `declare global` participates in `mod.barrel` visibility only through explicit `global` entries.
|
||||
- The admissible initializer slice for `declare global` is intentionally restricted by static semantics.
|
||||
- Error case labels in the same `declare error` body must be unique.
|
||||
- Enum case labels in the same `declare enum` must be unique.
|
||||
- If no enum case uses `=`, case identifiers default to ascending integer values starting at `0` in declaration order.
|
||||
@ -416,6 +428,7 @@ Rules:
|
||||
- Methods declared inside a `declare host` body are signature-only host-backed call surfaces.
|
||||
- A host method signature in a reserved stdlib/interface module MAY carry attributes.
|
||||
- `[Host(module = "...", name = "...", version = N)]` is the canonical reserved attribute surface for host-binding metadata in v1 core.
|
||||
- `[InitAllowed]` is a reserved SDK-only attribute surface for host methods admitted during init.
|
||||
- Service-shaped wrappers over host calls MAY exist as SDK/stdlib design patterns, but they do not replace canonical `declare host` bindings.
|
||||
|
||||
### 7.6 Top-level constants
|
||||
|
||||
@ -40,7 +40,7 @@ Rules:
|
||||
|
||||
- `declare struct`, `declare service`, `declare contract`, `declare error`, `declare enum`, `declare callback`, and `declare builtin type` introduce names in the type namespace.
|
||||
- `declare host` introduces names in the host-owner namespace.
|
||||
- `let`, parameters, and `declare const` introduce names in the value namespace.
|
||||
- `let`, parameters, `declare const`, and `declare global` introduce names in the value namespace.
|
||||
- `declare service Name` also introduces the canonical singleton value `Name` in the value namespace.
|
||||
- Top-level `fn`, service methods, and host methods participate in the callable namespace.
|
||||
- `fn` declarations are not first-class values in v1 core and therefore do not become ordinary value expressions.
|
||||
@ -62,9 +62,12 @@ Rules:
|
||||
- Attributes are not first-class values and are not reflectable in v1 core.
|
||||
- Attributes do not automatically survive into runtime or bytecode artifacts.
|
||||
- An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `BuiltinType`, `BuiltinConst`, and `IntrinsicCall`.
|
||||
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, and `InitAllowed`.
|
||||
- `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Capability` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Init` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
|
||||
- `Frame` is valid only on a top-level userland `fn` declaration with lifecycle-admissible signature.
|
||||
- `InitAllowed` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
|
||||
- `Host` is invalid on ordinary user-authored modules, top-level `fn`, struct methods, service methods, callbacks, contracts, and constants.
|
||||
- `Host` metadata is consumed by the compiler during host-binding lowering.
|
||||
- The `Host` attribute syntax itself is not exported as runtime metadata; instead, its canonical identity participates in PBX host-binding emission as defined by the Host ABI Binding specification.
|
||||
@ -72,6 +75,8 @@ Rules:
|
||||
- `BuiltinConst` is valid only on a reserved top-level `declare const` declaration that omits an initializer.
|
||||
- `IntrinsicCall` is valid only on a method signature declared directly inside a reserved `declare builtin type` body.
|
||||
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
|
||||
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
|
||||
- `InitAllowed` is consumed by init-time host-admission analysis and does not become ordinary userland metadata.
|
||||
|
||||
### 2.4 Tuple shapes
|
||||
|
||||
@ -168,6 +173,20 @@ Rules:
|
||||
- Any return surface that combines `optional` and `result` is statically invalid.
|
||||
- Any payload-less `optional` type surface is statically invalid.
|
||||
- Any `optional void` type surface is statically invalid.
|
||||
- A `declare global` declaration must include an explicit type annotation.
|
||||
- A `declare global` declaration must include an explicit initializer.
|
||||
- `declare global` initializer analysis is dependency-graph based rather than source-order based.
|
||||
- A `declare global` initializer may depend on other visible globals only through their canonical owner identity.
|
||||
- Cycles between globals are statically invalid.
|
||||
- A global import is valid only when the imported symbol resolves through a `global` entry in `mod.barrel`.
|
||||
- Imported visible names from `fn`, `service`, `global`, and `const` must not collide with already-visible names in those same cross-category spaces; aliasing is required to disambiguate.
|
||||
- `[Init]` and `[Frame]` are valid only on top-level `fn` declarations of shape `fn name() -> void`.
|
||||
- `[Frame]` is required exactly once for an executable project.
|
||||
- `[Init]` is optional.
|
||||
- A file may declare at most one `[Init]`.
|
||||
- The `[Init]` colocated with `[Frame]` is the project init.
|
||||
- Project init must be colocated with `[Frame]`.
|
||||
- `InitAllowed` is valid only on SDK host methods and is invalid on userland `fn`, `global`, `service`, `const`, `struct`, `contract`, and callback surfaces.
|
||||
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Host` attribute.
|
||||
- A host method signature in a reserved stdlib/interface module MUST carry exactly one `Capability` attribute.
|
||||
- A `Host` attribute MUST declare exactly the named arguments `module`, `name`, and `version`.
|
||||
@ -231,6 +250,19 @@ Rules:
|
||||
- A `BuiltinConst` declaration is not part of ordinary compile-time constant evaluation and lowers through VM-owned builtin constant materialization instead.
|
||||
- A `declare const` exported through `mod.barrel` may be imported from another module only through ordinary module import rules.
|
||||
- A `declare const` does not introduce mutable runtime storage; implementations may inline, fold, or materialize it as an immutable constant as long as observable semantics remain unchanged.
|
||||
- These `declare const` rules do not define `declare global` initializer admissibility.
|
||||
- `declare global` initializers are not general procedural bootstrap surfaces.
|
||||
- In v1, a `declare global` initializer may use:
|
||||
- primitive literals and simple value operations,
|
||||
- value-bearing member access,
|
||||
- `new Struct(...)`,
|
||||
- and reads of other globals that preserve an acyclic dependency graph.
|
||||
- In v1, a `declare global` initializer must reject:
|
||||
- top-level `fn` calls,
|
||||
- `some(...)`,
|
||||
- `none`,
|
||||
- `if`,
|
||||
- and `switch`.
|
||||
|
||||
### 3.5 Enum declarations and values
|
||||
|
||||
|
||||
@ -45,7 +45,6 @@ It is produced by cartridge packaging tooling and consumed by the runtime loader
|
||||
The manifest currently carries:
|
||||
|
||||
- cartridge identity and metadata,
|
||||
- app entry information,
|
||||
- asset metadata,
|
||||
- preload metadata.
|
||||
|
||||
@ -63,7 +62,6 @@ The current manifest shape relevant to this document is:
|
||||
"title": "Example",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "game",
|
||||
"entrypoint": "frame",
|
||||
"capabilities": ["gfx", "input"],
|
||||
"asset_table": [],
|
||||
"preload": []
|
||||
@ -74,10 +72,10 @@ Rules:
|
||||
|
||||
- `magic` identifies a Prometeu cartridge manifest,
|
||||
- `cartridge_version` identifies the cartridge manifest format line,
|
||||
- `entrypoint` identifies the runtime entrypoint,
|
||||
- for PBS v1, `entrypoint` should align with frontend-declared callable (`frame`),
|
||||
- `capabilities` declares the cartridge's requested runtime capabilities,
|
||||
- `asset_table` and `preload` remain separate concerns.
|
||||
- `manifest.json` MUST NOT declare nominal entrypoint authority for PBS v1 executable boot.
|
||||
- Runtime boot authority is the physical published entrypoint at function index `0`.
|
||||
|
||||
## 5. `capabilities`
|
||||
|
||||
@ -246,3 +244,4 @@ The current temporary contract is:
|
||||
5. The loader converts nominal manifest capabilities into internal flags.
|
||||
6. PBX `SYSC` declares required host bindings, not authority.
|
||||
7. Loader validation fails if PBX host requirements exceed granted cartridge capabilities.
|
||||
8. `manifest.json` is not entrypoint authority for PBS v1 boot.
|
||||
|
||||
@ -63,6 +63,8 @@ This document integrates the following accepted decisions:
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Effect Surfaces Decision.md`
|
||||
- `docs/pbs/decisions/Dynamic Semantics - Branch Selection Decision.md`
|
||||
- `docs/pbs/decisions/Host Memory Boundary Decision.md`
|
||||
- `docs/compiler/pbs/decisions/Lifecycle Markers, Program Init, and Frame Root Semantics Decision.md`
|
||||
- `docs/compiler/pbs/decisions/Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md`
|
||||
|
||||
## 5. Already-Settled Inputs
|
||||
|
||||
@ -75,6 +77,8 @@ The following inputs are already fixed elsewhere and must not be contradicted he
|
||||
- `optional T` function fallthrough yields `none`.
|
||||
- `result<E>` function fallthrough is a compile-time error.
|
||||
- `ok(...)` and `err(...)` are special result-flow forms rather than ordinary first-class runtime constructors.
|
||||
- Lifecycle bootstrap is one-shot and fail-fast.
|
||||
- `[Frame]` denotes the logical userland frame root, not the physical published entrypoint by itself.
|
||||
|
||||
## 6. Execution Baseline
|
||||
|
||||
@ -95,6 +99,35 @@ VM-internal frame layout, temporary storage, and lowering steps are not observab
|
||||
|
||||
`FRAME_SYNC` is the only normative safepoint in PBS v1.
|
||||
|
||||
## 6.1 Lifecycle bootstrap
|
||||
|
||||
Executable PBS programs have a logical bootstrap sequence before ordinary frame execution.
|
||||
|
||||
Normative order:
|
||||
|
||||
1. materialize globals for each file according to dependency order,
|
||||
2. execute that file's `[Init]`, if present,
|
||||
3. compose those steps into one synthetic module init per module,
|
||||
4. execute project init, if present,
|
||||
5. then invoke the userland callable marked with `[Frame]`.
|
||||
|
||||
Lifecycle bootstrap is one-shot:
|
||||
|
||||
- no automatic retry occurs after boot failure,
|
||||
- failure during module init aborts boot,
|
||||
- failure during project init aborts boot.
|
||||
|
||||
## 6.2 Logical frame root and physical wrapper
|
||||
|
||||
PBS distinguishes the logical frame root from the physical published entrypoint:
|
||||
|
||||
- the userland callable marked with `[Frame]` is the logical frame root,
|
||||
- the compiler-published synthetic wrapper is the physical executable root,
|
||||
- the wrapper owns final `FRAME_RET`,
|
||||
- and the wrapper invokes the logical frame root after bootstrap is complete.
|
||||
|
||||
Nominal manifest metadata does not participate in this runtime boot choice.
|
||||
|
||||
## 7. Evaluation Order and Single Evaluation
|
||||
|
||||
### 7.1 Default rule
|
||||
|
||||
@ -30,8 +30,8 @@ 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. `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
5. `20. IRBackend to IRVM Lowering Specification.md`
|
||||
6. `21. IRVM Optimization Pipeline Specification.md`
|
||||
7. This document
|
||||
@ -42,8 +42,8 @@ If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
This document depends on, at minimum:
|
||||
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `20. IRBackend to IRVM Lowering Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
@ -76,11 +76,16 @@ Emitter output must map to a `BytecodeModule` shape containing:
|
||||
|
||||
Function ordering must be deterministic:
|
||||
|
||||
1. entrypoint function index is `0`,
|
||||
2. entrypoint index `0` is selected from qualified `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
1. the published wrapper function index is `0`,
|
||||
2. function index `0` is owned by the compiler-selected physical wrapper rather than by manifest metadata or nominal export lookup,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. identical admitted input graph yields identical function ordering and function ids.
|
||||
|
||||
For PBS executable publication:
|
||||
|
||||
- the userland callable marked with `[Frame]` is not itself the physical entrypoint unless it is wrapped by the published synthetic wrapper,
|
||||
- final `FRAME_RET` belongs to the wrapper path.
|
||||
|
||||
### 6.3 Function code layout
|
||||
|
||||
Emitter must satisfy:
|
||||
|
||||
@ -33,7 +33,7 @@ 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. `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
3. `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
@ -42,9 +42,9 @@ If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `15. Bytecode and PBX Mapping Specification.md`
|
||||
- `21. IRVM Optimization Pipeline Specification.md`
|
||||
|
||||
@ -56,9 +56,7 @@ Lowering from `IRBackend` to `IRVM` may start only when:
|
||||
2. required callsite categories (`CALL_FUNC`/`CALL_HOST`/`CALL_INTRINSIC`) are available,
|
||||
3. required canonical host/intrinsic metadata is available for admitted callsites,
|
||||
4. dependency-scoped fail-fast exclusions have already been applied at the `IRBackend` boundary,
|
||||
5. frontend-declared qualified `EntrypointRef` is present:
|
||||
- `IRBackend.entryPointCallableName` is non-blank,
|
||||
- `IRBackend.entryPointModuleId` is non-none,
|
||||
5. compiler-selected published-wrapper entrypoint identity is present and unambiguous,
|
||||
6. and target `vm_profile` is selected deterministically.
|
||||
|
||||
## 6. IRVM Model Obligations
|
||||
@ -94,12 +92,18 @@ Control-flow lowering must satisfy:
|
||||
|
||||
Function indexing must be deterministic:
|
||||
|
||||
1. entrypoint callable is selected by exact qualified match against `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
|
||||
2. selected entrypoint function id is `0`,
|
||||
1. the compiler-selected published wrapper is the physical entrypoint,
|
||||
2. the published wrapper function id is `0`,
|
||||
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
||||
4. name-only entrypoint fallback is forbidden,
|
||||
4. manifest-owned or name-only entrypoint fallback is forbidden,
|
||||
5. and identical admitted input graphs must produce identical function-id assignments.
|
||||
|
||||
For PBS executable lowering:
|
||||
|
||||
- the userland callable marked with `[Frame]` remains the logical frame root,
|
||||
- the wrapper path must contain final `FRAME_RET`,
|
||||
- and lowering must preserve that distinction through `IRVM`.
|
||||
|
||||
## 9. Callsite Lowering Obligations
|
||||
|
||||
### 9.1 Function calls
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user