69 lines
2.6 KiB
Markdown
69 lines
2.6 KiB
Markdown
# Globals, Lifecycle, and Published Entrypoint
|
|
|
|
## Original Problem
|
|
|
|
Topic 19 closed the biggest remaining executable-model gap in PBS:
|
|
|
|
- explicit globals,
|
|
- lifecycle markers,
|
|
- program initialization,
|
|
- published wrapper ownership,
|
|
- `FRAME_RET` placement,
|
|
- hidden boot state,
|
|
- and the compiler-to-backend handoff contract.
|
|
|
|
## Consolidated Decision
|
|
|
|
PBS now has one coherent lifecycle model.
|
|
|
|
The durable rules are:
|
|
|
|
1. Globals are explicit source-level declarations with stable identity and module ownership.
|
|
2. Lifecycle is source-driven through `[Init]`, `[Frame]`, and related static rules.
|
|
3. The user `[Frame]` function is the logical frame root.
|
|
4. The published physical entrypoint is a synthetic compiler-owned wrapper.
|
|
5. The wrapper owns final `FRAME_RET`.
|
|
6. Boot is one-shot and enforced through a hidden compiler-owned boot guard.
|
|
7. Hidden lifecycle artifacts must be structurally distinguishable from userland globals and userland callables.
|
|
8. Backend handoff must preserve wrapper identity, hidden global identity, origin metadata, and physical entrypoint index `0`.
|
|
|
|
## Final Model
|
|
|
|
The executable model is now:
|
|
|
|
1. per-file init fragments,
|
|
2. per-module synthetic init,
|
|
3. project init,
|
|
4. a published wrapper at physical entrypoint `0`,
|
|
5. a hidden `BOOT_GUARD`,
|
|
6. and user `frame()` as the logical callable invoked by the wrapper.
|
|
|
|
This is the key conceptual split:
|
|
|
|
- userland owns the logical frame root,
|
|
- the compiler owns the physical boot protocol.
|
|
|
|
That separation keeps the language surface clean while still giving the backend and runtime a deterministic boot contract.
|
|
|
|
## Practical Consequences
|
|
|
|
1. Executable PBS projects must declare an explicit `[Frame]`.
|
|
2. Entrypoint authority no longer belongs to manifest metadata or nominal export lookup.
|
|
3. Hidden compiler lifecycle state must not be modeled as ordinary user globals.
|
|
4. Lowering and tests should prove wrapper publication, wrapper ordering, guard presence, and guard semantics.
|
|
|
|
## Common Pitfalls
|
|
|
|
- Treating `frame()` itself as the physical entrypoint.
|
|
- Reintroducing manifest-driven entrypoint authority.
|
|
- Recognizing hidden lifecycle artifacts only by naming convention.
|
|
- Forgetting that boot must be one-shot across frames, not merely “present in the graph”.
|
|
|
|
## Source Decisions
|
|
|
|
- `Globals Surface, Identity, and Module Boundaries Decision.md`
|
|
- `Lifecycle Markers, Program Init, and Frame Root Semantics Decision.md`
|
|
- `Published Entrypoint, Synthetic Wrapper, and FRAME_RET Ownership Decision.md`
|
|
- `Globals and Lifecycle Lowering to IRBackend and IRVM Decision.md`
|
|
- `Diagnostics, Manifest Propagation, and Conformance Coverage Decision.md`
|