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
@@ -13,7 +13,8 @@ diagnostic decoding can identify retired numbers. No compatibility mode exists.
Other instruction numbers are unchanged.
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
is not a terminator, can occur in any body and resumes next PC. Host MUST NOT
is not a terminator and resumes next PC. It is forbidden while a lifecycle hook
is active, including in its callees. Host MUST NOT
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
preserve the same open frame without draw publication or extra callback budget.
@@ -34,3 +35,53 @@ and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols requir
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
[events](09-events-and-concurrency.md) and
[memory](03-memory-stack-heap-and-allocation.md).
## Controlled lifecycle calls
SystemOS optionally invokes the Registry's BeforePause and BeforeResume roles.
BeforePause runs after leaving the existing gameplay loop/handoff and before OS
suspension completes. BeforeResume runs after reactivation and before any normal
gameplay instruction. Neither hook is required, takes arguments, returns a
value, or vetoes the transition. Absence preserves the existing transition.
Direct suspension and Shell foreground handoff obey the same ordering; they do
not add a gameplay reaction tick. Home retains its existing one-tick handoff.
A controlled call appends a frame and locals to the same VM stacks. It retains
the previous PC, halted state and stack boundaries; all suspended stack values,
frame environments, globals and heap references remain roots. Existing stack,
call-depth and allocation quotas include retained frames. Reserve before entry
mutation. Ordinary calls inside the hook work normally. On successful outer
return (including a branch to function end), restore the continuation and return
immediately to SystemOS, even if the execution slice has unused cycles. Never
clear the stacks with boot-entry preparation or execute gameplay in that slice.
Global/heap mutations persist. There is at most one lifecycle invocation per
session; duplicate requests do not reenter or renew it, and conflicting pending
transitions reject.
Each invocation receives 1,500,000 virtual cycles total, sliced at no more than
250,000 admitted cycles per host update. This budget is independent of normal
logical frames and never renews between slices or debugger stops. Positive
remaining budget admits a whole instruction and allows its existing overshoot.
A normal completed return succeeds even if that final instruction consumes the
remaining budget; an unfinished invocation at exhaustion fails. There is no
wall-clock deadline. Breakpoints preserve the invocation and remaining budget;
while stopped, no cycles or gameplay frames advance. Instruction stepping uses
the same budget and the session's real service context.
FRAME_SYNC traps before frame/GC/publication effects, including from ordinary
callees. Fatal traps, host errors/panics and total exhaustion fail the session,
block gameplay and report the failing phase through the existing crash path.
There is no retry, rollback of earlier mutations or compensating other hook.
Normal service-result errors remain guest data. HALT closes the task through
the OS termination path; it is not successful hook return.
Hooks use the existing services and capability checks. No automatic save,
flush, disk-completion wait, guest event queue or reason argument is added.
Host-owned in-flight work keeps its ownership until the service/host safely
releases it; lifecycle failure does not simulate cancellation or free borrowed
buffers. Native calls must return promptly: VM fuel only bounds bytecode and
cannot preempt a blocked native/host call. Existing FS read/write and the current
memcard commit backend are synchronous interfaces, so this implementation does
not promise a wall-time bound for them. The new asynchronous memcard backend
must expose bounded submission/polling independently; hooks can then submit an
explicit commit without waiting for disk completion.