prometeu-studio/docs/general/specs/16. Runtime Execution and Initialization Specification.md

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.