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
@@ -81,11 +81,34 @@ Encoding primitives: list=`count:u32` followed by records; optional name=`presen
| Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here |
| Fn payload | ordered parameter list, result list; names do not define identity |
| Captures section | function_count:u32, then each FunctionId in order: capture_count:u32 and TypeIds:u32; counts match functions, empty lists explicit |
| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Function | lifecycle_role:u8, optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match |
Code offsets are relative to Code. Local and temporary counts widen from current u16 without truncation. `max_stack_slots` counts temporaries only; zero means zero, never infer. No guest-controlled builtin layouts or raw Rust structures/pointers are serialized. Remove old/external compatibility; regeneration is mandatory.
## Optional lifecycle roles
The executable Function record carries one role byte before its optional name:
`0=None`, `1=BeforePause`, `2=BeforeResume`. Zero means an ordinary function,
not a callable hook. Unknown values reject with InvalidRegistry/LifecycleRole.
Each nonzero role has at most one target; duplicates reject with
InvalidRegistry/DuplicateLifecycleRole. Targets MUST NOT be FunctionId 0 and
MUST have zero parameters, results and captures; violations reject with
InvalidEntrypoint/LifecycleSignature. Preserve function/section context and the
wire offset when decoding an invalid role. Resolve optional FunctionIds once
in the immutable Registry. Names, exports, manifests and trait Method records
are not the binding mechanism.
Either hook may be absent. Additional roles require a future contract; there is
no termination role. PBX remains version 1, with no old-layout fallback or
external-artifact compatibility. Producers MUST regenerate their images and
emit this byte for every function, including zero for ordinary functions.
Frontend compilers choose their own source syntax and lower it to these roles.
Their existing Init/Frame boot assembly remains frontend-owned; runtime keeps
FunctionId 0 as its ordinary entry and does not introduce Init/Frame roles.
Execution ordering and limits are defined in [lifecycle](09a-coroutines-and-cooperative-scheduling.md).
## Values, storage and initialization
Value remains the generic stack/local representation. Structs/arrays are references; primitive and builtin-value array elements are stored directly. Layout descriptors distinguish value-slot width from heap-instance layout and distinguish GC references from native ownership. Derive offsets/defaults/maps once; access by indices/offsets rather than repeatedly traversing semantic metadata. Measure bitmap versus offset/block lists; changing the map encoding must not change the contract.