prometeu-runtime/discussion/workflow/decisions/DEC-0030-logical-render-pipeline-command-boundary.md

id	ticket	title	status	created	ref_agenda	tags
DEC-0030	render-frame-packet-boundary	Logical Render Pipeline Command Boundary	accepted	2026-05-25	AGD-0038	gfx renderer runtime frame-composer architecture ui pipeline

Decision - Logical Render Pipeline Command Boundary

Status

Accepted.

Contexto

Prometeu ja concluiu a migracao do framebuffer/runtime para RGBA8888. O proximo passo do renderer nao e introduzir GPU, 3D, multiplos backends, troca dinamica complexa de pipeline ou render thread. O objetivo imediato e criar uma fronteira arquitetural limpa entre:

• producao logica de comandos de render;
• fechamento/publicacao de frame;
• coordenacao entre AppMode::Game e AppMode::Shell;
• rasterizacao/publicacao em uma superficie real.

O estado atual ainda acopla codigo logico ao Gfx/framebuffer. FrameComposer ja centraliza parte da orquestracao do frame de jogo, mas ainda desenha por GfxBridge. Prometeu Hub, shell/system UI, splash/crash e primitivas gfx.* tambem acessam desenho imperativo direto. Essa decisao normatiza a nova fronteira de comandos e o papel de cada dominio.

Decisao

Prometeu MUST separar render pipeline logico de render implementation.

O runtime SHALL introduce a RenderManager as the runtime-level render coordination abstraction. RenderManager MUST NOT be a host-specific renderer and MUST NOT contain desktop presentation details. Host/render-surface implementations SHALL adapt RenderManager submissions to the local hardware or host surface.

The canonical render flow SHALL be:

domain buffers during logical frame
-> RenderManager closes buffers
-> RenderSubmission snapshot
-> render surface / implementation consumes submission
-> RGBA8888 surface publication

The v1 logical render domains are:

• composer.* for Game 2D high-level frame composition: scene, camera, sprites, HUD, and Game 2D frame orchestration.
• gfx2d.* for Game 2D primitives only.
• gfxui.* for Shell UI primitives.

The v1 app modes are:

• AppMode::Game, which SHALL route to Game 2D submissions.
• AppMode::Shell, which SHALL route to Shell UI submissions.

No AppMode::System rename is accepted by this decision.

RenderSubmission MUST be coherent with AppMode. The initial submission model SHOULD be a typed envelope rather than a generic universal command list:

RenderSubmission
- frame_id
- app_mode
- packet:
  - Game2D(Game2DFramePacket)
  - ShellUi(UiFramePacket)

The exact Rust layout may evolve during planning, but the contract MUST preserve typed per-pipeline command sets.

Rationale

Typed command sets preserve domain meaning. Game 2D and Shell UI have different responsibilities and should not be forced into a weak universal command list. A future 3D or custom 2D pipeline should add its own packet rather than reinterpret a 2D/UI command model.

RenderManager is required because mode transitions do not belong completely to either Shell UI or Game 2D. Shell can render an exit transition before launching a game, but once Game mode owns the frame, Shell UI is no longer available to render the entry transition. Therefore transition coordination, surface maintenance, active render capabilities, and frame publication need a manager above individual pipelines.

Command buffers and submissions must be distinct. Domain buffers are mutable while the logical frame is being built. A RenderSubmission is a closed snapshot. This makes future VM/render parallelism possible without requiring a render thread in v1.

The current fade model is rejected. Fade was a hardware-direction idea that no longer belongs in the Prometeu render contract after RGBA8888. Fade MUST NOT remain as a packet field, syscall, or implementation habit. Future visual transitions belong to RenderManager.

Invariantes / Contrato

Pipeline and Implementation Boundary

• Pipelines MUST produce logical commands or state.
• Render implementations MUST consume submissions and write/publish to a surface.
• Pipeline code MUST NOT require direct mutable access to the framebuffer.
• Pipeline code MUST NOT depend on host-specific presentation details.

RenderManager

• RenderManager MUST coordinate active AppMode, submission closure, mode transitions, capabilities, and publication policy.
• RenderManager MUST be a runtime abstraction, not a host renderer.
• Host/render-surface implementations MUST be separate adapters.
• RenderManager MUST own transition coordination between Game and Shell.
• RenderManager MUST own the policy for surface publication/present through the render surface.

Command Buffers and Submissions

• Each render domain/pipeline MUST own its own mutable command/state buffer during a logical frame.
• RenderManager MUST close the active buffers into a RenderSubmission at frame boundary.
• Once closed, RenderSubmission MUST be treated as immutable by producers.
• RenderSubmission MUST include frame_id and app_mode.
• Future parallel render MUST be supported by the contract: consuming a submission MUST NOT require &mut Hardware, &mut Gfx, or live mutable VM state.
• Backpressure policy MUST be latest-complete-submission-wins. The system MUST NOT accumulate an unbounded frame queue.

AppMode Routing

• AppMode::Game SHALL expose and route Game render domains.
• AppMode::Shell SHALL expose and route Shell UI render domains.
• Renderers/capabilities MAY differ by app mode.
• PBS stdlibs MAY expose similar high-level names, including gfx, but they MUST map to mode-appropriate ABI domains.

