Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
4
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/discussion/workflow/plans/PLN-0147-move-native-shell-profile-update-into-hub.md
bQUARKz bd27f5eb63
implements PLN-0147
2026-07-04 18:55:24 +01:00

5.9 KiB
Raw Blame History

id ticket title status created ref_decisions tags
PLN-0147 foreground-stack-game-pause-shell-vm-backed Move Native Shell Profile Update Into Hub done 2026-07-04
DEC-0037
runtime
os
lifecycle
shell
game
vm
foreground
architecture

Briefing

DEC-0037 says a suspended Game must not receive normal gameplay ticks while Hub or Shell owns foreground. A recent fix made ShellRunningStep branch on ProcessKind: VM-backed Shell tasks use the VM-backed shell profile path, while native Shell tasks call PrometeuHub::gui_update and PrometeuHub::render without ticking the VM.

That behavior is correct, but the native Shell update sequence now lives in firmware rather than in the Hub profile API. This duplicates part of PrometeuHub::update_shell_profile and creates a drift risk if Shell close, render, or input rules change later.

Objective

Move native Shell profile updating into PrometeuHub so ShellRunningStep chooses the correct profile API without reimplementing Hub behavior.

Dependencies

  • Source decision: DEC-0037.
  • Depends on the ProcessKind::VmShell vs ProcessKind::NativeShell distinction available through LifecycleFacade::process_kind_for_task.
  • May be implemented before or after PLN-0146, but should use the consolidated lookup helper if PLN-0146 has already landed.

Scope

Included:

  • Add a Hub-owned native Shell update API that does not tick the VM.
  • Keep VM-backed Shell update behavior in the existing VM-backed profile path.
  • Keep Shell close handling consistent between native and VM-backed Shells.
  • Keep native Shell rendering in the Hub/Shell UI path.
  • Keep firmware responsible for choosing which profile applies to the current Shell task.
  • Preserve regression coverage that a suspended resident Game does not advance while native Shell is foreground.

Excluded:

  • No change to VM-backed Shell execution semantics.
  • No change to native Shell UI content.
  • No direct Shell close to Game.
  • No multiple foreground Shells.
  • No background Game ticking.

Non-Goals

  • Do not move foreground lifecycle authority into PrometeuHub.
  • Do not make native Shells VM tasks.
  • Do not introduce a general scheduler abstraction.

Execution Method

  1. Add a native Shell profile update method on PrometeuHub.

    • What changes: create update_native_shell_profile or an equivalent clearly named method that returns SystemProfileUpdate.
    • How it changes: the method calls gui_update, maps Start input to SystemProfileAction::CloseShell when a shell window is focused, calls render, and always returns crash: None.
    • File(s): crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs.

  2. Keep the VM-backed Shell profile method explicitly VM-backed.

    • What changes: either keep update_shell_profile and document/name its VM tick behavior, or rename/split it if the codebase convention supports that without churn.
    • How it changes: ensure the VM-backed path is the only Hub profile update method that calls os.vm().tick(...).
    • File(s): crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs.

  3. Simplify ShellRunningStep.

    • What changes: remove manual native Shell gui_update, Start handling, and render calls from firmware.
    • How it changes: branch on ProcessKind and call the appropriate Hub profile method; keep crash handling only for the VM-backed method.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs.

  4. Add Hub-level native profile tests.

    • What changes: prove native Shell profile update emits close on the close button and on Start, renders Shell UI, and does not tick the VM.
    • How it changes: use existing Hub/system test helpers where possible; assert VM tick index remains unchanged for native profile update.
    • File(s): crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs and/or crates/console/prometeu-firmware/src/firmware/firmware.rs.

  5. Preserve end-to-end regression coverage.

    • What changes: keep the Game -> Home -> native Shell test asserting that repeated Shell frames do not advance the resident Game VM tick index.
    • How it changes: rerun the firmware regression added for native Shell foreground.
    • File(s): crates/console/prometeu-firmware/src/firmware/firmware.rs.

Acceptance Criteria

  • Native Shell update behavior is owned by PrometeuHub, not hand-coded in ShellRunningStep.
  • The native Shell profile update never calls os.vm().tick(...).
  • VM-backed Shell update remains the only Shell profile path that ticks the VM runtime.
  • Start and close-button Shell close behavior remains unchanged for native Shells.
  • A suspended resident Game receives no normal gameplay ticks while native Shell is foreground.

Tests

  • Hub-level tests for native Shell profile close behavior.
  • Hub-level or firmware-level tests proving native Shell profile update does not tick the VM.
  • Existing firmware regression for Game -> Home -> native Shell repeated frames.
  • Run cargo test -p prometeu-system native_shell shell_profile.
  • Run cargo test -p prometeu-firmware game_home_shell_hub_same_game_flow.
  • Run cargo test -p prometeu-firmware.
  • Run cargo test -p prometeu-system.
  • Run discussion validate.

Affected Artifacts

  • crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs
  • crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs
  • crates/console/prometeu-firmware/src/firmware/firmware.rs

Risks

  • Renaming the existing VM-backed shell profile method may create unnecessary churn. Prefer adding the native method and keeping call sites explicit unless the rename is small and clearly improves readability.
  • Hub APIs must remain UI/profile orchestration only; lifecycle close and task state changes still belong to firmware/SystemOS lifecycle.