From 32b838f9c4758c865ddd08da08c40c47b95903e1 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Fri, 15 May 2026 11:44:19 +0100 Subject: [PATCH] implements PLN-0059 task window specs --- discussion/index.ndjson | 2 +- ...LN-0059-plan-task-window-contract-specs.md | 16 ++--- .../12-firmware-pos-and-prometeuhub.md | 71 +++++++++++++++++-- 3 files changed, 75 insertions(+), 14 deletions(-) diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 3874ab01..22674046 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,5 +1,5 @@ {"type":"meta","next_id":{"DSC":36,"AGD":36,"DEC":28,"PLN":62,"LSN":44,"CLSN":1}} -{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-agenda-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-decision-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0059","file":"PLN-0059-plan-task-window-contract-specs.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0060","file":"PLN-0060-plan-focused-window-ownership-api.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0061","file":"PLN-0061-plan-shell-running-lifecycle-integration.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0035","status":"in_progress","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[{"id":"AGD-0035","file":"AGD-0035-agenda-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-decision-task-owned-shell-windows.md","status":"accepted","created_at":"2026-05-15","updated_at":"2026-05-15","ref_agenda":"AGD-0035"}],"plans":[{"id":"PLN-0059","file":"PLN-0059-plan-task-window-contract-specs.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0060","file":"PLN-0060-plan-focused-window-ownership-api.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]},{"id":"PLN-0061","file":"PLN-0061-plan-shell-running-lifecycle-integration.md","status":"open","created_at":"2026-05-15","updated_at":"2026-05-15","ref_decisions":["DEC-0027"]}],"lessons":[]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0023","status":"done","ticket":"perf-full-migration-to-atomic-telemetry","title":"Agenda - [PERF] Full Migration to Atomic Telemetry","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["perf","runtime","telemetry"],"agendas":[{"id":"AGD-0021","file":"AGD-0021-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"decisions":[{"id":"DEC-0008","file":"DEC-0008-full-migration-to-atomic-telemetry.md","status":"accepted","created_at":"2026-04-10","updated_at":"2026-04-10"}],"plans":[{"id":"PLN-0007","file":"PLN-0007-full-migration-to-atomic-telemetry.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}],"lessons":[{"id":"LSN-0028","file":"discussion/lessons/DSC-0023-perf-full-migration-to-atomic-telemetry/LSN-0028-converging-to-single-atomic-telemetry-source.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]} {"type":"discussion","id":"DSC-0020","status":"done","ticket":"jenkins-gitea-integration","title":"Jenkins Gitea Integration and Relocation","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["ci","jenkins","gitea"],"agendas":[{"id":"AGD-0018","file":"AGD-0018-jenkins-gitea-integration-and-relocation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"decisions":[{"id":"DEC-0003","file":"DEC-0003-jenkins-gitea-strategy.md","status":"accepted","created_at":"2026-04-07","updated_at":"2026-04-07"}],"plans":[{"id":"PLN-0003","file":"PLN-0003-jenkins-gitea-execution.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}],"lessons":[{"id":"LSN-0021","file":"discussion/lessons/DSC-0020-jenkins-gitea-integration/LSN-0021-jenkins-gitea-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]} diff --git a/discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md b/discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md index a81f0e05..0a247675 100644 --- a/discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md +++ b/discussion/workflow/plans/PLN-0059-plan-task-window-contract-specs.md @@ -2,9 +2,9 @@ id: PLN-0059 ticket: task-owned-shell-windows title: Plan - Task Window Contract Specs -status: open +status: done created: 2026-05-15 -completed: +completed: 2026-05-15 ref_decisions: [DEC-0027] tags: [runtime, os, task, window-manager, shell, lifecycle, specs] --- @@ -91,13 +91,13 @@ Included: ## 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 +- [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. -- [ ] The spec does not introduce overlay, background, minimization, app +- [x] The spec does not introduce overlay, background, minimization, app switcher, dock, or multiple-window policy. ## Tests / Validacao diff --git a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md index 93a832bd..a4b90b86 100644 --- a/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md +++ b/docs/specs/runtime/12-firmware-pos-and-prometeuhub.md @@ -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.