5.2 KiB
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, events and memory.
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.