VM and Render Parallel Execution Boundary
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user