88 lines
5.2 KiB
Markdown
88 lines
5.2 KiB
Markdown
# Single Execution Context and Frame Continuation
|
||
|
||
Domain: VM execution lifecycle
|
||
Function: normative
|
||
|
||
VM directly owns one PC, operand stack, call stack and globals. Entry preparation
|
||
does not allocate a heap execution object. There are no guest coroutine instances,
|
||
ready/sleeping queues, sleeper clock or coroutine scheduling phase.
|
||
|
||
SPAWN/YIELD/SLEEP are retired; 0x54–0x56 remain reserved. Loading MUST reject them
|
||
before execution, including unreachable code. Assembler rejects their mnemonics;
|
||
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 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.
|
||
|
||
Successful RET of the last root completes entry and leaves rooted results on VM
|
||
stack. Recurring host may prepare FunctionId 0 next logical frame, preserving
|
||
globals/init guard. Callee RET does not close a frame. Replacement preparation
|
||
validates/reserves before releasing owners. HALT/trap/reset/unload retain their
|
||
contracts.
|
||
|
||
Threshold GC opportunities are sync and successful root RET after result rooting.
|
||
Preparation, ordinary callee RET and allocation failure add no opportunity. GC
|
||
advances no clock/frame, grants no budget and invokes no guest cleanup/callback.
|
||
Asset/render workers retain their independent protocols and run no guest code;
|
||
no physical-core affinity is implied.
|
||
|
||
Persistent operations can advance through short steps in normal frame execution
|
||
and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols require
|
||
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 interfaces remain synchronous. Memcard commits use
|
||
bounded admission and query calls on the shared asset/IO lane. BeforePause can
|
||
submit a commit and return immediately; BeforeResume can query the retained
|
||
result. The independent 500ms cancellation and 1s host escalation deadlines are
|
||
defined by [save memory](08-save-memory-and-memcard.md).
|