117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
---
|
|
id: PLN-0059
|
|
ticket: task-owned-shell-windows
|
|
title: Plan - Task Window Contract Specs
|
|
status: done
|
|
created: 2026-05-15
|
|
completed: 2026-05-15
|
|
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
|
|
|
|
- [x] The spec describes the `Process` / `Task` / `Window` model in English.
|
|
- [x] The spec states that games are not `WindowManager` windows.
|
|
- [x] The spec states that shell app windows use `WindowOwner::Task(TaskId)`.
|
|
- [x] The spec states the v1 `ShellRunningStep` focused-window predicate.
|
|
- [x] The spec states that loss of the eligible focused window closes the task
|
|
through lifecycle before returning to Hub.
|
|
- [x] 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.
|