feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...

This commit is contained in:
2026-10-13 12:18:18 +01:00
parent 23dc6fc66d
commit 0af8b2b1fe
39 changed files with 1381 additions and 70 deletions
@@ -97,7 +97,8 @@ Sync Phase
Important properties:
- events are processed at known points;
- no execution occurs outside the frame loop;
- normal gameplay executes inside the frame loop; optional SystemOS lifecycle
hooks execute outside it with an independent budget;
- frame structure remains observable for host tooling and host-owned certification.
## 7 Foreground Lifecycle Events
@@ -111,7 +112,9 @@ The Game pause path is:
Home/SystemOS request
-> pause event becomes visible to the Game
-> bounded pause reaction budget
-> SystemOS suspension, even if the Game did not cooperate
-> leave gameplay execution
-> optional BeforePause hook
-> SystemOS suspension on normal completion, or session failure
```
The Game resume path is:
@@ -120,7 +123,8 @@ The Game resume path is:
SystemOS resume request
-> VM reactivation
-> resume or foreground-restore event becomes visible to the Game
-> Game may synchronize while still internally paused
-> optional BeforeResume hook
-> normal gameplay becomes eligible after successful return
-> visual foreground returns after a valid current-epoch render submission
```
@@ -128,10 +132,11 @@ SystemOS resume request
scheduler/runtime state. A Game may observe pause/resume, but it must not
control whether SystemOS suspends or resumes the VM.
When SystemOS replaces one Game with another from Home, the old Game MAY receive
a cooperative terminate/save lifecycle event if the runtime supports such an
event. That event is non-blocking in v1. SystemOS remains authoritative and may
close the old Game task/session without guest acknowledgement.
Registry hooks are optional and independent. Their binding, single-context call
boundary, fuel and debugger semantics follow [the lifecycle contract](09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls).
Existing pending native lifecycle delivery bookkeeping remains separate; it is
not a new guest event API. There is no termination hook. SystemOS may close an
old Game task/session without guest acknowledgement when replacing it.
Pause budgets are measured in deterministic machine units, not host wall-clock
time. A suspended Game receives no normal gameplay ticks, no normal Game input,