implements PLN-0059 task window specs
This commit is contained in:
@@ -31,6 +31,14 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
- **AppMode**: cartridge mode, currently `Game` or `System`.
|
||||
- **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
|
||||
- **Host tick**: the host-driven outer update tick.
|
||||
- **Process**: technical execution owned by POS lifecycle.
|
||||
- **Task**: navigable presence associated with an app flow.
|
||||
- **Window**: visual presence for a shell/system task when that task is
|
||||
represented by the system window model.
|
||||
- **WindowOwner**: ownership marker for a system window. The v1 owners are
|
||||
`Hub`, `Task(TaskId)`, and `Overlay`.
|
||||
- **Shell task window**: a `WindowManager` window whose owner is
|
||||
`WindowOwner::Task(TaskId)`.
|
||||
|
||||
## 3 POS Responsibilities
|
||||
|
||||
@@ -69,6 +77,8 @@ Game-mode cartridges:
|
||||
- transition firmware into the game-running state;
|
||||
- run as the active app flow;
|
||||
- present through the main frame path.
|
||||
- run as fullscreen firmware sessions;
|
||||
- are not `WindowManager` windows.
|
||||
|
||||
### System
|
||||
|
||||
@@ -77,8 +87,59 @@ System-mode cartridges:
|
||||
- are initialized by POS;
|
||||
- are integrated into the Hub/window environment;
|
||||
- do not replace the firmware state with the game-running path.
|
||||
- are represented as shell task windows when they expose a visual shell
|
||||
presence.
|
||||
|
||||
## 6 Cartridge Load Flow
|
||||
## 6 Task-Owned Shell Windows
|
||||
|
||||
The shell window contract separates execution, navigation, and visual
|
||||
presence:
|
||||
|
||||
```text
|
||||
Process = technical execution
|
||||
Task = navigable presence
|
||||
Window = visual presence of the task
|
||||
```
|
||||
|
||||
For shell/system apps managed by the window model, the visible shell presence
|
||||
must be a `WindowManager` window owned by `WindowOwner::Task(TaskId)`.
|
||||
|
||||
`Hub` windows are not shell task windows. `Overlay` windows are not shell task
|
||||
windows in this v1 contract. Overlay/modal policy, minimization, app switching,
|
||||
dock behavior, background services, and complex multi-window semantics are
|
||||
future contracts and are not defined here.
|
||||
|
||||
Game cartridges must not be represented as `WindowManager` windows. They remain
|
||||
fullscreen sessions driven by `GameRunningStep`.
|
||||
|
||||
For v1, `ShellRunningStep` continues a shell task only while both conditions are
|
||||
true:
|
||||
|
||||
```text
|
||||
TaskState::Foreground
|
||||
+
|
||||
focused window owner == WindowOwner::Task(task_id)
|
||||
```
|
||||
|
||||
The runtime query for the focused-window ownership predicate is:
|
||||
|
||||
```text
|
||||
os.windows().focused_window_belongs_to_task(task_id)
|
||||
```
|
||||
|
||||
If a foreground shell task loses its eligible focused window,
|
||||
`ShellRunningStep` must close the task through `SystemOS` lifecycle before
|
||||
returning to Hub:
|
||||
|
||||
```text
|
||||
Shell task loses its eligible focused window
|
||||
-> os.lifecycle().close_task(task_id)
|
||||
-> TaskState::Closed
|
||||
-> ProcessState::Stopped
|
||||
-> FirmwareState::HubHome
|
||||
```
|
||||
|
||||
## 7 Cartridge Load Flow
|
||||
|
||||
Current high-level flow:
|
||||
|
||||
@@ -93,7 +154,7 @@ If VM initialization fails, firmware transitions to the crash path.
|
||||
|
||||
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
||||
|
||||
## 7 Firmware States
|
||||
## 8 Firmware States
|
||||
|
||||
The current firmware state model includes:
|
||||
|
||||
@@ -107,7 +168,7 @@ The current firmware state model includes:
|
||||
|
||||
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
|
||||
|
||||
## 8 Execution Contract
|
||||
## 9 Execution Contract
|
||||
|
||||
For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
@@ -118,7 +179,7 @@ For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
This keeps the machine model deterministic and observable.
|
||||
|
||||
## 9 Crash Handling
|
||||
## 10 Crash Handling
|
||||
|
||||
Firmware owns terminal fault presentation.
|
||||
|
||||
@@ -130,7 +191,7 @@ When a terminal app fault occurs:
|
||||
|
||||
Crash handling is outside the guest VM execution model.
|
||||
|
||||
## 10 Relationship to Other Specs
|
||||
## 11 Relationship to Other Specs
|
||||
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
|
||||
|
||||
Reference in New Issue
Block a user