feat(pbs): add explicit guest lifecycle hooks

This commit is contained in:
2026-10-28 09:12:48 +00:00
parent eb7d6a2398
commit 9504f4694a
41 changed files with 1209 additions and 24 deletions
@@ -153,3 +153,18 @@ This document is ready to move beyond temporary status only when:
2. service and module runtime lifecycle assumptions are explicit enough to remove the remaining TODO items,
3. execution lifecycle boundaries are aligned with dynamic semantics and runtime authority,
4. and the document no longer relies on unresolved TODO items for ordinary v1 runtime startup behavior.
## Optional controlled runtime hooks
Producer-selected BeforePause/BeforeResume metadata MUST survive lifecycle
assembly without joining the init sequence or replacing the frame root/entry.
BeforePause runs after the existing gameplay handoff and before suspension;
BeforeResume runs after reactivation and before any normal gameplay instruction.
Missing hooks preserve transitions. Controlled calls preserve PC/stacks/roots,
globals and init guard; outer return restores continuation and yields to the OS
without another gameplay tick/frame or reinitialization. Direct calls remain
ordinary calls. Runtime owns the independent bounded fuel, transitive sync
prohibition, debugger behavior and failure envelope. There is no termination
hook, new syscall or automatic persistence. See the runtime's controlled
lifecycle contract and common typed Registry/PBX specification.
@@ -216,3 +216,15 @@ This specification MUST NOT be read as authorizing:
- or reopening lifecycle-assembly ownership.
Platform validators MUST NOT depend on types from the PBS frontend module (`prometeu-frontend-pbs`). The package `p.studio.compiler.pbs` is not the complete boundary; facades shipped by that module remain PBS-owned. Platform validators MUST NOT discover roles from `__pbs.` prefixes.
## Guest hook verification boundary
Frontend diagnostics validate source marker targets/signatures and image-wide
uniqueness. Common typed validation MUST independently reject duplicate roles,
pause/resume parameters/results/captures and final FunctionId-zero targets.
These producer defenses do not replace runtime loading/admission. Assembly and
optimization MUST preserve hook metadata and externally entered bodies/callees.
Regression tests MUST inspect production PBX from source and execute it through
the production runtime. Source errors, common emission errors, loader failures
and executed traps retain distinct diagnostics; preserve the runtime envelope.
@@ -289,3 +289,15 @@ This document is healthy when:
4. common backend obligations are not described as owned by PBS,
5. frontend-specific lowering specs only own emission into `IRBackend`,
6. and scope boundaries with optimization/emission specs are explicit.
## Preserving optional runtime hook metadata
Typed FunctionMetadata roles are frontend-neutral executable input. Lowering,
function ordering and optimization MUST retain externally entered role targets,
their dependencies and exact signature/capture/role metadata even without
ordinary CALL edges. Physical entry zero remains ordinary; deterministic linking
assigns other IDs to hooks. PBX emission consumes the existing role byte and
validates final targets, without role inference from function names or frontend
ASTs. Synthetic Init/Frame assembly is unchanged. FRAME_SYNC fixtures used to
test controlled-call rejection do not introduce frontend sync syntax.