diff --git a/docs/specs/compiler-languages/pbs/11. AST Specification.md b/docs/specs/compiler-languages/pbs/11. AST Specification.md index ae34f0ff..cf32b8ff 100644 --- a/docs/specs/compiler-languages/pbs/11. AST Specification.md +++ b/docs/specs/compiler-languages/pbs/11. AST Specification.md @@ -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: diff --git a/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md b/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md index 07b0c9bd..7433e1cc 100644 --- a/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md +++ b/docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md @@ -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. diff --git a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md index 7c69c0dc..4741307b 100644 --- a/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md +++ b/docs/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md @@ -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. diff --git a/docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md b/docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md index 2f568893..fbc6552e 100644 --- a/docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md +++ b/docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md @@ -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 diff --git a/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md b/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md index 8253593b..a24639f6 100644 --- a/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md +++ b/docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md @@ -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 diff --git a/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md b/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md index 28ae2274..7c7e8ce5 100644 --- a/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md +++ b/docs/specs/compiler-languages/pbs/7. Cartridge Manifest and Runtime Capabilities Specification.md @@ -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. diff --git a/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md b/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md index fdacf682..9ad8e57b 100644 --- a/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md +++ b/docs/specs/compiler-languages/pbs/9. Dynamic Semantics Specification.md @@ -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` 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 diff --git a/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md b/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md index ea17a5b1..3311e24a 100644 --- a/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md +++ b/docs/specs/compiler/15. Bytecode and PBX Mapping Specification.md @@ -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: diff --git a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md index 157a7c6d..74288b4c 100644 --- a/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md +++ b/docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md @@ -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