ABI Domains

• composer.* MUST remain the high-level Game 2D composition domain.
• composer.* MUST own scene, camera, sprites, HUD, and Game 2D frame orchestration.
• gfx2d.* MUST contain Game 2D primitives only.
• gfx2d.* MUST NOT own scene, camera, sprites, HUD, or frame orchestration.
• gfxui.* MUST contain Shell UI primitives.
• gfxui.* MUST NOT contain widget/layout policy. Widget/layout belongs in Shell/UI code or stdlib, not the host implementation.
• Capabilities MUST be separated for composer, gfx2d, and gfxui.

Game 2D Composition

• Game 2D scene and sprites MUST compose by integer layer.
• The v1 Game 2D model has four available layers.
• Scene and sprite composition MAY interleave by layer, normally as sprite/scene ordering across the four layers.
• HUD MUST render above scene/sprite composition.
• HUD belongs to composer in v1 and remains a minimal, evolvable contract.
• HUD in this decision means Game HUD only. Shell/system UI is always part of the Shell UI pipeline.
• Game 2D publish happens after scene/sprite/HUD composition.

Shell UI Composition

• Shell UI MUST use its own gfxui.* primitive command set.
• Shell UI commands MAY reduce to the same local drawing directives as Game 2D primitives inside a host/render-surface implementation.
• That reduction MUST remain an implementation detail and MUST NOT collapse the ABI domains.

Fade and Transitions

• Fade MUST be removed completely from canonical pipeline contracts.
• Fade MUST NOT appear as a Game2DFramePacket, UiFramePacket, RenderSubmission, composer, gfx2d, or gfxui field or syscall.
• Future visual transitions MUST be coordinated by RenderManager.

Debug Overlay

• The current host-owned debug overlay is not part of the new render architecture.
• It MAY be removed during execution.
• A future console/debug UI MUST be discussed as a separate product/domain, not preserved as inherited host overlay behavior.

Impactos

Spec

Specs must define the logical render pipeline model, RenderManager, RenderSubmission, app-mode routing, domain buffers, and publication boundary in English.

The public syscall/ABI specs must replace the old primitive gfx.* surface with mode-appropriate gfx2d.* and gfxui.* primitive domains while preserving composer.* as the high-level Game 2D composition domain.

Runtime

Runtime frame execution must stop treating Gfx/framebuffer as the direct target of logical render calls. It must accumulate domain state/commands and let RenderManager close submissions.

VirtualMachineRuntime and firmware flow must route frame closure through RenderManager.

HAL

HAL must expose distinct contracts for:

• composer;
• gfx2d;
• gfxui;
• render submissions;
• render manager/surface boundary.

Capability flags must be split accordingly.

Host

The desktop host remains a concrete render-surface implementation. It may continue publishing RGBA8888 to pixels, but that behavior must sit below the render-surface adapter, not inside logical pipeline APIs.

Host debug overlay may be removed.

Firmware / Shell

Shell UI must migrate away from direct gfx_mut() drawing toward gfxui.*/Shell UI command buffers.

Game mode must migrate toward composer.* plus gfx2d.* buffers closed by RenderManager.

PBS / Stdlibs

PBS Game and Shell stdlibs may present similar high-level APIs to authors. They must map to different ABI domains according to AppMode.

Game stdlib should map scene/camera/sprites/HUD to composer.* and primitive Game drawing to gfx2d.*.

Shell stdlib should map UI primitives to gfxui.*.

Alternativas Descartadas

Universal RenderCommand

A single RenderCommand display list for Game, Shell, and future pipelines is rejected. It collapses domain meaning and would likely force future 3D or custom pipelines into a 2D/UI-shaped contract.

Trait-Only RenderPipeline

A trait that calls render(&mut Surface) without a closed packet is rejected as the primary boundary. It preserves immediate rendering and does not prepare VM/render parallelism.

Backend Registry Now

A full backend registry, GPU/CPU backend abstraction, dynamic pipeline switching, render thread, or 3D implementation is out of scope. Those may come later after the command boundary is stable.

Moving Composer into Gfx2D

Moving scene, camera, sprites, HUD, or frame orchestration into gfx2d.* is rejected. gfx2d.* is primitives only.

Referencias

• Agenda: AGD-0038
• Related dependency: DSC-0011 dirty regions must wait until this boundary exists.
• Related prior lessons: frame composition belongs above the render backend; public ABI must follow canonical service boundaries; RGBA8888 is the canonical framebuffer contract.

Propagacao Necessaria

• Create a plan before any spec or code changes.
• Update canonical specs in English.
• Update HAL syscall registry, capability definitions, and resolver tests.
• Update PBS/stdlib syscall declarations for Game and Shell.
• Update runtime dispatch so render syscalls mutate domain buffers instead of drawing directly.
• Introduce RenderManager, domain buffers, RenderSubmission, and render-surface implementation boundary.
• Migrate Game 2D first, then Shell UI, unless the plan proves both can be safely migrated together.
• Remove fade surfaces from render contracts.
• Remove or explicitly retire the host debug overlay.
• Add packet/submission tests, app-mode capability tests, and pixel-equivalence tests for unchanged visible behavior.

Revision Log

• 2026-05-25: Initial decision draft from AGD-0038.