Logical Render Pipelines and Command Packets

This commit is contained in:
2026-05-25 11:33:34 +01:00
parent 38544ed3f1
commit 2b69be0f11
17 changed files with 1616 additions and 1 deletions
@@ -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