feat(pbs): add explicit guest lifecycle hooks

This commit is contained in:
2026-10-28 09:12:48 +00:00
parent eb7d6a2398
commit 9504f4694a
41 changed files with 1209 additions and 24 deletions
@@ -382,3 +382,30 @@ The [PBS input and value alignment contract](../../../compiler/pbs/specs/input-a
## Typed arrays and optional execution extension
The [typed arrays and optional execution specification](../../../compiler/pbs/specs/typed-arrays-and-optional-execution.md) defines array types/construction/indexing, contextual literals, optional bindings and runtime storage. Its rules extend this specification, including source typing, complete groups, Struct/contract execution and diagnostics.
## Controlled pause and resume hooks
Source-selected BeforePause/BeforeResume functions lower to existing runtime
roles 1/2. Runtime owns invocation ordering, continuation, fuel and failures.
Home's existing handoff precedes BeforePause; suspension completes after normal
hook return. Reactivation precedes BeforeResume; no normal gameplay instruction
is eligible until that hook returns. Direct suspension and Shell handoff follow
the runtime contract without an additional gameplay reaction tick. Missing
hooks preserve existing transitions.
Controlled calls retain the same VM stacks, suspended values, environments,
globals and heap roots, restoring the continuation on outer return and handing
control immediately to the OS. Mutations persist. They MUST NOT reprepare entry,
repeat Init, reset the boot guard, or add gameplay ticks/logical frames. Ordinary
calls to marked functions do not themselves acquire controlled-call semantics.
Each controlled invocation has 1,500,000 virtual cycles total, sliced at at most
250,000 admitted cycles per host update, with the runtime's whole-instruction
overshoot rule. Slices/debugger stops do not renew fuel. There is no wall-clock
deadline. FRAME_SYNC, including in a callee, traps before frame/GC/publication
effects. Fatal traps/host failures and unfinished fuel exhaustion fail the
session, block gameplay and retain the existing crash envelope, without retry,
rollback or compensation. HALT is OS termination, not successful hook return.
Existing capability/service rules apply, without auto-save, flush, disk wait,
transition veto or reason argument. MemcardBoot and persistence are separate.