Logical Render Pipelines and Command Packets
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: PLN-0073
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Render Contract Specs
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Publish canonical English spec language for the logical render pipeline boundary before code migration. The specs must make `RenderManager`, domain buffers, typed `RenderSubmission`, app-mode routing, render-surface publication, latest-complete-submission policy, and fade removal explicit.
|
||||
|
||||
## Target
|
||||
|
||||
Canonical specs describe the DEC-0030 render contract well enough that HAL, runtime, host, firmware, and PBS work can proceed without reopening architecture.
|
||||
|
||||
## Scope
|
||||
|
||||
- Define the logical flow from mutable domain buffers to closed `RenderSubmission` to render-surface publication.
|
||||
- Define `RenderManager` as runtime coordination, not a host renderer.
|
||||
- Define `RenderSubmission` with `frame_id`, `app_mode`, and typed Game 2D or Shell UI packet.
|
||||
- Define `composer.*`, `gfx2d.*`, and `gfxui.*` as separate ABI domains.
|
||||
- Specify latest-complete-submission-wins backpressure.
|
||||
- Remove fade from canonical render contracts.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Rust implementation.
|
||||
- PBS stdlib implementation.
|
||||
- Pixel output changes.
|
||||
- Backend registry, GPU backend, render thread, 3D pipeline, or debug console design.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory existing render, graphics, framebuffer, composer, and syscall specs.
|
||||
2. Replace old primitive `gfx.*` ABI language with the DEC-0030 domain split.
|
||||
3. Add sections for `RenderManager`, domain buffers, submission closure, immutability, and publication.
|
||||
4. Add app-mode and capability routing language for Game and Shell.
|
||||
5. Remove normative fade fields, syscalls, and packet references from render specs.
|
||||
6. Cross-link impacted specs for HAL, runtime, host, firmware, and PBS propagation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs are in English and reference `DEC-0030`.
|
||||
- No canonical render spec presents direct framebuffer mutation as the logical render API.
|
||||
- No canonical render spec keeps fade as a packet field, syscall, or ABI habit.
|
||||
- Specs distinguish logical pipeline production from render-surface implementation.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run repository documentation/spec validation if available.
|
||||
- Inspect `rg -n "fade|gfx\\.\\*|RenderSubmission|RenderManager|present\\(" specs discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md`.
|
||||
- Run `discussion validate` if discussion references change.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing specs may use `gfx.*` as both author API and ABI name; preserve author clarity while changing ABI names.
|
||||
- Removing fade text can accidentally delete transition requirements; move those requirements to `RenderManager` language.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `specs/`
|
||||
- `discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md`
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: PLN-0074
|
||||
ticket: render-frame-packet-boundary
|
||||
title: HAL Render Submission Types
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Introduce HAL-level submission types that encode the logical render boundary without binding consumers to live `Hardware`, `Gfx`, framebuffer, or VM state.
|
||||
|
||||
## Target
|
||||
|
||||
HAL exposes typed contracts for `RenderSubmission`, `Game2DFramePacket`, `ShellUiFramePacket`, frame ids, app-mode routing, and immutable closed submissions.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add typed packet structures for Game 2D and Shell UI.
|
||||
- Add a `RenderSubmission` envelope with `frame_id`, `app_mode`, and typed packet variant.
|
||||
- Add or reuse a monotonic frame id type.
|
||||
- Encode closed-submission immutability through ownership and API shape.
|
||||
- Keep packet types free of host presentation details and live mutable runtime references.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- `RenderManager` behavior beyond type integration.
|
||||
- Renderer/rasterizer implementation.
|
||||
- Backend registry, render thread, GPU path, or 3D packet.
|
||||
- PBS stdlib updates.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Locate current HAL graphics, composer, capability, and app-mode modules.
|
||||
2. Add packet and submission types where ABI-facing render data belongs.
|
||||
3. Represent packets as typed variants: `Game2D(Game2DFramePacket)` and `ShellUi(ShellUiFramePacket)`.
|
||||
4. Ensure constructors or closure APIs consume or clone domain buffer contents.
|
||||
5. Add tests for app-mode and packet coherence.
|
||||
6. Update internal references to use the new types without changing runtime rendering yet.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- HAL contains the DEC-0030 submission and packet vocabulary.
|
||||
- A closed `RenderSubmission` can be handed to a consumer without borrowing live runtime rendering state.
|
||||
- Game and Shell packets are distinguishable at the type level.
|
||||
- The HAL API does not include fade fields.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run HAL crate unit tests.
|
||||
- Add tests for packet construction, app-mode coherence, and immutable ownership semantics.
|
||||
- Inspect `rg -n "fade|UiFramePacket|ShellUiFramePacket|Game2DFramePacket|RenderSubmission" crates specs`.
|
||||
|
||||
## Risks
|
||||
|
||||
- New types must live at the ABI/contract level, not inside a host renderer.
|
||||
- Borrowing shortcuts could leak mutability and violate the future parallel render contract.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- HAL crate/module under `crates/`
|
||||
- HAL tests
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
id: PLN-0075
|
||||
ticket: render-frame-packet-boundary
|
||||
title: RenderManager Core
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Add `RenderManager` as the runtime abstraction that closes domain buffers into typed submissions, tracks active app mode, owns transition coordination placeholders, and hands the latest complete submission to the render surface.
|
||||
|
||||
## Target
|
||||
|
||||
Runtime frame execution routes render closure through `RenderManager` without making it a host renderer or direct framebuffer writer.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add the `RenderManager` module and public runtime API.
|
||||
- Track active `AppMode` and frame id generation.
|
||||
- Close the active domain buffer into a `RenderSubmission`.
|
||||
- Enforce latest-complete-submission-wins rather than an unbounded queue.
|
||||
- Add transition coordination placeholders owned by `RenderManager`.
|
||||
- Provide a publication handoff to a render-surface abstraction.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Full visual transition implementation.
|
||||
- Host-specific presentation details.
|
||||
- Domain buffer implementation beyond integration points.
|
||||
- Render thread, GPU backend, or backend registry.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Add a runtime render module that owns `RenderManager` and related state.
|
||||
2. Wire `VirtualMachineRuntime` frame closure through `RenderManager`.
|
||||
3. Add active app-mode routing and rejection for incoherent packet closure.
|
||||
4. Add latest-complete-submission storage and replacement semantics.
|
||||
5. Add a render-surface handoff interface without calling host-specific `present()` from producers.
|
||||
6. Add explicit no-op transition hooks for future work.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Runtime has one frame closure authority for render submissions.
|
||||
- Producers can mutate domain buffers before closure but cannot mutate the closed submission.
|
||||
- `RenderManager` does not depend on desktop host types.
|
||||
- Backpressure is latest-complete-submission-wins.
|
||||
- App-mode routing is explicit and tested.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests for frame id increment, latest submission replacement, app-mode routing, and no-op transition state.
|
||||
- Add runtime integration coverage proving frame closure passes through `RenderManager`.
|
||||
- Run affected crate tests.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing frame lifecycle code may assume immediate framebuffer mutation; isolate compatibility shims and remove them in later plans.
|
||||
- Transition placeholders must not become hidden fade behavior.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Runtime crate/modules under `crates/`
|
||||
- Runtime tests
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: PLN-0076
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Capabilities and ABI Domain Split
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Split render capabilities and syscall metadata so `composer`, `gfx2d`, and `gfxui` are independently addressable and enforceable according to `AppMode`.
|
||||
|
||||
## Target
|
||||
|
||||
Capability gates reject wrong-domain render syscalls, and metadata no longer treats the old primitive `gfx.*` ABI as the single render surface.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add or rename capability flags for `COMPOSER`, `GFX2D`, and `GFXUI`.
|
||||
- Update syscall metadata for all render-domain calls.
|
||||
- Enforce domain availability by `AppMode::Game` and `AppMode::Shell`.
|
||||
- Update resolver and capability tests.
|
||||
- Preserve `composer.*` as Game 2D high-level composition.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Implementing command buffers.
|
||||
- PBS stdlib author-facing wrappers.
|
||||
- Host rendering.
|
||||
- Backward compatibility for the old primitive `gfx.*` ABI.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Locate capability definitions, syscall registry metadata, and resolver tests.
|
||||
2. Introduce separate render capability identifiers for `composer`, `gfx2d`, and `gfxui`.
|
||||
3. Update metadata for existing composer calls and new or renamed primitive domains.
|
||||
4. Add app-mode checks so Game exposes `composer` and `gfx2d`, while Shell exposes `gfxui`.
|
||||
5. Replace stale tests that assume one graphics capability.
|
||||
6. Run resolver and runtime syscall tests.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Wrong-domain calls fail before mutating render state.
|
||||
- Game mode cannot use `gfxui.*`.
|
||||
- Shell mode cannot use `composer.*` or `gfx2d.*`.
|
||||
- Capability metadata uses the split domain names.
|
||||
- No compatibility promise remains for the old primitive `gfx.*` ABI.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add resolver tests for all three capabilities.
|
||||
- Add app-mode enforcement tests for allowed and rejected calls.
|
||||
- Run affected unit and integration tests.
|
||||
|
||||
## Risks
|
||||
|
||||
- A large rename can hide semantic mistakes; verify every syscall maps to the correct domain responsibility.
|
||||
- Author-facing stdlib names may still use `gfx`; keep this plan focused on ABI metadata.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Syscall metadata and resolver modules under `crates/`
|
||||
- Capability tests
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: PLN-0077
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Composer Buffer and Game2D Packet
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Convert current `composer.*` frame state into a mutable `ComposerBuffer` that closes into `Game2DFramePacket` at frame boundary.
|
||||
|
||||
## Target
|
||||
|
||||
Game 2D scene, camera, sprites, HUD, and frame orchestration are represented as domain-owned state until `RenderManager` closes them into a typed packet.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `ComposerBuffer`.
|
||||
- Move scene, camera, sprite, HUD, layer ordering, and Game 2D orchestration state into the buffer.
|
||||
- Close the buffer into `Game2DFramePacket`.
|
||||
- Preserve the v1 four-layer scene/sprite composition model and HUD-above-game rule.
|
||||
- Ensure fade is absent from Game 2D packet state.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Primitive `gfx2d.*` command buffering.
|
||||
- Shell UI packet work.
|
||||
- Renderer consumption refactor beyond packet shape.
|
||||
- New Game 2D features.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Locate current `FrameComposer`, composer syscalls, scene/camera/sprite/HUD state, and tests.
|
||||
2. Introduce `ComposerBuffer` and migrate composer mutation paths into it.
|
||||
3. Implement closure into `Game2DFramePacket` with immutable packet contents.
|
||||
4. Preserve integer layer ordering across the four Game 2D layers and HUD final composition.
|
||||
5. Route frame closure through `RenderManager`.
|
||||
6. Update tests that currently inspect `FrameComposer` internals.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `composer.*` owns Game 2D high-level frame state.
|
||||
- Closed `Game2DFramePacket` contains all data required by the Game 2D renderer without live VM or `Gfx` access.
|
||||
- Scene/sprite layer behavior and HUD ordering are preserved.
|
||||
- Fade is not represented.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests for buffer mutation and packet closure.
|
||||
- Add composition ordering tests for scene, sprites, and HUD.
|
||||
- Run current frame composer/render tests and compare existing expected output.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing composer code may mix orchestration with drawing; split state capture from rendering before deeper migration.
|
||||
- Layer behavior is user-visible and must not drift.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Composer/frame-composer modules under `crates/`
|
||||
- Game 2D tests
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
id: PLN-0078
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Classic2D Game Renderer Consumer
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Refactor the Classic2D renderer path so it consumes `Game2DFramePacket` instead of being called directly by `FrameComposer` or logical producers.
|
||||
|
||||
## Target
|
||||
|
||||
Classic2D remains the concrete Game 2D rasterizer, but its input is a closed packet and its visible pixel output remains equivalent.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a packet consumer entry point for the current Classic2D/Gfx renderer.
|
||||
- Replace direct `FrameComposer` to `Gfx` calls with packet consumption.
|
||||
- Keep RGBA8888 output unchanged for existing supported scenes.
|
||||
- Keep renderer implementation below the logical pipeline boundary.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Redesigning scene, sprite, HUD, or primitive semantics.
|
||||
- Shell UI rendering.
|
||||
- Backend registry or GPU work.
|
||||
- Dirty region optimization.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Locate the current Classic2D/Gfx rendering entry points and `FrameComposer` call graph.
|
||||
2. Add a `Game2DFramePacket` consumer API.
|
||||
3. Move rendering reads from live composer state to packet data.
|
||||
4. Update frame execution to pass the closed packet into the renderer through the render surface path.
|
||||
5. Preserve existing framebuffer dimensions, RGBA8888 format, and pixel behavior.
|
||||
6. Remove direct producer-to-renderer calls that bypass the packet boundary.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Classic2D renders from `Game2DFramePacket`.
|
||||
- Logical composer code no longer directly mutates `Gfx` during frame production.
|
||||
- Existing Game 2D visual fixtures or tests remain pixel-equivalent except where explicitly updated for the new boundary.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add packet-to-pixels tests for representative scene, sprite, primitive, and HUD cases.
|
||||
- Run existing render tests.
|
||||
- Add regression coverage comparing old expected pixel buffers where available.
|
||||
|
||||
## Risks
|
||||
|
||||
- Packet conversion can accidentally alter draw order; keep tests focused on ordering and final pixels.
|
||||
- Some current code may depend on side effects from direct `Gfx` mutation; identify and replace those effects explicitly.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Classic2D/Gfx renderer modules under `crates/`
|
||||
- Render tests and fixtures
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: PLN-0079
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Gfx2D Primitive Domain
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Replace primitive Game drawing paths with `gfx2d.*` command buffering while keeping `gfx2d` limited to primitives only.
|
||||
|
||||
## Target
|
||||
|
||||
Game primitive drawing becomes a Game-mode ABI domain that records commands into a buffer consumed as part of Game 2D rendering.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `gfx2d.*` syscall domain and command buffer.
|
||||
- Migrate primitive Game drawing calls from old `gfx.*` behavior to `gfx2d.*`.
|
||||
- Ensure `gfx2d` contains primitives only.
|
||||
- Integrate `gfx2d` commands into the Game 2D packet/render path without taking ownership of scene, camera, sprites, HUD, or frame orchestration.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Shell UI primitive domain.
|
||||
- `composer.*` high-level Game state.
|
||||
- Widget/layout policy.
|
||||
- Compatibility with old primitive `gfx.*` ABI names.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory old primitive `gfx.*` syscalls and direct drawing callsites used by Game mode.
|
||||
2. Define the `gfx2d.*` command enum and mutable command buffer.
|
||||
3. Route Game primitive syscalls into the buffer.
|
||||
4. Add app-mode and capability enforcement for Game-only access.
|
||||
5. Integrate buffered primitives into Game 2D packet closure or renderer consumption at the DEC-0030-approved layer.
|
||||
6. Remove or retire old primitive `gfx.*` ABI registrations.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Game primitive commands are buffered as `gfx2d.*`.
|
||||
- `gfx2d` does not own scene, camera, sprites, HUD, or frame orchestration.
|
||||
- Shell mode cannot call `gfx2d.*`.
|
||||
- No logical primitive path directly mutates framebuffer during production.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add syscall tests for each migrated primitive.
|
||||
- Add command buffer ordering tests.
|
||||
- Add capability rejection tests for Shell mode.
|
||||
- Run pixel-equivalence tests for unchanged primitive output.
|
||||
|
||||
## Risks
|
||||
|
||||
- The old `gfx` naming may appear in PBS wrappers; distinguish author API names from ABI domain names.
|
||||
- Primitive ordering relative to composer output must be explicit.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Syscall registry and runtime render domain modules under `crates/`
|
||||
- Game primitive tests
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: PLN-0080
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Shell UI Packet and GfxUI Domain
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Add `gfxui.*` command buffering and `ShellUiFramePacket` for Shell UI primitives while keeping widget/layout policy outside the host/render-surface implementation.
|
||||
|
||||
## Target
|
||||
|
||||
Shell UI emits typed UI primitive commands into a Shell-only packet that render-surface implementations can consume without collapsing UI and Game ABI domains.
|
||||
|
||||
## Scope
|
||||
|
||||
- Define `gfxui.*` primitive commands.
|
||||
- Add a mutable Shell UI command buffer.
|
||||
- Close Shell UI commands into `ShellUiFramePacket`.
|
||||
- Enforce Shell-only capability and app-mode access.
|
||||
- Keep widget/layout policy in Shell/UI code or stdlib layers.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Migrating all Shell callsites; that is handled by the Shell/Hub migration plan.
|
||||
- Game primitive rendering.
|
||||
- New widget framework.
|
||||
- Host-owned debug overlay.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Define the `gfxui.*` syscall and command vocabulary needed for current Shell UI primitives.
|
||||
2. Add a Shell UI command buffer and closure into `ShellUiFramePacket`.
|
||||
3. Add capability metadata and resolver enforcement for `GFXUI`.
|
||||
4. Add a render-surface consumer path that can rasterize Shell UI commands as an implementation detail.
|
||||
5. Keep layout/widget decisions above the packet boundary.
|
||||
6. Add tests for closure, app-mode gating, and packet consumption.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Shell UI commands close into `ShellUiFramePacket`.
|
||||
- `gfxui.*` does not contain widget/layout policy.
|
||||
- Game mode cannot call `gfxui.*`.
|
||||
- Host/render-surface code consumes commands without redefining Shell UI product policy.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add Shell UI command buffer unit tests.
|
||||
- Add app-mode rejection tests for Game mode.
|
||||
- Add render-surface consumer tests for representative primitives.
|
||||
|
||||
## Risks
|
||||
|
||||
- It is easy to migrate widget policy into host rendering while adding UI primitives; keep commands low-level and policy-free.
|
||||
- Shell UI and Game primitives may rasterize similarly, but ABI domains must remain distinct.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Shell UI render domain modules under `crates/`
|
||||
- Syscall metadata and tests
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: PLN-0081
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Shell Hub Migration
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Move Prometeu Hub, shell windows, splash/crash UI, and Shell drawing away from `gfx_mut()` into `gfxui.*` and Shell UI command buffers.
|
||||
|
||||
## Target
|
||||
|
||||
Shell-facing UI no longer draws directly into `Gfx`; it produces Shell UI commands that close into `ShellUiFramePacket`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Migrate Prometeu Hub UI drawing.
|
||||
- Migrate shell windows and window-manager drawing.
|
||||
- Migrate splash and crash UI drawing.
|
||||
- Remove direct Shell access to `gfx_mut()` for render production.
|
||||
- Preserve visible Shell output where behavior is not intentionally changed.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Designing new Hub visuals.
|
||||
- New widget/layout framework.
|
||||
- Game mode migration.
|
||||
- Debug console replacement.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory Shell, Hub, splash, crash, and firmware drawing callsites that use `gfx_mut()` or direct framebuffer access.
|
||||
2. Replace direct primitive drawing with `gfxui.*` buffer writes.
|
||||
3. Route Shell frame closure through `RenderManager`.
|
||||
4. Ensure Shell UI packets are consumed by the render-surface implementation.
|
||||
5. Remove now-unused direct Shell rendering hooks.
|
||||
6. Update tests and snapshots for unchanged visible behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Shell UI production no longer requires mutable `Gfx` access.
|
||||
- Hub, shell windows, splash, and crash UI can render through `ShellUiFramePacket`.
|
||||
- Shell mode does not use `composer.*` or `gfx2d.*`.
|
||||
- Visible UI output is preserved except for approved fixture updates caused by boundary-only refactoring.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add integration tests for Hub/shell frame production.
|
||||
- Add tests for splash and crash UI packet output.
|
||||
- Run host smoke tests where available.
|
||||
- Use pixel or snapshot comparisons for representative Shell screens.
|
||||
|
||||
## Risks
|
||||
|
||||
- Firmware and Shell code may mix lifecycle side effects with drawing; split command production without changing lifecycle semantics.
|
||||
- Some host tests may assume immediate framebuffer writes; update them to observe submissions or final pixels.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Shell, Hub, firmware, and host integration modules under `crates/`
|
||||
- Shell UI tests and fixtures
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: PLN-0082
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Frame Publication and Present Boundary
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Move `present()` and surface publication behind the render-surface implementation boundary so runtime producers no longer publish buffers directly.
|
||||
|
||||
## Target
|
||||
|
||||
Only the render-surface implementation publishes RGBA8888 output; logical producers and `RenderManager` hand off closed submissions through a boundary.
|
||||
|
||||
## Scope
|
||||
|
||||
- Identify all direct `present()` and surface publication callsites.
|
||||
- Define the render-surface adapter boundary.
|
||||
- Route publication through the adapter from `RenderManager`.
|
||||
- Keep desktop `pixels` publication as a host implementation detail.
|
||||
- Preserve frame pacing and invalidation behavior.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- New backend registry.
|
||||
- GPU implementation.
|
||||
- Render thread.
|
||||
- Dirty regions.
|
||||
- Visual transition design.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory `present()`, framebuffer publication, and host invalidation callsites.
|
||||
2. Add or refine a render-surface trait/adapter that consumes `RenderSubmission`.
|
||||
3. Move host desktop publication below that adapter.
|
||||
4. Update runtime frame loop to publish only through `RenderManager` and the adapter.
|
||||
5. Remove direct publication from composer, `gfx2d`, `gfxui`, Shell, and Game producers.
|
||||
6. Verify frame pacing and host invalidation still occur at the correct boundary.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Logical render domains cannot call `present()` or publish buffers directly.
|
||||
- Host desktop publication remains functional below the render-surface boundary.
|
||||
- `RenderManager` owns the policy for selecting the latest complete submission.
|
||||
- Existing frame pacing behavior is not regressed.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests for render-surface handoff.
|
||||
- Add integration tests proving producers cannot publish directly.
|
||||
- Run host desktop render/pacing tests.
|
||||
- Inspect `rg -n "present\\(|publish|pixels" crates` for boundary violations.
|
||||
|
||||
## Risks
|
||||
|
||||
- Publication and invalidation may be coupled in current host code; preserve timing semantics while moving ownership.
|
||||
- A too-broad adapter can become a backend registry prematurely.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Runtime render manager modules
|
||||
- Host desktop render surface modules
|
||||
- Frame pacing tests
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
id: PLN-0083
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Fade Removal
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Remove fade fields, syscalls, packet members, renderer state, tests, and docs from canonical render contracts.
|
||||
|
||||
## Target
|
||||
|
||||
Fade is no longer a render pipeline feature. Future visual transitions remain the responsibility of `RenderManager` and require separate product/domain work.
|
||||
|
||||
## Scope
|
||||
|
||||
- Remove fade from specs, HAL packet types, syscall metadata, runtime state, renderer state, tests, and PBS declarations.
|
||||
- Remove or update tests that assert fade behavior.
|
||||
- Add guard tests or searches that prevent reintroducing fade in canonical render contracts.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Implementing replacement visual transitions.
|
||||
- Replacing fade with another transition API.
|
||||
- Preserving backward compatibility for fade syscalls.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory all fade references in specs, crates, tests, examples, and PBS stdlibs.
|
||||
2. Delete fade fields and syscalls from canonical ABI and packet definitions.
|
||||
3. Remove renderer/runtime fade state and behavior.
|
||||
4. Update callers and tests to stop setting or expecting fade.
|
||||
5. Add documentation language that transitions belong to `RenderManager`.
|
||||
6. Run targeted and full affected tests.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- No canonical packet, syscall, or render contract contains fade.
|
||||
- Runtime and renderer code do not maintain fade state.
|
||||
- Tests no longer depend on fade behavior.
|
||||
- Specs clearly state future transitions are `RenderManager` responsibility.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `rg -n "\\bfade\\b|Fade" specs crates discussion/workflow` and verify remaining references are only historical decision/agenda text or explicit removal notes.
|
||||
- Run affected unit and integration tests.
|
||||
- Add regression tests preventing fade fields in current packet types.
|
||||
|
||||
## Risks
|
||||
|
||||
- Removing tests can reduce coverage; replace fade-specific assertions with packet/transition boundary assertions where appropriate.
|
||||
- Historical discussion files may keep fade references; do not rewrite history unless the framework requires it.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Specs
|
||||
- HAL, runtime, renderer, syscall, PBS, and tests under `crates/`
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: PLN-0084
|
||||
ticket: render-frame-packet-boundary
|
||||
title: Host Debug Overlay Removal
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Remove the current host-owned debug overlay from the render path. Any future console/debug UI is a separate product/domain discussion.
|
||||
|
||||
## Target
|
||||
|
||||
Host rendering no longer injects an inherited debug overlay into Game or Shell output.
|
||||
|
||||
## Scope
|
||||
|
||||
- Identify host-owned debug overlay code and render hooks.
|
||||
- Remove overlay rendering from the host render path.
|
||||
- Remove overlay toggles/tests that assume inherited host drawing.
|
||||
- Preserve non-render telemetry and logging where they are not tied to overlay drawing.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Designing a replacement debug console.
|
||||
- Moving debug UI into `gfxui.*`.
|
||||
- Changing telemetry collection.
|
||||
- Removing unrelated developer diagnostics.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory debug overlay rendering callsites and tests.
|
||||
2. Remove host overlay injection from Game and Shell render paths.
|
||||
3. Delete overlay-specific drawing state, toggles, and fixture expectations.
|
||||
4. Keep telemetry/logging APIs that do not render overlay pixels.
|
||||
5. Update docs/specs to state that future debug UI requires a separate decision.
|
||||
6. Run host and render tests.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Host render path does not draw debug overlay pixels.
|
||||
- Game and Shell output do not depend on host overlay state.
|
||||
- Remaining diagnostics do not violate the render pipeline boundary.
|
||||
- Docs do not preserve host overlay as an architectural requirement.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run host render tests.
|
||||
- Add or update tests proving overlay state does not affect final rendered output.
|
||||
- Run `rg -n "debug overlay|overlay|DebugOverlay" crates specs discussion/workflow` and inspect remaining references.
|
||||
|
||||
## Risks
|
||||
|
||||
- Removing overlay code can accidentally remove useful telemetry; keep non-render diagnostics intact.
|
||||
- The word overlay may also refer to Game HUD/primitives; distinguish those from host debug overlay.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Host desktop modules under `crates/`
|
||||
- Host/render tests
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: PLN-0085
|
||||
ticket: render-frame-packet-boundary
|
||||
title: PBS Stdlib and Syscall Declarations
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Update PBS Game and Shell stdlibs so high-level APIs map to app-mode-specific ABI domains: Game uses `composer.*` and `gfx2d.*`; Shell uses `gfxui.*`.
|
||||
|
||||
## Target
|
||||
|
||||
PBS authors can keep ergonomic high-level APIs where appropriate, but generated or declared syscalls use the correct DEC-0030 ABI domain for the active app mode.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update Game stdlib declarations for `composer.*` and `gfx2d.*`.
|
||||
- Update Shell stdlib declarations for `gfxui.*`.
|
||||
- Remove old primitive `gfx.*` ABI declarations.
|
||||
- Keep author-facing wrappers clear about mode-specific behavior.
|
||||
- Update examples/tests that compile PBS code.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Runtime implementation of the syscall handlers.
|
||||
- New visual APIs beyond the domain split.
|
||||
- Backward compatibility for old primitive `gfx.*` ABI declarations.
|
||||
- Widget/layout redesign.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Inventory PBS stdlib files and syscall declaration generation.
|
||||
2. Map Game scene/camera/sprites/HUD APIs to `composer.*`.
|
||||
3. Map Game primitive APIs to `gfx2d.*`.
|
||||
4. Map Shell primitive APIs to `gfxui.*`.
|
||||
5. Remove or fail old primitive `gfx.*` ABI declarations.
|
||||
6. Update PBS compile tests, examples, and syscall metadata expectations.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- PBS Game code emits only Game-allowed render ABI domains.
|
||||
- PBS Shell code emits only Shell-allowed render ABI domains.
|
||||
- Old primitive `gfx.*` ABI declarations are gone or explicitly rejected.
|
||||
- Existing examples are updated to the new declarations.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run PBS stdlib and compiler tests.
|
||||
- Add Game and Shell declaration tests for emitted syscall names.
|
||||
- Add negative tests for wrong-domain declarations.
|
||||
|
||||
## Risks
|
||||
|
||||
- User-facing API names may remain similar while ABI names change; tests must assert emitted syscall domains, not just wrapper names.
|
||||
- Examples can mask stale declarations if they do not compile in both Game and Shell contexts.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- PBS stdlib files
|
||||
- Syscall declaration generation
|
||||
- PBS tests and examples
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
id: PLN-0086
|
||||
ticket: render-frame-packet-boundary
|
||||
title: End-to-End Render Boundary Validation
|
||||
status: open
|
||||
created: 2026-05-25
|
||||
ref_decisions: [DEC-0030]
|
||||
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Source decision: `DEC-0030`.
|
||||
|
||||
Add end-to-end validation proving the new boundary works across Game and Shell modes after the granular implementation plans land.
|
||||
|
||||
## Target
|
||||
|
||||
Integration coverage demonstrates typed submissions, app-mode capability gates, immutable closed submissions, render-surface publication, fade removal, and visible output preservation.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add Game end-to-end tests from PBS/syscall production to `Game2DFramePacket` and final pixels.
|
||||
- Add Shell end-to-end tests from UI production to `ShellUiFramePacket` and final pixels.
|
||||
- Test wrong-domain capability failures.
|
||||
- Test closed-submission immutability.
|
||||
- Test latest-complete-submission-wins behavior.
|
||||
- Test absence of fade and host debug overlay from canonical paths.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Implementing missing production code.
|
||||
- New rendering features.
|
||||
- Performance tuning.
|
||||
- Dirty regions.
|
||||
|
||||
## Execution Sequence
|
||||
|
||||
1. Define representative Game and Shell scenarios that cover composer, `gfx2d`, and `gfxui`.
|
||||
2. Add integration harness access to inspect closed submissions where appropriate.
|
||||
3. Assert Game produces `RenderSubmission::Game2D` and Shell produces `RenderSubmission::ShellUi`.
|
||||
4. Assert wrong-domain syscalls fail before mutating buffers.
|
||||
5. Assert closed submissions remain unchanged after producers continue mutating the next frame.
|
||||
6. Assert final pixels match existing expected output for unchanged scenarios.
|
||||
7. Add searches or tests proving fade and host debug overlay are absent from the active render path.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Game and Shell each have end-to-end typed submission tests.
|
||||
- Capability gates reject `gfxui` in Game and `composer`/`gfx2d` in Shell.
|
||||
- Closed submissions are immutable snapshots.
|
||||
- Latest complete submission replaces older unpublished submissions without queue growth.
|
||||
- Unchanged Game and Shell scenarios remain visually equivalent.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run full affected Rust test suites.
|
||||
- Run PBS compile/runtime integration tests.
|
||||
- Run pixel-equivalence tests for representative Game and Shell output.
|
||||
- Run `discussion validate` once execution discussion artifacts are updated.
|
||||
|
||||
## Risks
|
||||
|
||||
- End-to-end tests may become brittle if they assert host details; assert the logical contract and final pixels, not internal host implementation names.
|
||||
- Pixel-equivalence fixtures must account for intentional removals such as host debug overlay.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- Integration tests under `crates/`
|
||||
- PBS tests
|
||||
- Render fixtures
|
||||
Reference in New Issue
Block a user