globals and synthetic inits
This commit is contained in:
+154
@@ -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.
|
||||
+194
@@ -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.
|
||||
+130
@@ -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.
|
||||
Reference in New Issue
Block a user