feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
This commit is contained in:
+111
@@ -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.
|
||||
Reference in New Issue
Block a user