VM and Render Parallel Execution Boundary

This commit is contained in:
2026-06-06 12:03:10 +01:00
parent df0d7949c8
commit 26e038e195
16 changed files with 279 additions and 1676 deletions
@@ -1,62 +0,0 @@
---
id: PLN-0087
ticket: vm-render-parallel-execution-boundary
title: Fix Game2D Packet Overlay Composition
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, game2d, packet, overlay]
---
## Briefing
`DEC-0031` requires `RenderSubmissionPacket::Game2D` to be a complete frame description. The current active-scene path can bypass the packet and lose `gfx2d` overlay commands.
## Objective
Make Game2D packet consumption identical for active-scene and no-scene frames: scene/layers/sprites first, then `gfx2d` primitives as final overlay.
## Dependencies
- Source decision: `DEC-0031`.
- Existing Game2D packet types in `crates/console/prometeu-hal`.
- Existing publish path in `crates/console/prometeu-drivers`.
## Scope
- Update Game2D render publication so active-scene rendering consumes the packet and applies `gfx2d`.
- Keep Shell UI behavior unchanged.
- Add regression tests for active scene plus primitive overlay.
## Non-Goals
- Do not introduce a render worker.
- Do not change frame pacing, telemetry, lifecycle, or AppMode policy.
- Do not redesign `FrameComposer` beyond what is needed to consume the packet correctly.
## Execution Method
1. Inspect `Hardware::publish_render_submission`, `Gfx::render_game2d_frame_packet`, and `FrameComposer::render_frame`.
2. Replace the active-scene branch that bypasses `Game2DFramePacket` with a packet-consuming path.
3. Ensure `gfx2d` commands are applied after scene/layer/sprite composition in all Game2D branches.
4. Add a test fixture with an active scene and a primitive overlay that would visibly overwrite or mark the composed layer.
5. Add a no-scene regression test if current coverage does not already lock the overlay order.
## Acceptance Criteria
- Active-scene Game2D frames render `gfx2d` after layer/sprite composition.
- No-scene Game2D frames preserve the existing overlay behavior.
- `Hardware::publish_render_submission` does not discard `packet.gfx2d`.
- Tests fail on the old active-scene bypass behavior.
## Tests
- Unit or integration test around Game2D packet publication.
- Pixel/assertion test for overlay-after-scene ordering where practical.
- Existing renderer tests continue to pass.
## Affected Artifacts
- `crates/console/prometeu-drivers/src/hardware.rs`
- `crates/console/prometeu-hal/src/render_submission.rs`
- `crates/console/prometeu-system` or renderer test modules as needed.
@@ -1,63 +0,0 @@
---
id: PLN-0088
ticket: vm-render-parallel-execution-boundary
title: Define Read-Only Render Resource Boundary
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, resources, cache, banks]
---
## Briefing
`DEC-0031` requires render packets to carry small owned data and stable resource IDs, while heavy banks/caches remain resident and read-only to render consumers.
## Objective
Define and enforce the read-only resource boundary needed before any worker can safely read scene/glyph/cache data.
## Dependencies
- Source decision: `DEC-0031`.
- `PLN-0087` should clarify the packet consumer path before this plan finalizes worker-facing APIs.
## Scope
- Identify every resource read during Game2D rendering.
- Classify data as packet-owned, resident read-only, or logical-core mutable preparation state.
- Add trait/API boundaries for render read access where missing.
- Document which types must be `Send + Sync` for a real threaded worker.
## Non-Goals
- Do not make resource swaps transactional.
- Do not capture `Arc<GlyphBank>` or `Arc<SceneBank>` inside every submission.
- Do not implement background asset loading policy.
## Execution Method
1. Trace Game2D render reads from packet to glyph bank, scene bank, viewport cache, and framebuffer helpers.
2. Create a short internal module-level contract for render resource access.
3. Add or refine read-only access traits for banks/cache without exposing mutable runtime state.
4. Add compile-time assertions or targeted tests for `Send + Sync` where a threaded worker will require them.
5. Keep resource identity in submissions as IDs/handles, not heavy ownership captures.
## Acceptance Criteria
- Render consumer APIs can be described as packet-owned plus read-only resource access.
- No worker-facing API requires `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state.
- Shared read APIs that cross thread boundaries have explicit `Send + Sync` expectations.
- Existing synchronous renderer behavior remains unchanged.
## Tests
- Compile-time trait assertions for read-only resource APIs where practical.
- Unit tests for read-only bank/cache access.
- Existing asset/scene rendering tests continue to pass.
## Affected Artifacts
- `crates/console/prometeu-hal`
- `crates/console/prometeu-system`
- `crates/console/prometeu-drivers`
- Relevant renderer/resource tests.
@@ -1,62 +0,0 @@
---
id: PLN-0089
ticket: vm-render-parallel-execution-boundary
title: Introduce Render Handoff Abstraction
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, handoff, latest-wins]
---
## Briefing
`DEC-0031` requires a single-slot latest-wins handoff where the producer never blocks on render ACK and replacement before consumption is observable.
## Objective
Introduce a render handoff abstraction that can be used synchronously today and by a worker later.
## Dependencies
- Source decision: `DEC-0031`.
- `PLN-0093` should define telemetry counters before final instrumentation is wired.
## Scope
- Add a small handoff type or trait around one pending owned `RenderSubmission`.
- Support publish, take latest, replace pending, and drain/discard operations.
- Report replacement/drop events to telemetry hooks.
- Integrate the abstraction into `RenderManager` without starting a worker.
## Non-Goals
- Do not spawn a thread.
- Do not implement frame pacing.
- Do not change Shell UI default rendering policy.
## Execution Method
1. Locate `RenderManager::latest_complete_submission` ownership and publication flow.
2. Introduce a handoff module with single pending slot semantics.
3. Move `RenderSubmission` into the slot on publication.
4. Make `take_latest` transfer ownership to the consumer.
5. Count replacement when a pending submission is overwritten before consumption.
6. Keep current synchronous publication working by immediately taking and rendering through the same abstraction.
## Acceptance Criteria
- `RenderManager` no longer relies on an unconstrained raw `Option<RenderSubmission>` for the future worker boundary.
- Publishing a newer pending submission replaces the old one without blocking.
- The consumer receives owned submissions.
- Replacement before consume is observable.
## Tests
- Unit tests for empty take, publish/take, publish/replace/take, and drain/discard.
- Integration smoke test that existing synchronous render still presents frames.
## Affected Artifacts
- `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`
- New or existing render handoff module under `crates/console/prometeu-system`.
- Render manager tests.
@@ -1,63 +0,0 @@
---
id: PLN-0090
ticket: vm-render-parallel-execution-boundary
title: Add Render Frame Pacing Contract
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [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.
@@ -1,63 +0,0 @@
---
id: PLN-0091
ticket: vm-render-parallel-execution-boundary
title: Implement AppMode Render Policy Matrix
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, appmode, shell, game, policy]
---
## Briefing
`DEC-0031` requires render execution policy to be explicit by AppMode/pipeline: Game is frame-paced and may use worker; Shell/System UI is lifecycle-driven and local/synchronous by default.
## Objective
Add an explicit render policy matrix so Game and Shell rendering cannot accidentally share the wrong lifecycle or pacing model.
## Dependencies
- Source decision: `DEC-0031`.
- `PLN-0090` defines the Game pacing contract.
## Scope
- Represent render policy for current `AppMode::Game` and `AppMode::Shell`.
- Make policy selection a SystemOS/lifecycle decision executed by `RenderManager`.
- Add host/runtime capability fallback for worker-supported vs local render.
- Keep Shell VM-backed apps under Shell lifecycle.
## Non-Goals
- Do not rename `AppMode::Game` to `Game2D` in this plan.
- Do not implement Game3D.
- Do not define Game pause/resume foreground stack; that belongs to `DSC-0041`.
## Execution Method
1. Locate `AppMode` routing through cartridge load, firmware state, SystemOS, and `RenderManager`.
2. Add a render policy enum or equivalent explicit matrix.
3. Route Game to frame-paced policy with optional worker capability.
4. Route Shell/system screens to local/synchronous lifecycle policy.
5. Add assertions/tests that Shell UI does not consume Game frame scheduler.
## Acceptance Criteria
- Policy is explicit and testable for Game and Shell.
- Shell UI remains local/synchronous by default.
- Game can declare worker-capable policy without requiring the worker to exist.
- Host/runtime capability fallback is represented without moving ownership decisions to host.
## Tests
- Unit tests for AppMode-to-render-policy mapping.
- Lifecycle test proving Shell does not require Game frame ticks.
- Regression test for Game still producing frame-paced submissions.
## Affected Artifacts
- `AppMode` routing modules.
- `RenderManager`.
- Firmware load/run steps.
- SystemOS lifecycle integration tests.
@@ -1,64 +0,0 @@
---
id: PLN-0092
ticket: vm-render-parallel-execution-boundary
title: Add Render Epoch Ownership Transitions
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, lifecycle, render-epoch, ownership]
---
## Briefing
`DEC-0031` requires foreground visual-owner transitions to invalidate stale render work using epoch/generation and owner identity.
## Objective
Add render epoch/ownership metadata and transition APIs so stale submissions cannot be presented after mode, app, crash, cartridge, or shutdown transitions.
## Dependencies
- Source decision: `DEC-0031`.
- `PLN-0089` provides the handoff abstraction.
## Scope
- Add epoch/generation and owner identity to render submission metadata.
- Add central `RenderManager` API for applying ownership transitions.
- Integrate lifecycle transitions that change visual owner.
- Reject stale pending/current submissions before present.
## Non-Goals
- Do not implement smooth visual transitions.
- Do not define Game pause/resume stack semantics from `DSC-0041`.
- Do not give host/HAL authority to decide ownership.
## Execution Method
1. Define render owner metadata shape: epoch/generation plus mode/app/surface owner as needed.
2. Extend `RenderSubmission` metadata and constructors.
3. Add `RenderManager` transition API that increments/applies epoch.
4. Call the API from SystemOS/firmware lifecycle transition points.
5. Update render consumption to check ownership before present.
6. Add discard telemetry hook for stale epoch.
## Acceptance Criteria
- Game -> Shell, Shell -> Game, crash, splash, cartridge/app swap, and shutdown can invalidate stale render work.
- Worker/current consumer cannot present a submission with stale epoch/owner.
- Host/HAL does not decide semantic ownership.
- Same physical surface can be reused with distinct logical ownership.
## Tests
- Unit test stale epoch discard before present.
- Integration test mode transition with pending Game submission.
- Test cartridge/app swap increments ownership even when AppMode remains unchanged.
## Affected Artifacts
- `RenderSubmission` metadata.
- `RenderManager`.
- Firmware/SystemOS transition code.
- Render publication path.
@@ -1,66 +0,0 @@
---
id: PLN-0093
ticket: vm-render-parallel-execution-boundary
title: Add Render Telemetry Counters and Events
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, telemetry, diagnostics]
---
## Briefing
`DEC-0031` requires render drops, repeats, stale discards, render errors, and present errors to be observable without becoming VM semantics.
## Objective
Add the minimum render telemetry surface required for asynchronous render diagnostics and certification.
## Dependencies
- Source decision: `DEC-0031`.
- `PLN-0089` and `PLN-0092` provide main event sources.
## Scope
- Add minimum counters and last-frame IDs from `DEC-0031`.
- Add event recording hooks for handoff, consume, present, repeat, stale discard, errors, and shutdown discard.
- Expose telemetry through existing runtime/host diagnostics patterns.
- Ensure VM program behavior cannot observe telemetry as render ACK.
## Non-Goals
- Do not build a UI profiler.
- Do not add VM syscalls for present ACK.
- Do not define host-specific logging formats beyond necessary hooks.
## Execution Method
1. Locate current telemetry facilities and atomic counter patterns.
2. Add render telemetry structure with counters and last IDs.
3. Wire replacement-before-consume from handoff.
4. Wire consumed/presented/repeated from consumer path.
5. Wire stale epoch and shutdown discards.
6. Wire render/present error reporting.
7. Add read-only diagnostics access for host/debug tooling.
## Acceptance Criteria
- All minimum counters and IDs from `DEC-0031` exist.
- Latest-wins replacement is measurable.
- Repeated presents and stale epoch discards are measurable.
- Telemetry is not a blocking ACK path for the VM.
## Tests
- Unit tests for counter increments.
- Handoff replacement telemetry test.
- Stale epoch discard telemetry test.
- Error path telemetry test where render/present errors can be simulated.
## Affected Artifacts
- Runtime telemetry modules.
- `RenderManager`.
- Render handoff and publication paths.
- Host/debug telemetry readers.
@@ -1,60 +0,0 @@
---
id: PLN-0094
ticket: vm-render-parallel-execution-boundary
title: Specify Async Render Boundary
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [spec, runtime, renderer, architecture]
---
## Briefing
`DEC-0031` needs canonical English spec coverage before worker-oriented code becomes normative.
## Objective
Publish the async render boundary contract in the canonical specs location.
## Dependencies
- Source decision: `DEC-0031`.
- Should run before large worker implementation plans are executed.
## Scope
- Add or update English spec text for packet completeness, handoff, pacing, AppMode policy, epoch ownership, and telemetry.
- Link the spec language to runtime concepts without exposing implementation-only details.
- Keep `DSC-0041` foreground stack details out of this spec pass except as explicit out-of-scope reference.
## Non-Goals
- Do not document future Game3D behavior beyond extensibility notes.
- Do not write lessons; lessons happen after execution.
- Do not encode implementation file paths as spec requirements.
## Execution Method
1. Locate canonical specs for runtime/render/AppMode.
2. Add a section for asynchronous render boundary or update the closest existing spec.
3. Translate normative parts of `DEC-0031` into concise English spec language.
4. Add out-of-scope note for Game pause/resume and VM-backed Shell coexistence under `DSC-0041`.
5. Cross-check terminology against existing specs.
## Acceptance Criteria
- Canonical specs describe the async render boundary in English.
- Spec language covers all seven decision areas.
- No Portuguese text is introduced in specs.
- The spec does not require worker implementation before the plan for it exists.
## Tests
- Documentation review.
- `rg` check for accidental Portuguese in touched spec files.
- Existing doc/spec validation scripts if present.
## Affected Artifacts
- Canonical specs location in the repository.
- `discussion/workflow/decisions/DEC-0031-vm-and-render-parallel-execution-boundary.md` as reference only.
@@ -1,66 +0,0 @@
---
id: PLN-0095
ticket: vm-render-parallel-execution-boundary
title: Prototype Local Render Worker Capability
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, host, renderer, worker, prototype]
---
## Briefing
`DEC-0031` allows Game pipelines to use a render worker when host/runtime capabilities support it, with local/synchronous fallback.
## Objective
Prototype the first local render worker capability behind the established handoff, policy, epoch, and telemetry contracts.
## Dependencies
- `PLN-0087` through `PLN-0093` should be complete or accepted as prerequisites.
- `PLN-0094` should publish the spec boundary before this becomes production work.
## Scope
- Add a host/runtime capability flag for render worker support.
- Spawn a local worker for Game policy only.
- Consume the single-slot handoff.
- Present at display cadence or the nearest available host cadence.
- Preserve synchronous/local fallback.
## Non-Goals
- Do not optimize performance beyond proving the contract.
- Do not enable Shell worker by default.
- Do not implement hardware-specific core/DMA behavior.
## Execution Method
1. Add capability wiring for worker-supported vs local render.
2. Create worker lifecycle owned by runtime/host integration according to `RenderManager` policy.
3. Make worker consume owned submissions through the handoff.
4. Check epoch/owner before present.
5. Emit telemetry for consume, present, repeat, stale discard, and errors.
6. Keep a build/runtime path that uses the existing synchronous renderer.
## Acceptance Criteria
- Game rendering can run through a local worker in a controlled configuration.
- Shell rendering remains local/synchronous by default.
- Worker does not access live mutable VM, `Hardware`, `Gfx`, or `FrameComposer` state outside approved boundaries.
- Fallback to synchronous/local render remains available.
## Tests
- Worker smoke test with Game submission.
- Fallback mode smoke test.
- Stale epoch discard test while worker is active.
- Thread shutdown test covered with `PLN-0096`.
## Affected Artifacts
- Host desktop runtime integration.
- `RenderManager`.
- Render handoff.
- Render backend/driver integration points.
@@ -1,70 +0,0 @@
---
id: PLN-0096
ticket: vm-render-parallel-execution-boundary
title: Define Render Shutdown and Failure Handling
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, shutdown, errors]
---
## Briefing
`DEC-0031` requires shutdown to stop obsolete presentation, discard pending/current work, and terminate worker execution in a bounded way. Worker panic must become controlled failure, not VM panic.
## Objective
Define and implement render shutdown, cancellation, and failure handling for both synchronous and worker-capable paths.
## Dependencies
- `PLN-0089` handoff abstraction.
- `PLN-0092` epoch/ownership transitions.
- `PLN-0093` telemetry.
- `PLN-0095` if a real worker is being exercised.
## Scope
- Add stop token or equivalent cancellation state for worker/current render work.
- Discard pending submissions on shutdown.
- Prevent obsolete current work from presenting after shutdown/owner change.
- Convert worker panic/render backend failure into controlled runtime/host error state.
- Record shutdown discards and errors in telemetry.
## Non-Goals
- Do not design full crash UI policy beyond render ownership requirements.
- Do not implement automatic worker restart unless existing host policy already supports it.
- Do not expose failure ACK to VM program semantics.
## Execution Method
1. Define shutdown state machine for render consumer.
2. Add bounded worker termination behavior where worker exists.
3. Add pending/current discard paths.
4. Ensure present path checks stop/epoch before publishing.
5. Wrap worker entrypoint with panic/error containment.
6. Add telemetry for shutdown discards, render errors, present errors, and worker failure.
## Acceptance Criteria
- Shutdown does not drain obsolete frames to screen.
- Pending work is discarded.
- Current work cannot present after stop/epoch invalidation.
- Worker failure is reported without panicking the VM.
- Shutdown completes in bounded time.
## Tests
- Unit test pending discard on shutdown.
- Integration test shutdown during currently-rendering submission.
- Simulated worker panic/error test.
- Telemetry assertions for shutdown/error counters.
## Affected Artifacts
- Render handoff.
- Worker runtime integration.
- `RenderManager`.
- Telemetry modules.
- Host error handling.
@@ -1,61 +0,0 @@
---
id: PLN-0097
ticket: vm-render-parallel-execution-boundary
title: Add Async Render Integration Test Matrix
status: done
created: 2026-06-05
ref_decisions: [DEC-0031]
tags: [runtime, renderer, tests, integration]
---
## Briefing
`DEC-0031` spans packet correctness, resource boundaries, handoff, pacing, AppMode policy, epoch ownership, telemetry, and failure behavior. These need integration coverage across plans.
## Objective
Create an integration test matrix that proves the async render boundary contracts work together and prevents regressions while plans are implemented incrementally.
## Dependencies
- Source decision: `DEC-0031`.
- This plan can start early as test scaffolding and expand as other plans land.
## Scope
- Define a test matrix mapping each `DEC-0031` invariant to at least one test.
- Add reusable fixtures for Game2D submissions, Shell UI submissions, stale epoch, handoff replacement, and frame repeat.
- Ensure tests run in local/synchronous mode and, when available, worker mode.
## Non-Goals
- Do not require real hardware backend.
- Do not require visual screenshot testing unless the existing test stack already supports it.
- Do not test `DSC-0041` foreground stack semantics.
## Execution Method
1. Build a matrix with rows for each decision invariant.
2. Identify existing tests that already cover rows.
3. Add missing tests as focused runtime/renderer integration tests.
4. Add helpers to construct deterministic submissions and resource IDs.
5. Run matrix in synchronous mode first.
6. Add worker-mode variants when `PLN-0095` exists.
## Acceptance Criteria
- Each `DEC-0031` invariant has at least one automated or explicitly documented validation.
- Test fixtures distinguish Game and Shell policies.
- Tests cover stale epoch discard, latest-wins replacement, repeated present, render error telemetry, and active-scene overlay.
- The matrix is referenced by later implementation plans.
## Tests
- This plan is itself test-focused.
- Required categories: packet composition, handoff, pacing, AppMode policy, epoch, telemetry, shutdown/failure.
## Affected Artifacts
- Runtime/renderer integration tests.
- Test fixtures/helpers.
- Any existing CI test grouping that needs to include the new tests.