prometeu-runtime/discussion/workflow/plans/PLN-0090-add-render-frame-pacing-contract.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0090	vm-render-parallel-execution-boundary	Add Render Frame Pacing Contract	done	2026-06-05	DEC-0031	runtime frame-clock scheduler vm

Briefing

DEC-0031 separates Game logical frame pacing from render worker ACK. Game frames are paced by a frame clock/scheduler and still end at FRAME_SYNC.

Objective

Define and implement the runtime contract that authorizes Game logical frames without using render present completion as ACK.

Dependencies

• Source decision: DEC-0031.
• PLN-0091 should define which AppModes consume this policy.

Scope

• Introduce or formalize a FrameClock/FrameScheduler authority for Game workloads.
• Ensure Game VM runs at most one logical frame per authorized frame tick.
• Preserve FRAME_SYNC as logical frame end.
• Record overrun/repeat conditions through telemetry hooks.

Non-Goals

• Do not make Shell UI run a game loop.
• Do not implement catch-up frames or logical frame skipping.
• Do not tie VM progress to render ACK.

Execution Method

1. Inspect current tick/budget/FRAME_SYNC handling.
2. Identify where a frame tick should authorize Game VM execution.
3. Introduce a narrow scheduling API consumed by Game lifecycle code.
4. Preserve budget/cycle/time accounting only for watchdog, certification, and diagnostics.
5. Add telemetry points for logical-frame-overrun and no-new-frame/repeat.
6. Document the distinction between logical frame ID, produced submission ID, and presented frame ID.

Acceptance Criteria

• Game VM cannot run unlimited logical frames ahead of the frame clock.
• Render worker or render consumer ACK is not required to start the next logical frame.
• Slow logical frames remain sequential and produce overrun/stutter telemetry.
• Shell lifecycle remains unaffected.

Tests

• Unit tests for scheduler permitting one Game frame per tick.
• Test that no catch-up N+k logical frame is produced after overrun.
• Regression tests around FRAME_SYNC behavior.

Affected Artifacts

• VM runtime scheduling modules.
• Firmware/Game running step.
• Telemetry interfaces touched by pacing.