156 lines
6.8 KiB
Markdown
156 lines
6.8 KiB
Markdown
# PBS Runtime Execution and Initialization Specification
|
|
|
|
Status: Draft v1 (Temporary)
|
|
Applies to: runtime startup, entry behavior, module/service initialization, and execution lifecycle of PBS programs after successful load
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the PBS-visible runtime entry and execution-lifecycle contract after successful artifact load.
|
|
|
|
Its purpose is to keep runtime startup, frame-driven execution, and fatal-failure behavior aligned with:
|
|
|
|
- runtime authority,
|
|
- dynamic semantics,
|
|
- memory/lifetime guarantees,
|
|
- and the closed capability-gated host model.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- when PBS program execution may begin,
|
|
- which preconditions must already hold before userland runs,
|
|
- the runtime execution model of a loaded PBS program instance,
|
|
- the only normative frame/safepoint boundary in v1,
|
|
- and which startup or fatal-failure outcomes are PBS-visible.
|
|
|
|
This document does not define:
|
|
|
|
- loader-side host resolution details,
|
|
- the full packaging or process model,
|
|
- scheduler models outside the v1 single-threaded execution contract,
|
|
- shutdown/finalization APIs or hooks,
|
|
- or subsystem-specific host resource lifecycles.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
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. `1. Language Charter.md`
|
|
3. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
4. `9. Dynamic Semantics Specification.md`
|
|
5. `10. Memory and Lifetime Specification.md`
|
|
6. This document
|
|
|
|
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `1. Language Charter.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
- `9. Dynamic Semantics Specification.md`
|
|
- `10. Memory and Lifetime Specification.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- `FRAME_SYNC`-based execution semantics are preserved.
|
|
- Loader-side host binding resolution and capability gating happen before program execution begins.
|
|
- A PBS program instance executes single-threaded in v1.
|
|
- Dynamic semantics are deterministic at the language-observable level.
|
|
- Any runtime trap aborts PBS program execution and enters the runtime/firmware crash path rather than a userland recovery path.
|
|
- Service values are canonical module-owned singleton values.
|
|
- Top-level executable statements are forbidden in PBS source modules.
|
|
|
|
## 6. Runtime Entry Preconditions
|
|
|
|
PBS userland execution may begin only after all of the following are true:
|
|
|
|
1. the program artifact has been accepted by the relevant runtime/load authority,
|
|
2. capability gating and host-binding resolution required for startup have completed successfully,
|
|
3. runtime state required to begin frame-driven execution has been established,
|
|
4. and no prior fatal startup failure has occurred.
|
|
|
|
If these preconditions are not satisfied, ordinary PBS userland execution does not begin.
|
|
|
|
This document does not define loader-internal sequencing in detail; it only defines that the userland-visible start boundary occurs after successful load- and capability-level admission.
|
|
|
|
## 7. Program Instance Model
|
|
|
|
Each loaded PBS program executes as one single-threaded program instance in v1.
|
|
|
|
Within a program instance:
|
|
|
|
- userland execution is not concurrently interleaved by another userland thread,
|
|
- the dynamic-semantics evaluation order defined in `9. Dynamic Semantics Specification.md` remains authoritative,
|
|
- and runtime/host activity must not perturb that language-level sequencing.
|
|
|
|
PBS source modules do not contribute a user-authored top-level execution phase. Any startup activity that exists outside ordinary function/method execution is runtime-owned unless and until another specification makes a narrower PBS-visible contract explicit.
|
|
|
|
## 8. Frame Boundary and Host Work
|
|
|
|
`FRAME_SYNC` is the only normative runtime step boundary and the only normative safepoint in PBS v1.
|
|
|
|
Consequences:
|
|
|
|
- the runtime may use the interval around `FRAME_SYNC` to process host-side demands and internal work,
|
|
- userland execution must remain semantically ordered as defined by `9. Dynamic Semantics Specification.md`,
|
|
- and PBS user code cannot rely on any other boundary as a guaranteed safepoint, collection point, or scheduling point.
|
|
|
|
Internal runtime work may exist outside `FRAME_SYNC`, but it must remain semantically invisible to PBS userland unless a higher-precedence authority explicitly defines otherwise.
|
|
|
|
## 9. Failure and Non-Start Conditions
|
|
|
|
PBS distinguishes between two broad classes of failure at this layer:
|
|
|
|
1. non-start conditions, where userland never begins because artifact admission, capability checks, or required startup preconditions fail;
|
|
2. fatal runtime traps, where an already-running PBS program aborts.
|
|
|
|
Traps are not recoverable in PBS userland. When a trap occurs:
|
|
|
|
- it does not enter `result` flow,
|
|
- it is not intercepted by `handle`,
|
|
- and it aborts the PBS program execution path into the runtime/firmware crash path.
|
|
|
|
This document does not define a userland-visible trap catalog.
|
|
|
|
## 10. Service and Module Initialization Boundaries
|
|
|
|
The current v1 baseline is intentionally narrow:
|
|
|
|
- service values are canonical singleton values,
|
|
- top-level executable statements do not exist,
|
|
- and no userland-visible module-initialization statement phase is defined here.
|
|
|
|
The exact timing at which service-owned runtime state becomes initialized and observable remains an open item for this document. Until that is closed, implementations must not infer extra userland-visible initialization hooks beyond what is already guaranteed by higher-precedence specs.
|
|
|
|
## 11. TODO
|
|
|
|
The following items remain open for later closure:
|
|
|
|
- the exact runtime entry contract between successful load and first userland-observable execution,
|
|
- whether service-owned runtime state has a more precise initialization point than the baseline stated here,
|
|
- which runtime lifecycle boundaries, if any, are userland-observable beyond `FRAME_SYNC` and trap abort,
|
|
- and whether shutdown behavior has any PBS-visible contract in v1.
|
|
|
|
## 12. Non-Goals
|
|
|
|
- Defining OS/process lifecycle outside Prometeu runtime authority.
|
|
- Reopening the ban on top-level executable statements.
|
|
- Designing a future async runtime.
|
|
- Defining userland recovery from trap.
|
|
|
|
## 13. Exit Criteria
|
|
|
|
This document is ready to move beyond temporary status only when:
|
|
|
|
1. runtime startup and non-start boundaries are normatively described,
|
|
2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items,
|
|
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
|
|
4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior.
|