Task-Owned Shell Windows

This commit is contained in:
2026-05-15 11:43:04 +01:00
parent a8e3040d1e
commit 2154dba080
6 changed files with 1021 additions and 1 deletions
@@ -0,0 +1,116 @@
---
id: PLN-0059
ticket: task-owned-shell-windows
title: Plan - Task Window Contract Specs
status: open
created: 2026-05-15
completed:
ref_decisions: [DEC-0027]
tags: [runtime, os, task, window-manager, shell, lifecycle, specs]
---
# Plan - Task Window Contract Specs
## Briefing
Document the task-owned shell window contract from `DEC-0027` in the canonical
runtime specs before code execution changes the observable model.
## Decisions de Origem
- `DEC-0027` - Task-Owned Shell Windows
## Alvo
The canonical specs must state that:
- `Process` is technical execution.
- `Task` is navigable presence.
- `Window` is visual presence for shell/system tasks managed by the
`WindowManager`.
- Game cartridges are not `WindowManager` windows and continue as fullscreen
`GameRunningStep` sessions.
- Shell app windows use `WindowOwner::Task(TaskId)`.
- `Hub` and `Overlay` are not shell task windows.
- v1 `ShellRunningStep` continues only while the focused window belongs to its
own task.
## Escopo
Included:
- Update [docs/specs/runtime/12-firmware-pos-and-prometeuhub.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md) with the contract.
- Add or adjust terminology in the same file if the existing terms section is
the best local home.
- Link the contract to firmware states, AppMode behavior, and Hub/system window
responsibilities.
## Fora de Escopo
- Code changes in `crates/`.
- Overlay/modal policy.
- Background services, minimization, app switcher, or dock behavior.
- Multiple-window semantics beyond preserving future compatibility.
- Rewriting unrelated firmware spec sections.
## Plano de Execucao
1. Locate the normative spec home.
Use `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` as the primary
target because it already owns POS, Hub, AppMode, and firmware states.
2. Extend the terms section.
Add concise definitions for `Process`, `Task`, `Window`, `WindowOwner`, and
shell task windows if they are not already present.
3. Add a Task-Owned Shell Windows section.
State the v1 predicate explicitly:
```text
TaskState::Foreground
+
focused window owner == WindowOwner::Task(task_id)
```
State that the runtime API is
`os.windows().focused_window_belongs_to_task(task_id)`.
4. Clarify AppMode separation.
Under `Game`, state that games are fullscreen firmware sessions and must not
be modeled as `WindowManager` windows. Under `System`, state that shell apps
are represented through task-owned windows.
5. Clarify lifecycle consequence.
State that when a shell task loses its eligible focused window,
`ShellRunningStep` must close the task through `SystemOS` lifecycle and then
return to Hub.
6. Keep excluded topics explicit.
Add a short note that overlay policy, minimization, app switcher, dock, and
background services are future contracts, not part of v1.
## Criterios de Aceite
- [ ] The spec describes the `Process` / `Task` / `Window` model in English.
- [ ] The spec states that games are not `WindowManager` windows.
- [ ] The spec states that shell app windows use `WindowOwner::Task(TaskId)`.
- [ ] The spec states the v1 `ShellRunningStep` focused-window predicate.
- [ ] The spec states that loss of the eligible focused window closes the task
through lifecycle before returning to Hub.
- [ ] The spec does not introduce overlay, background, minimization, app
switcher, dock, or multiple-window policy.
## Tests / Validacao
- Run `discussion validate`.
- Review the changed spec for English-only normative text.
- Confirm every normative point from `DEC-0027` has a corresponding spec line.
## Riscos
- The spec may become too implementation-specific if it describes current Rust
call sites instead of the contract.
- The spec may accidentally imply overlay/modal behavior. Keep overlay
behavior explicitly out of scope.
- Future work may need a dedicated OS/window spec chapter; this plan keeps the
change local to the existing firmware/Hub spec.
@@ -0,0 +1,105 @@
---
id: PLN-0060
ticket: task-owned-shell-windows
title: Plan - Focused Window Ownership API
status: open
created: 2026-05-15
completed:
ref_decisions: [DEC-0027]
tags: [runtime, os, task, window-manager, shell, lifecycle, code]
---
# Plan - Focused Window Ownership API
## Briefing
Add the OS/window query required by `DEC-0027`:
`os.windows().focused_window_belongs_to_task(task_id)`.
This plan owns the system-side API and tests. It does not change firmware
control flow; that is covered by `PLN-0061`.
## Decisions de Origem
- `DEC-0027` - Task-Owned Shell Windows
## Alvo
`WindowFacade` must expose a focused-window ownership predicate that answers
whether the global focused window belongs to a specific `TaskId`.
## Escopo
Included:
- Add a focused ownership query to
[window.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/os/facades/window.rs).
- Add a helper in
[window_manager.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/windows/window_manager.rs) if it keeps the facade thin and testable.
- Add unit tests for focused-window ownership in the `prometeu-system` crate.
## Fora de Escopo
- Changing `ShellRunningStep`.
- Removing `focused_window_active` from `PrometeuHubOutcome`.
- Spec edits.
- Overlay/modal policy or active-window semantics.
- Multiple-window policy beyond querying the single global focused window.
## Plano de Execucao
1. Add `WindowManager::focused_window_belongs_to_task`.
In `crates/console/prometeu-system/src/services/windows/window_manager.rs`,
implement a method that:
- returns `false` when `focused` is `None`;
- finds the focused window by `WindowId`;
- returns `true` only when its owner is `WindowOwner::Task(task_id)`;
- returns `false` for `Hub`, `Overlay`, another task id, or stale focus.
2. Add `WindowFacade::focused_window_belongs_to_task`.
In `crates/console/prometeu-system/src/os/facades/window.rs`, expose the
public facade method and delegate to the manager/helper.
3. Keep existing facade methods intact.
Do not remove `focused_window()` or `windows()` in this plan. Existing call
sites may still need them until `PLN-0061` updates firmware.
4. Add tests in `window_manager.rs`.
Cover:
- no focused window returns `false`;
- focused `WindowOwner::Task(task_id)` returns `true`;
- focused `WindowOwner::Task(other_task)` returns `false`;
- focused `WindowOwner::Hub` returns `false`;
- focused `WindowOwner::Overlay` returns `false`;
- stale focused id after window removal returns `false`.
5. Add facade-level coverage if existing `SystemOS` tests provide a convenient
pattern.
If facade-level setup would duplicate manager coverage heavily, keep the
unit coverage at the manager level and rely on the facade as a direct
delegation.
## Criterios de Aceite
- [ ] `os.windows().focused_window_belongs_to_task(task_id)` compiles.
- [ ] The predicate returns `true` only for the currently focused
`WindowOwner::Task(task_id)`.
- [ ] `Hub`, `Overlay`, absent focus, stale focus, and other task owners return
`false`.
- [ ] No firmware behavior changes are included in this plan.
## Tests / Validacao
- Run `cargo test -p prometeu-system`.
- Run any narrower test command available for the window manager module if the
crate supports it.
- Run `discussion validate`.
## Riscos
- Directly scanning `windows` by focused id is simple but can hide stale focus
bugs. Tests must lock stale focus behavior to `false`.
- Adding only a facade method without manager coverage would make the contract
harder to verify. Prefer manager tests.
- Borrowing through `WindowFacade` must remain short-lived and compatible with
existing `SystemOS` facade patterns.
@@ -0,0 +1,128 @@
---
id: PLN-0061
ticket: task-owned-shell-windows
title: Plan - Shell Running Lifecycle Integration
status: open
created: 2026-05-15
completed:
ref_decisions: [DEC-0027]
tags: [runtime, os, task, window-manager, shell, lifecycle, firmware, tests]
---
# Plan - Shell Running Lifecycle Integration
## Briefing
Integrate the accepted task-owned window contract into `ShellRunningStep`.
`ShellRunningStep` must stop using generic focused-window presence as the
liveness contract and must close the shell task through lifecycle when the
focused window no longer belongs to that task.
## Decisions de Origem
- `DEC-0027` - Task-Owned Shell Windows
## Alvo
`ShellRunningStep` continues only when:
```text
TaskState::Foreground
+
os.windows().focused_window_belongs_to_task(task_id)
```
When that predicate is false, the step must call
`os.lifecycle().close_task(task_id)` and return `FirmwareState::HubHome`.
## Escopo
Included:
- Update
[firmware_step_shell_running.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs).
- Adjust the shell-running path in
[prometeu_hub.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs) only if `focused_window_active` becomes unused or misleading.
- Add firmware/system tests proving lifecycle closure and Hub return behavior.
- Preserve `GameRunningStep` behavior.
## Fora de Escopo
- Spec edits; covered by `PLN-0059`.
- Adding the window ownership API; covered by `PLN-0060`.
- Overlay/modal policy.
- Background, minimization, app switcher, dock, or multiple-window behavior.
- Treating games as windows.
## Plano de Execucao
1. Depend on `PLN-0060`.
Do not update `ShellRunningStep` until
`os.windows().focused_window_belongs_to_task(task_id)` exists.
2. Replace the liveness predicate in `ShellRunningStep`.
In `firmware_step_shell_running.rs`, keep the existing `TaskState`
validation. After `ctx.hub.update_shell_profile(...)`, replace the
`outcome.focused_window_active` check with:
```text
!ctx.os.windows().focused_window_belongs_to_task(self.task_id)
```
3. Preserve crash handling order.
Keep VM crash handling before window-liveness closure so a crash reported by
the shell update remains a crash, not a normal close.
4. Close through lifecycle before returning Hub.
When the focused-window ownership predicate is false:
- log the closure with task id;
- call `ctx.os.lifecycle().close_task(self.task_id)`;
- log lifecycle close errors;
- return `Some(FirmwareState::HubHome(HubHomeStep))`.
5. De-emphasize or remove `focused_window_active`.
If `SystemProfileUpdate.focused_window_active` has no remaining call sites,
remove it from `SystemProfileUpdate` and its construction. If another
legitimate caller remains, keep it but do not use it for shell task
liveness.
6. Add or update tests.
Use existing firmware tests in
[firmware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-firmware/src/firmware/firmware.rs)
or a nearby test module. Cover:
- focused task-owned window keeps the shell path running;
- no focused window closes task and returns `HubHome`;
- focused `Hub` window closes task and returns `HubHome`;
- focused `Overlay` window closes task and returns `HubHome` in v1;
- focused window for another task closes task and returns `HubHome`;
- lifecycle close changes task to `Closed` and process to `Stopped`;
- `GameRunningStep` remains independent from `WindowManager`.
## Criterios de Aceite
- [ ] `ShellRunningStep` no longer uses `focused_window_active` as its
continuation contract.
- [ ] `ShellRunningStep` uses
`os.windows().focused_window_belongs_to_task(self.task_id)`.
- [ ] A false predicate closes the task through lifecycle before returning
`HubHome`.
- [ ] `Hub`, `Overlay`, absent focus, and another task's focused window all
fail the predicate for the current shell task.
- [ ] Game-running behavior is unchanged and remains outside `WindowManager`.
## Tests / Validacao
- Run `cargo test -p prometeu-system`.
- Run `cargo test -p prometeu-firmware`.
- Run a workspace or targeted build command used by this repository if the two
crate tests are not sufficient.
- Run `discussion validate`.
## Riscos
- Current Hub update behavior may close or replace windows during the same tick;
tests need to account for the final focused window after `update_shell_profile`.
- Removing `focused_window_active` may require small cleanup in system tests or
callers.
- The v1 overlay behavior is intentionally strict. Do not add overlay
preservation logic in this plan.