prometeu-runtime/discussion/workflow/plans/PLN-0073-render-contract-specs.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0073	render-frame-packet-boundary	Render Contract Specs	done	2026-05-25	DEC-0030	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