implements PR-19.1 normative spec propagation

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:
 

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/specs/compiler/15. Bytecode and PBX Mapping Specification.md`
-- `docs/general/specs/16. Runtime Execution and Initialization Specification.md`
+- `docs/specs/compiler/16. Runtime Execution and Initialization Specification.md`
-- `docs/general/specs/19. Verification and Safety Checks 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.
 

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`,
+1. `docs/specs/compiler/20. IRBackend to IRVM Lowering Specification.md`,
-2. `docs/general/specs/21. IRVM Optimization Pipeline Specification.md`,
+2. `docs/specs/compiler/21. IRVM Optimization Pipeline Specification.md`,
-3. or `docs/general/specs/15. Bytecode and PBX Mapping 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`):
+For executable PBS frontends, backend handoff must preserve the compiler-selected published wrapper rather than a frontend-declared nominal entrypoint.
-
-1. `entryPointCallableName`,
-2. `entryPointModuleId`.
 
 At `IRBackend` emission time:
 
-1. frontend must copy this declaration into `IRBackend.entryPointCallableName` and `IRBackend.entryPointModuleId`,
+1. the lowered graph must contain explicit lifecycle structure for:
-2. both values must be non-blank/non-none and deterministic for the same language/spec version,
+   - user-authored globals,
-3. and backend stages must treat this qualified reference as authoritative for entrypoint selection instead of name-only fallbacks or hardcoded language-agnostic names.
+   - 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.

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

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
 

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.

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<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

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`
+3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
-4. `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution 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/specs/compiler-languages/pbs/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.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`,
+1. the published wrapper function index is `0`,
-2. entrypoint index `0` is selected from qualified `EntrypointRef(entryPointModuleId, entryPointCallableName)`,
+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:

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/specs/compiler-languages/pbs/13. Lowering IRBackend Specification.md`
-- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
+- `docs/specs/compiler-languages/pbs/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.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:
+5. compiler-selected published-wrapper entrypoint identity is present and unambiguous,
-   - `IRBackend.entryPointCallableName` is non-blank,
-   - `IRBackend.entryPointModuleId` is non-none,
 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)`,
+1. the compiler-selected published wrapper is the physical entrypoint,
-2. selected entrypoint function id is `0`,
+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