---
id: PLN-0073
ticket: render-frame-packet-boundary
title: Render Contract Specs
status: done
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`