globals and synthetic inits

This commit is contained in:
2026-03-24 13:42:58 +00:00
parent f49dc64fe0
commit ecea7e96c0
10 changed files with 2205 additions and 69 deletions
@@ -0,0 +1,154 @@
# Globals Surface, Identity, and Module Boundaries Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.1. PBS Globals Surface, Identity, and Module Boundaries Agenda.md`
## Context
PBS v1 needed a precise language and linking policy for runtime globals before lifecycle, published entrypoint, and lowering work under topic `19` could proceed safely.
The open problem was not merely syntax.
It also required closing:
- how globals differ from `declare const`,
- how globals participate in value visibility and import flow,
- how module ownership of storage is preserved,
- how dependency order between globals is modeled,
- and which diagnostics are mandatory when that model is violated.
Important fixed inputs already existed:
- `declare const` is compile-time only and does not denote mutable module storage,
- top-level executable statements remain forbidden,
- the VM already exposes global-slot access,
- and `mod.barrel` remains the visibility authority for module exports.
## Decision
PBS adopts the following policy for runtime globals in v1:
1. PBS introduces a distinct top-level declaration form:
- `declare global Name: T = expr;`
2. `declare global` is not a variant of `declare const`.
3. `declare const` remains reserved to immutable values and must not be reused as runtime module storage.
4. `declare global` requires:
- an explicit type annotation,
- and an explicit initializer in all ordinary v1 cases.
5. Globals participate in the value namespace, but remain a distinct declaration category.
6. `mod.barrel` must expose globals through explicit `global` entries:
- `mod global Name;`
- `pub global Name;`
7. PBS does not introduce global re-export in this line of work.
8. Import of a global preserves the storage identity of the original owner module.
9. Imports may use aliasing when needed, but aliasing changes only the local visible name, never the canonical storage owner.
10. Shadowing between visible `fn`, `service`, `global`, and `const` names is a compile-time error and must be resolved with aliasing.
11. Lookup precedence remains:
- locals,
- then struct/class members,
- then globals,
including globals introduced by import.
12. Global dependency order is defined by a deterministic dependency graph:
- every read of another global in a global initializer creates a dependency edge,
- imports and aliases preserve canonical owner identity in that graph,
- source-file order must not affect dependency resolution.
13. Cycles between globals are compile-time errors.
14. Modules and globals must share the same structural dependency-analysis kernel through a refactor of the existing module dependency algorithm into:
- `DependencyGraphAnaliser`
- located in infra `util.structures`.
15. What is shared is the structural graph analysis kernel:
- topological ordering,
- cycle detection,
- deterministic traversal support.
16. What is not shared is domain semantics:
- each domain remains responsible for constructing canonical nodes, edges, and diagnostics.
## Global Initializer Policy
PBS v1 adopts the following initializer policy for `declare global`:
1. The initializer exists only to materialize the initial module storage value.
2. Admissible forms in v1 include:
- primitive literals and simple value operations,
- value-bearing member access at this stage,
- `new Struct(...)`,
- and reads of other globals compatible with the dependency graph.
3. Top-level `fn` calls are not permitted in a global initializer in v1.
4. `some(...)` and `none` are not permitted in a global initializer in v1.
5. `if` and `switch` are not permitted directly in the declaration initializer in v1.
6. Richer procedural setup belongs to later lifecycle stages rather than the declaration initializer itself.
## Rationale
This decision intentionally keeps global declarations narrow and explicit.
That choice:
- prevents semantic collapse between immutable constants and mutable runtime storage,
- keeps import and visibility rules legible,
- makes dependency analysis deterministic and explainable,
- avoids hiding lifecycle logic inside declaration expressions,
- and prepares a clean handoff to later topic `19` work on module init, project init, and published entrypoint behavior.
The decision also rejects implicit complexity:
- no silent reuse of `const`,
- no global re-export,
- no ambiguous cross-category name merging,
- and no procedural `fn`-driven initialization inside `declare global`.
## Mandatory Diagnostics
PBS must provide, at minimum, the following diagnostics for this policy:
1. `global initializer uses unsupported form`
- emitted at the invalid subexpression inside a global initializer.
2. `global dependency cycle detected`
- emitted on the local participating global,
- and should include the canonical cycle path when available.
3. `imported symbol shadows existing visible symbol; alias required`
- emitted when an imported `fn`, `service`, `global`, or `const` collides with an already-visible symbol of those categories.
4. `global import must resolve through a global barrel entry`
- emitted when import resolution would otherwise degrade a global into another category.
## Invariants
1. `declare const` and `declare global` remain semantically distinct.
2. Runtime storage ownership remains attached to the canonical owner module.
3. Global dependency order is semantic, not textual.
4. Alias spelling must not change canonical global identity.
5. The dependency-analysis kernel may be shared structurally, but semantic graph construction remains domain-owned.
## Explicit Non-Decisions
1. This decision does not define module init or project init behavior.
2. This decision does not define `[INIT]`, `[FRAME]`, or lifecycle markers.
3. This decision does not define published entrypoint or `FRAME_RET` ownership.
4. This decision does not define the final IR representation of globals.
5. This decision does not define host-call admissibility during lifecycle hooks.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/11. AST Specification.md`
4. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also constrains future topic `19` work in:
1. `docs/compiler/pbs/agendas/19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
2. `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
3. `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
## Validation Notes
At minimum, validation for this decision should include:
1. accepted fixtures for `declare global` with primitive, member-value, `new`, and dependent-global initializers;
2. rejection fixtures for forbidden initializer forms such as top-level `fn`, `some(...)`, `if`, and `switch`;
3. import fixtures proving alias-based disambiguation;
4. negative fixtures for cross-category collisions;
5. dependency fixtures proving deterministic ordering independent of source-file order;
6. cycle fixtures proving deterministic detection and diagnostics for intra-module and inter-module cycles.
@@ -0,0 +1,194 @@
# Lifecycle Markers, Program Init, and Frame Root Semantics Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.2. PBS Lifecycle Markers, Program Init, and Frame Root Semantics Agenda.md`
## Context
After closing the globals surface and module-boundary model, PBS v1 needed a precise lifecycle policy for:
- module bootstrap,
- project bootstrap,
- frame-root identification,
- host-call admissibility during init,
- and failure behavior at boot.
The key requirement was to keep initialization expressive enough for real setup work, while preserving deterministic semantics and preventing the declaration initializer of `global` from becoming a general procedural execution surface.
Important fixed inputs already existed:
- `declare global` lowers into module-owned runtime storage,
- global initializers remain declarative and restricted,
- top-level `fn` calls are not allowed inside `declare global` initializers,
- `FRAME_SYNC` remains the only normative safepoint,
- and PBS v1 remains deterministic and single-threaded.
## Decision
PBS adopts the following lifecycle-marker and bootstrap policy in v1:
1. PBS introduces the reserved userland attributes:
- `[Init]`
- `[Frame]`
2. `[Frame]` is mandatory for an executable project.
3. `[Frame]` is unique per executable project.
4. `[Init]` is optional.
5. `[Init]` may appear in ordinary userland source both for module-local bootstrap and for project bootstrap.
6. Both `[Init]` and `[Frame]` require the same signature shape:
- `fn name() -> void`
7. Recommended canonical source forms are:
```pbs
[Init]
fn init() -> void { ... }
```
```pbs
[Frame]
fn frame() -> void { ... }
```
## Module Init and Project Init Policy
PBS adopts the following bootstrap layering:
1. Every module has exactly one synthetic module init.
2. `declare global` always lowers into that synthetic module init.
3. Each file may declare at most one `[Init]`.
4. A file may declare `[Init]` even when it declares no globals.
5. For one file:
- that file's globals are materialized first,
- then that file's `[Init]`, if present, executes.
6. File-level init fragments are then composed into the one synthetic module init.
7. The `[Init]` colocated in the same file as `[Frame]` is the project init.
8. `[Init]` in other files remains module init.
9. The distinction between module init and project init is one of ordering and semantic role, not one of different source syntax.
10. There is therefore at most one project init per executable project.
11. Project init uses the same signature shape:
- `fn init() -> void`
## Bootstrap Order
PBS adopts the following logical bootstrap 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,
4. after required module work is complete, execute project init, if present,
5. then enter the first `frame()`.
Within one module:
1. file ordering must follow the order derived from the globals `DependencyGraphAnaliser`,
2. and when two files have no dependency edge between them, the compiler must still use a deterministic stable order.
## Host Interaction During Init
PBS adopts the following init-time host-call policy:
1. Loops are permitted in module init and project init.
2. Host calls are forbidden by default during init.
3. The only host calls admissible during init are host methods marked with `[InitAllowed]`.
4. `[InitAllowed]` is a reserved SDK attribute, not a userland attribute.
5. `[InitAllowed]` has no arguments in v1.
6. `[InitAllowed]` is valid only on SDK host methods.
7. `[InitAllowed]` is invalid on userland `fn`, `global`, `service`, or any non-host-method surface.
8. `[InitAllowed]` does not distinguish module init from project init.
9. The difference between those phases is ordering and semantic role, not a separate host-permission class.
10. Admissibility of `[InitAllowed]` must be checked at compile time.
Illustrative shape:
```pbs
declare host Runtime {
[Host(module = "runtime", name = "random_u32", version = 1)]
[Capability(name = "runtime")]
[InitAllowed]
fn random_u32() -> int;
}
```
## Failure Policy
PBS adopts a fail-fast boot policy:
1. Failure during module init aborts boot.
2. Failure during project init aborts boot.
3. No automatic retry occurs on the next frame.
4. Implementations must surface a coherent failure message identifying the failing boot phase.
## Rationale
This decision keeps the declaration initializer of `global` simple, while still allowing practical bootstrap work in later lifecycle stages.
That balance matters because:
- arrays and derived data often require loops during setup,
- module bootstrap must remain expressive enough for real projects,
- host interaction during boot must still be tightly controlled,
- and the runtime model must remain deterministic and explainable.
Colocation of project init with frame was chosen deliberately as a source-organization rule.
It avoids introducing a second project-level marker while keeping project bootstrap discoverable in source.
## Mandatory Diagnostics
PBS must provide, at minimum, the following diagnostics for this policy:
1. `project init must be colocated with frame`
2. `multiple project init functions detected`
3. `multiple frame functions detected`
4. `missing frame function for executable project`
5. `init function must have signature fn name() -> void`
6. `frame function must have signature fn name() -> void`
7. `host call not allowed during init`
8. `InitAllowed is valid only on SDK host methods`
9. `boot failed during module init`
10. `boot failed during project init`
11. `multiple module init functions detected`
12. `Init attribute target invalid`
## Invariants
1. `[Frame]` remains unique per executable project.
2. Project init is identified by colocation with `[Frame]`.
3. Each file contributes at most one init fragment.
4. Each module contributes exactly one synthetic module init.
5. Host-call admissibility during init is explicit and compile-time validated.
6. Boot ordering remains deterministic.
## Explicit Non-Decisions
1. This decision does not define the published synthetic wrapper entrypoint.
2. This decision does not define `FRAME_RET` ownership.
3. This decision does not define the final IR encoding of bootstrap.
4. This decision does not define cartridge manifest publication details.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/3. Core Syntax Specification.md`
2. `docs/compiler/pbs/specs/4. Static Semantics Specification.md`
3. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
4. `docs/compiler/pbs/specs/12. Diagnostics Specification.md`
It also constrains future topic `19` work in:
1. `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
2. `docs/compiler/pbs/agendas/19.4. Globals and Lifecycle Lowering to IRBackend/IRVM Agenda.md`
3. `docs/compiler/pbs/agendas/19.5. Diagnostics, Manifest Propagation, and Conformance Coverage Agenda.md`
## Validation Notes
At minimum, validation for this decision should include:
1. accepted fixtures for `[Init]` and `[Frame]` with correct signatures;
2. accepted fixtures for file-level `[Init]` without globals;
3. accepted fixtures for loops inside module init and project init;
4. rejection fixtures for invalid marker targets and invalid signatures;
5. rejection fixtures for illegal host calls during init;
6. accepted fixtures for SDK host calls marked `[InitAllowed]`;
7. failure fixtures that distinguish module-init boot failure from project-init boot failure;
8. ordering fixtures proving deterministic file ordering within one module.
@@ -0,0 +1,130 @@
# Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision
Status: Accepted
Date: 2026-03-22
Related Agenda: `docs/compiler/pbs/agendas/19.3. Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Agenda.md`
## Context
After closing globals and lifecycle semantics, PBS v1 still needed a precise publication contract for executable boot.
The remaining problem was no longer how initialization behaves in userland.
It was how that behavior is published into the artifact and consumed by backend stages and runtime.
The open points were:
- whether the published entrypoint is still the user `frame()` callable,
- whether a synthetic wrapper becomes the true physical entrypoint,
- where `FRAME_RET` must live once lifecycle bootstrap exists,
- whether `FrontendSpec` continues to hold authority over entrypoint identity,
- and whether `manifest.json` remains part of entrypoint authority.
Important fixed inputs already existed:
- `[Frame]` identifies the userland logical frame root,
- module init and project init are already defined in lifecycle terms,
- boot is one-shot and fail-fast,
- and general backend specs already converge on entrypoint function index `0`.
## Decision
PBS adopts the following publication and ownership policy for executable boot in v1:
1. The compiler publishes a synthetic wrapper as the physical executable entrypoint.
2. The userland callable marked with `[Frame]` remains the logical frame root of user code.
3. The synthetic wrapper is therefore the physical root, while `[Frame]` remains the logical root.
4. The wrapper must contain:
- one-shot boot orchestration,
- the required init execution exactly once,
- invocation of the userland `[Frame]` callable,
- and the final `FRAME_RET`.
5. `FRAME_RET` no longer belongs at the end of the userland `frame()` body.
6. `FRAME_RET` belongs to the published wrapper.
7. The published wrapper must occupy physical entrypoint index `0`.
## Entrypoint Authority
PBS adopts the following authority model:
1. `FrontendSpec` no longer holds authority to decide which callable is the published entrypoint for PBS.
2. Entrypoint authority is owned exclusively by the PBS compiler.
3. Source-derived lifecycle semantics determine the logical frame root.
4. The compiler then publishes the physical wrapper that realizes that lifecycle contract.
5. Backend handoff must therefore preserve the compiler-selected published wrapper as the effective entrypoint identity.
## Manifest and Runtime Protocol
PBS adopts the following target protocol direction:
1. `entrypoint` must stop being part of the final `manifest.json` contract.
2. Runtime boot must not depend on nominal entrypoint resolution from the manifest.
3. Runtime boot must treat physical entrypoint index `0` as protocol.
4. The compiler guarantees that the published wrapper occupies that index.
5. Any temporary compatibility line with manifest-declared nominal entrypoint is transitional only and is not the target contract.
## Exports Boundary
PBS adopts the following boundary for nominal exports:
1. Nominal function exports may continue to exist in the emitted artifact.
2. Those exports are no longer authoritative for loader or boot.
3. Boot depends exclusively on the published physical entrypoint at index `0`.
4. Nominal exports remain useful only for tooling, debug, introspection, and related non-boot concerns.
## Rationale
This decision keeps logical user semantics and physical boot publication clearly separated.
That matters because:
- the user `frame()` callable should remain the semantic root of frame logic,
- the one-shot bootstrap sequence must still execute before normal frame work,
- `FRAME_RET` should mark the true end of the logical published frame,
- and the compiler must be the single authority that turns source lifecycle into executable publication.
The decision also deliberately removes duplicated authority:
- not `FrontendSpec`,
- not manifest nominal metadata,
- and not PBX nominal exports
are allowed to compete with the compiler-selected physical wrapper as boot authority.
## Invariants
1. `[Frame]` remains the userland logical frame root.
2. The published wrapper remains the physical executable root.
3. `FRAME_RET` belongs to the published wrapper.
4. Physical entrypoint index `0` belongs to that wrapper.
5. Nominal exports are not boot authority.
6. Entrypoint authority for PBS belongs to the compiler, not to `FrontendSpec` or manifest metadata.
## Explicit Non-Decisions
1. This decision does not define the final IR encoding of the wrapper body.
2. This decision does not define the detailed lowering mechanics of globals and lifecycle into IR.
3. This decision does not define the runtime-side migration implementation plan in detail.
4. This decision does not define the final diagnostics catalog for backend/runtime structural failures.
## Spec Impact
This decision should feed at least:
1. `docs/compiler/pbs/specs/9. Dynamic Semantics Specification.md`
2. `docs/compiler/pbs/specs/13. Lowering IRBackend Specification.md`
3. `docs/compiler/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
4. `docs/compiler/general/specs/15. Bytecode and PBX Mapping Specification.md`
5. `docs/compiler/general/specs/20. IRBackend to IRVM Lowering Specification.md`
It also requires explicit cross-domain propagation to:
1. `../runtime/docs/runtime/agendas/025-cartridge-manifest-entrypoint-removal-and-runtime-protocol.md`
## Validation Notes
At minimum, validation for this decision should include:
1. emitted artifact evidence that the published wrapper occupies function index `0`;
2. conformance evidence that the userland `[Frame]` callable is invoked by that wrapper rather than being published directly;
3. evidence that `FRAME_RET` is emitted in the wrapper path;
4. evidence that nominal exports, when present, do not participate in boot authority;
5. integration evidence that runtime boot aligns with the fixed physical entrypoint protocol.