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
@@ -0,0 +1,111 @@
---
id: LSN-0066
ticket: guest-lifecycle-pause-and-resume-api
title: Lifecycle Calls Retain the Game Continuation
created: 2026-10-13
tags: [lifecycle, vm, registry, debugger]
---
## Context
Optional BeforePause and BeforeResume functions now run around the existing OS
suspension and reactivation transitions. The implementation derives from accepted
DEC-0054 and PLN-0185, originating in AGD-0065 / DSC-0062. These workflow records
are disposable; the durable contracts are
[Registry roles](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles)
and [controlled lifecycle calls](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls).
## Binding Describes a Runtime Event, Not a Frontend Construct
A Registry function has one explicit role byte. Zero means no lifecycle role;
nonzero bindings are unique and optional. The function index is chosen by the
producer. A source name, manifest entry or arbitrary fixed FunctionId would mix
language policy with runtime scheduling. Signature validation at image loading
makes the OS call boundary independent of source syntax.
Init and Frame remain frontend assembly choices behind ordinary entry zero.
The external compiler must emit the new role byte for every Function record,
validate source declarations, and regenerate its PBX v1 artifacts. That compiler
integration was not performed in this runtime delivery. Internal producers and
tracked dummy-boy/stress-console images use the revised layout. Independent
binary oracles were updated field by field, including directory offsets and
malformed-input locations; merely regenerating fixtures would lose that check.
## Retaining the Continuation Avoids a Second Execution Context
The VM appends a hook frame to its own operand and call stacks. The previous PC,
halted flag and boundaries define where to restore execution. Existing values
and closure environments stay in the normal root traversal, so a suspended
caller cannot disappear during collection. Globals and heap mutations made by
the hook persist. Retained frames still count toward call-depth and memory limits.
Boot-entry preparation clears stacks and is therefore the wrong operation for
this boundary. A second VM would separate globals, capabilities, handles and
heap identity. Appending a controlled frame keeps those identities intact. The
critical completion rule is to stop at the outer return immediately: unused
slice fuel must not execute the saved gameplay continuation. A branch to function
end follows the same boundary, including nested ordinary calls.
## A Debugger Is Another Execution Driver
Normal slices and instruction stepping share the VM's total-fuel accounting.
Breakpoints retain that balance, including a breakpoint on the first hook
instruction. Waiting in the debugger costs no cycles. The OS step path uses the
session's actual filesystem state, open handles and memcard service. A dummy
service context would make stepping change the program's meaning.
One total budget survives all slices. Whole instructions retain their ordinary
overshoot semantics; a completed return wins at the boundary, while unfinished
work fails at exhaustion. FRAME_SYNC is forbidden transitively because a hook
must not close or publish a gameplay frame. Normal service errors remain data;
fatal faults and host panics fail the session with the phase in diagnostics.
HALT closes the task rather than completing a hook or returning to gameplay.
## Deferring Completion Preserves Existing OS Policy
The Home path still grants its existing handoff tick. After it leaves gameplay,
the pending transition drives only the callback until suspension completes.
Direct suspension and Shell activation use the same callback boundary without
inventing an extra gameplay tick. Reactivation precedes BeforeResume, and normal
frames remain gated until return. Requests are serialized; repeated requests
cannot replenish fuel or start another invocation.
The firmware also recognizes completion caused by debugger stepping, so its
next update cannot treat a properly suspended task as a crash. Transitions with
no applicable hook retain their immediate behavior.
## Bytecode Fuel Does Not Bound a Blocked Native Call
The executor adds no disk wait or automatic flush and does not cancel owned IO
on hook failure. Existing asset/async-work protocols retain their ownership.
The native audit found that FS read/write and the current memcard commit still
call synchronous backend interfaces. A deterministic cycle cap cannot preempt
one of those host calls. Prompt native return is a host/service obligation;
there is no wall-time guarantee in this delivery.
The new memcard backend must supply bounded asynchronous submission/polling and
own in-flight data until completion or safe release. Its consumer acceptance
belongs to the memcard workflow: explicit commit from a hook, return without
waiting for disk, late completion after lifecycle failure, and availability
checks on resume without automatic reload/save/reinitialization. The runtime
hook mechanism is independently complete and does not implement that backend.
## Evidence
Loaded-bytecode tests exercise optional roles, strict metadata rejection,
retained PC/stacks/roots, nested calls, branch returns, quota refusal, an empty
continuation, exact/overshooting return budgets, multiple slices, breakpoints,
and sticky fatal failures. Firmware tests cover Home, direct suspend, Shell,
resume, independently absent hooks, debugger steps using real handles, phase
failures and HALT. Validation completed with 960 passed / 9 existing ignored across 53 workspace
suites (`cargo test --workspace --all-targets --all-features --no-fail-fast`).
After the final tick/step and boot-entry guards, all 528 affected VM/system/firmware
library tests passed (2 existing ignored). The final pause-request guard was
also revalidated by the 245 system/firmware library tests. Formatting, Clippy,
diff whitespace, published-doc workflow-reference checks and discussion validation
passed. Published lesson links resolve. Internal producer regeneration completed.
The tests also verify ordinary unmounted-FS error data inside a hook, real
session-handle mutation under debugger stepping, and that a suspended session
cannot execute gameplay through direct tick/step requests. Preparing a new boot
entry while a hook is active is refused rather than clearing the retained stacks.