diff --git a/discussion/index.ndjson b/discussion/index.ndjson index 9794dfd3..aef7f6c9 100644 --- a/discussion/index.ndjson +++ b/discussion/index.ndjson @@ -1,8 +1,8 @@ -{"type":"meta","next_id":{"DSC":43,"AGD":44,"DEC":34,"PLN":110,"LSN":49,"CLSN":1}} +{"type":"meta","next_id":{"DSC":43,"AGD":44,"DEC":34,"PLN":122,"LSN":49,"CLSN":1}} {"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."} {"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]} {"type":"discussion","id":"DSC-0041","status":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]} -{"type":"discussion","id":"DSC-0042","status":"in_progress","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-15","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[{"id":"AGD-0042","file":"AGD-0042-host-hardware-render-boundary-preparation.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-06"},{"id":"AGD-0043","file":"AGD-0043-real-render-worker-establishment.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-15"}],"decisions":[{"id":"DEC-0032","file":"DEC-0032-platform-layer-and-hardwarebridge-elimination.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-06","ref_agenda":"AGD-0042"},{"id":"DEC-0033","file":"DEC-0033-real-render-worker-contract.md","status":"accepted","created_at":"2026-06-15","updated_at":"2026-06-15","ref_agenda":"AGD-0043"}],"plans":[{"id":"PLN-0098","file":"PLN-0098-define-platform-facade-contracts.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0099","file":"PLN-0099-introduce-owned-render-submission-sink.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0100","file":"PLN-0100-migrate-local-render-publication-to-sink.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0101","file":"PLN-0101-remove-immediate-gfx-syscall-rendering.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0102","file":"PLN-0102-introduce-game2d-frame-composer-service.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0103","file":"PLN-0103-introduce-runtime-platform-and-testplatform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0104","file":"PLN-0104-migrate-vm-runtime-hostcontext-to-platform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0105","file":"PLN-0105-migrate-firmware-and-hub-to-platform-services.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0106","file":"PLN-0106-migrate-desktop-host-to-platform-services.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0107","file":"PLN-0107-migrate-remaining-platform-domains.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0108","file":"PLN-0108-migrate-tests-to-testplatform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0109","file":"PLN-0109-remove-hardwarebridge-and-update-specs.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]}],"lessons":[]} +{"type":"discussion","id":"DSC-0042","status":"in_progress","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-15","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[{"id":"AGD-0042","file":"AGD-0042-host-hardware-render-boundary-preparation.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-06"},{"id":"AGD-0043","file":"AGD-0043-real-render-worker-establishment.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-15"}],"decisions":[{"id":"DEC-0032","file":"DEC-0032-platform-layer-and-hardwarebridge-elimination.md","status":"accepted","created_at":"2026-06-06","updated_at":"2026-06-06","ref_agenda":"AGD-0042"},{"id":"DEC-0033","file":"DEC-0033-real-render-worker-contract.md","status":"accepted","created_at":"2026-06-15","updated_at":"2026-06-15","ref_agenda":"AGD-0043"}],"plans":[{"id":"PLN-0098","file":"PLN-0098-define-platform-facade-contracts.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0099","file":"PLN-0099-introduce-owned-render-submission-sink.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0100","file":"PLN-0100-migrate-local-render-publication-to-sink.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0101","file":"PLN-0101-remove-immediate-gfx-syscall-rendering.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0102","file":"PLN-0102-introduce-game2d-frame-composer-service.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0103","file":"PLN-0103-introduce-runtime-platform-and-testplatform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0104","file":"PLN-0104-migrate-vm-runtime-hostcontext-to-platform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0105","file":"PLN-0105-migrate-firmware-and-hub-to-platform-services.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0106","file":"PLN-0106-migrate-desktop-host-to-platform-services.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0107","file":"PLN-0107-migrate-remaining-platform-domains.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0108","file":"PLN-0108-migrate-tests-to-testplatform.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0109","file":"PLN-0109-remove-hardwarebridge-and-update-specs.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-15","ref_decisions":["DEC-0032"]},{"id":"PLN-0110","file":"PLN-0110-define-owned-rgba8888-frame-contract.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0111","file":"PLN-0111-define-read-only-render-resource-access.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0112","file":"PLN-0112-define-render-worker-errors-and-telemetry.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0113","file":"PLN-0113-implement-thread-safe-latest-wins-handoff.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0114","file":"PLN-0114-add-deterministic-render-worker-test-harness.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0115","file":"PLN-0115-implement-render-worker-controller-lifecycle.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0116","file":"PLN-0116-implement-fake-local-render-backend.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0117","file":"PLN-0117-integrate-runtime-submission-with-worker.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0118","file":"PLN-0118-add-stale-epoch-and-repeat-frame-behavior.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0119","file":"PLN-0119-integrate-desktop-host-worker-presentation.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0120","file":"PLN-0120-update-real-render-worker-specs.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]},{"id":"PLN-0121","file":"PLN-0121-final-worker-path-validation-and-hardening.md","status":"open","created_at":"2026-06-15","updated_at":"2026-06-15","ref_decisions":["DEC-0033"]}],"lessons":[]} {"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]} {"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} {"type":"discussion","id":"DSC-0034","status":"done","ticket":"system-os-domain-facades","title":"Agenda - SystemOS Domain Facades","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","services","api-surface","lifecycle","fs"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0034-system-os-domain-facades/LSN-0043-systemos-domain-facades.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]} diff --git a/discussion/workflow/decisions/DEC-0033-real-render-worker-contract.md b/discussion/workflow/decisions/DEC-0033-real-render-worker-contract.md index 59cbe397..9d24b9f4 100644 --- a/discussion/workflow/decisions/DEC-0033-real-render-worker-contract.md +++ b/discussion/workflow/decisions/DEC-0033-real-render-worker-contract.md @@ -6,7 +6,7 @@ status: accepted created: 2026-06-15 accepted: agenda: AGD-0043 -plans: [] +plans: [PLN-0110, PLN-0111, PLN-0112, PLN-0113, PLN-0114, PLN-0115, PLN-0116, PLN-0117, PLN-0118, PLN-0119, PLN-0120, PLN-0121] tags: [runtime, renderer, worker, concurrency, host, hal, architecture] --- diff --git a/discussion/workflow/plans/PLN-0110-define-owned-rgba8888-frame-contract.md b/discussion/workflow/plans/PLN-0110-define-owned-rgba8888-frame-contract.md new file mode 100644 index 00000000..8cffebcb --- /dev/null +++ b/discussion/workflow/plans/PLN-0110-define-owned-rgba8888-frame-contract.md @@ -0,0 +1,79 @@ +--- +id: PLN-0110 +ticket: real-render-worker-establishment +title: Define Owned RGBA8888 Frame Contract +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, hal, frame-contract] +--- + +## Briefing + +`DEC-0033` requires the worker to publish an owned RGBA8888 frame that is independent of native window APIs. This plan defines that shared HAL contract before any worker implementation depends on it. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Introduce `OwnedRgba8888Frame` in `prometeu-hal` as the canonical worker-to-host published frame type. + +## Escopo + +- Add the shared frame type to HAL. +- Include frame id, ownership/epoch metadata, dimensions, stride, and owned `Vec` RGBA8888 pixels. +- Add constructors and validation helpers that keep dimensions, stride, and pixel length coherent. +- Add unit tests for layout and validation. + +## Fora de Escopo + +- No worker thread. +- No host upload/present integration. +- No resource bank access. +- No spec updates beyond code-facing rustdoc if useful. + +## Plano de Execucao + +### Step 1 - Add HAL frame module + +**What:** Add `OwnedRgba8888Frame`. +**How:** Create a HAL module, likely `crates/console/prometeu-hal/src/owned_frame.rs` or equivalent, and export it from `lib.rs`. +**File(s):** `crates/console/prometeu-hal/src/lib.rs`, new HAL frame module. + +### Step 2 - Define required fields + +**What:** Encode the DEC-0033 frame contract. +**How:** Include `FrameId`, render ownership/epoch metadata compatible with `RenderSubmission`, `width`, `height`, `stride_pixels`, and `pixels: Vec`. +**File(s):** HAL frame module, existing render ownership types if reuse is needed. + +### Step 3 - Add constructors and validation + +**What:** Prevent malformed frame buffers from entering the worker-host boundary. +**How:** Add checked constructor(s) that reject zero dimensions, too-small stride, and pixel buffers shorter than `stride_pixels * height`. +**File(s):** HAL frame module. + +### Step 4 - Add tests + +**What:** Pin layout semantics. +**How:** Test valid construction, invalid stride, invalid pixel length, and that raw pixel values are preserved as RGBA8888 `u32`. +**File(s):** HAL frame module tests. + +## Criterios de Aceite + +- [ ] `OwnedRgba8888Frame` is exported by `prometeu-hal`. +- [ ] The type contains `FrameId`, ownership/epoch, width, height, `stride_pixels`, and `Vec` pixels. +- [ ] Invalid dimensions/stride/pixel length cannot be silently accepted by checked constructors. +- [ ] No native host/window/pixels/winit/SDL type appears in the HAL frame contract. + +## Tests / Validacao + +- `cargo test -p prometeu-hal` +- `rg "OwnedRgba8888Frame" crates/console/prometeu-hal -n` + +## Riscos + +- Reusing native pixel terminology could blur the logical RGBA8888 contract. +- Overfitting the frame type to current desktop upload code would leak host details into HAL. diff --git a/discussion/workflow/plans/PLN-0111-define-read-only-render-resource-access.md b/discussion/workflow/plans/PLN-0111-define-read-only-render-resource-access.md new file mode 100644 index 00000000..7d561d48 --- /dev/null +++ b/discussion/workflow/plans/PLN-0111-define-read-only-render-resource-access.md @@ -0,0 +1,79 @@ +--- +id: PLN-0111 +ticket: real-render-worker-establishment +title: Define Read-Only Render Resource Access +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, hal, resources] +--- + +## Briefing + +`DEC-0033` requires the worker backend to resolve render resources by stable ids through compact read-only access, without copying banks, snapshotting banks, requiring `Arc` in the public contract, or accessing mutable `Hardware`/`Gfx`/`FrameComposer`. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Define shared read-only render resource traits in HAL and implement them over existing local bank storage without changing bank ownership semantics. + +## Escopo + +- Define compact HAL traits for read-only glyph and scene bank access by id. +- Keep the public contract id-based and read-only. +- Implement the traits in the local driver/resource owner currently used by rendering. +- Add tests proving banks are read through the new interface. + +## Fora de Escopo + +- No worker thread. +- No bank copying or snapshotting. +- No public `Arc` requirement. +- No asset residency policy changes. + +## Plano de Execucao + +### Step 1 - Define HAL read-only traits + +**What:** Add worker-facing resource access contracts. +**How:** Define traits for resolving glyph and scene banks by stable ids. Return borrowed read-only references or compact read-only views, not mutable handles. +**File(s):** `crates/console/prometeu-hal/src/*`, likely a new render resource module. + +### Step 2 - Implement local resource access + +**What:** Expose current local bank storage through the new traits. +**How:** Implement the read-only traits for the existing memory bank/resource owner used by `prometeu-drivers`. +**File(s):** `crates/console/prometeu-drivers/src/memory_banks.rs`, `frame_composer.rs`, or adjacent resource modules. + +### Step 3 - Thread access through backend-facing APIs + +**What:** Make future backends able to receive resource access without `Hardware`. +**How:** Add narrow parameters/types where needed so a backend can be given read-only resources independently from the full platform. +**File(s):** HAL contracts and driver modules touched above. + +### Step 4 - Add resource access tests + +**What:** Prove id lookup and read-only behavior. +**How:** Add tests for resident/missing glyph and scene banks through the new traits and verify no mutable API is exposed. +**File(s):** HAL/driver tests. + +## Criterios de Aceite + +- [ ] Worker-facing render resource access is defined in `prometeu-hal`. +- [ ] Resource access is by stable id and read-only. +- [ ] The public contract does not require `Arc`, bank copies, bank snapshots, `Hardware`, `Gfx`, or `FrameComposer`. +- [ ] Local driver storage implements the traits. + +## Tests / Validacao + +- `cargo test -p prometeu-hal -p prometeu-drivers` +- `rg "Arc<.*RenderResource|snapshot.*bank|&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-drivers -n` + +## Riscos + +- Returning concrete bank internals may overexpose driver implementation. +- Accidentally requiring `Arc` in the trait would make a storage strategy part of the public contract. diff --git a/discussion/workflow/plans/PLN-0112-define-render-worker-errors-and-telemetry.md b/discussion/workflow/plans/PLN-0112-define-render-worker-errors-and-telemetry.md new file mode 100644 index 00000000..d9b498fa --- /dev/null +++ b/discussion/workflow/plans/PLN-0112-define-render-worker-errors-and-telemetry.md @@ -0,0 +1,78 @@ +--- +id: PLN-0112 +ticket: real-render-worker-establishment +title: Define Render Worker Errors and Telemetry +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, hal, telemetry] +--- + +## Briefing + +`DEC-0033` requires typed worker/backend errors and telemetry that observes worker behavior without changing VM semantics. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Introduce the shared error and telemetry vocabulary required by the real worker. + +## Escopo + +- Define `RenderWorkerError` or equivalent shared error type. +- Define worker telemetry counters/snapshot shape. +- Integrate the new telemetry shape with existing render telemetry types where appropriate. +- Add tests for error/debug/copy/equality behavior and telemetry defaults. + +## Fora de Escopo + +- No worker lifecycle implementation. +- No thread-safe handoff. +- No host integration. + +## Plano de Execucao + +### Step 1 - Add worker error type + +**What:** Define typed worker errors. +**How:** Add variants for backend unavailable, render failed, publish/present handoff failed, shutdown timeout, stale submission discarded, and worker panic/internal failure. +**File(s):** `crates/console/prometeu-hal/src/*` or `prometeu-system` if the type is not shared; prefer HAL if host/tests need it. + +### Step 2 - Add telemetry snapshot + +**What:** Define counters required by DEC-0033. +**How:** Include produced, replaced/dropped, consumed, published/presented, stale discarded, render failures, repeated frames, and shutdown timeouts. +**File(s):** existing telemetry/render manager modules or new worker telemetry module. + +### Step 3 - Preserve existing telemetry compatibility + +**What:** Avoid breaking existing render telemetry tests. +**How:** Map or extend current render telemetry without changing VM semantics or current counters unexpectedly. +**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`, HAL telemetry modules as needed. + +### Step 4 - Add tests + +**What:** Pin type behavior. +**How:** Test default zero telemetry, counter increments through helper methods if added, and error formatting/debug behavior. +**File(s):** HAL/system tests. + +## Criterios de Aceite + +- [ ] Worker/backend failure has a typed error surface. +- [ ] Telemetry includes all DEC-0033 minimum counters. +- [ ] Existing render telemetry tests still pass. +- [ ] No worker/backend failure path relies on panic as the normal reporting model. + +## Tests / Validacao + +- `cargo test -p prometeu-hal -p prometeu-system` +- `rg "RenderWorkerError|shutdown_timeout|stale.*discard|repeat" crates/console -n` + +## Riscos + +- Splitting telemetry between too many structs may make final worker accounting inconsistent. +- Adding errors before call sites exist may create unused-code warnings if not scoped carefully. diff --git a/discussion/workflow/plans/PLN-0113-implement-thread-safe-latest-wins-handoff.md b/discussion/workflow/plans/PLN-0113-implement-thread-safe-latest-wins-handoff.md new file mode 100644 index 00000000..adffc62c --- /dev/null +++ b/discussion/workflow/plans/PLN-0113-implement-thread-safe-latest-wins-handoff.md @@ -0,0 +1,80 @@ +--- +id: PLN-0113 +ticket: real-render-worker-establishment +title: Implement Thread-Safe Latest-Wins Handoff +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, concurrency, handoff] +--- + +## Briefing + +`DEC-0033` requires a thread-safe single-slot latest-wins handoff. The producer must replace pending work without waiting for rasterization or present, and the consumer must take ownership of the latest pending submission. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Add the real worker handoff primitive in `prometeu-system`, using explicit synchronization and deterministic tests. + +## Escopo + +- Implement a single-slot pending submission structure. +- Use `Mutex> + Condvar` or an equivalent explicit structure. +- Add producer publish/replace behavior and consumer wait/take behavior. +- Track replacement/drop telemetry. + +## Fora de Escopo + +- No worker thread controller lifecycle. +- No backend rendering. +- No host integration. +- No stale epoch publish behavior beyond storing ownership data already present in submissions. + +## Plano de Execucao + +### Step 1 - Add handoff module + +**What:** Create the worker handoff primitive. +**How:** Add a module under `crates/console/prometeu-system/src/services/vm_runtime/`, for example `render_worker_handoff.rs`. +**File(s):** new system module, `mod.rs` exports. + +### Step 2 - Implement publish replacement + +**What:** Producer publishes owned `RenderSubmission`. +**How:** Lock the slot, replace any pending submission, increment replacement/drop counters when applicable, notify the condvar, and return immediately. +**File(s):** handoff module. + +### Step 3 - Implement consumer wait/take + +**What:** Consumer waits for work or shutdown signal. +**How:** Add wait/take APIs that block only the consumer side and return owned submissions. +**File(s):** handoff module. + +### Step 4 - Add deterministic tests + +**What:** Prove latest-wins and blocking boundaries. +**How:** Use threads, barriers, and condvars to prove producer replacement and consumer wake behavior without sleeps. +**File(s):** handoff module tests or `async_render_contract_tests.rs`. + +## Criterios de Aceite + +- [ ] Producer publish does not wait for consumer rasterization. +- [ ] Multiple pending publishes leave only the newest submission available. +- [ ] Replacements increment telemetry. +- [ ] Consumer can wait for work and is woken by publish. +- [ ] Tests do not use sleep as their primary synchronization proof. + +## Tests / Validacao + +- `cargo test -p prometeu-system render_worker_handoff` +- `cargo test -p prometeu-system` + +## Riscos + +- Holding the mutex while doing heavy work would violate non-blocking producer behavior. +- Condvar wait loops must handle spurious wakeups. diff --git a/discussion/workflow/plans/PLN-0114-add-deterministic-render-worker-test-harness.md b/discussion/workflow/plans/PLN-0114-add-deterministic-render-worker-test-harness.md new file mode 100644 index 00000000..065b48f4 --- /dev/null +++ b/discussion/workflow/plans/PLN-0114-add-deterministic-render-worker-test-harness.md @@ -0,0 +1,78 @@ +--- +id: PLN-0114 +ticket: real-render-worker-establishment +title: Add Deterministic Render Worker Test Harness +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, tests, concurrency] +--- + +## Briefing + +`DEC-0033` requires worker behavior to be proven without a native window and without fragile sleeps. This plan creates reusable deterministic test fixtures for the remaining worker plans. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Add a fake backend and synchronization harness capable of blocking render at controlled points, observing publication, and proving non-blocking VM/producer behavior. + +## Escopo + +- Create test-only synchronization helpers using barriers/condvars. +- Create a fake render backend shape that can block/fail/publish deterministically. +- Add helper functions for constructing owned render submissions and frames. +- Reuse the harness in later worker tests. + +## Fora de Escopo + +- No production worker lifecycle. +- No desktop host integration. +- No real GFX rasterization. + +## Plano de Execucao + +### Step 1 - Add test support module + +**What:** Introduce deterministic worker test fixtures. +**How:** Add test-only helpers under `prometeu-system` worker tests or a local test module. +**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/*`. + +### Step 2 - Add controllable fake backend + +**What:** Provide backend behavior for tests. +**How:** Fake backend can block at render start, unblock by test signal, return errors, and record published frames. +**File(s):** worker test module. + +### Step 3 - Add submission/frame builders + +**What:** Make tests concise and consistent. +**How:** Build Game/Shell submissions with explicit frame ids and ownership metadata; build `OwnedRgba8888Frame` fixtures. +**File(s):** worker test module. + +### Step 4 - Add initial harness self-tests + +**What:** Prove harness itself is deterministic. +**How:** Verify a test can block and release backend render without timing sleeps. +**File(s):** worker test module. + +## Criterios de Aceite + +- [ ] Tests can block worker backend render using deterministic synchronization. +- [ ] Tests can observe published `OwnedRgba8888Frame` values. +- [ ] Harness can inject backend errors. +- [ ] Harness helpers are scoped to tests or clearly internal. + +## Tests / Validacao + +- `cargo test -p prometeu-system render_worker` +- `rg "sleep\\(|thread::sleep" crates/console/prometeu-system/src/services/vm_runtime -n` + +## Riscos + +- Test harness code can become too coupled to implementation internals. +- Overly broad helpers can hide important assertions in later plans. diff --git a/discussion/workflow/plans/PLN-0115-implement-render-worker-controller-lifecycle.md b/discussion/workflow/plans/PLN-0115-implement-render-worker-controller-lifecycle.md new file mode 100644 index 00000000..509fe667 --- /dev/null +++ b/discussion/workflow/plans/PLN-0115-implement-render-worker-controller-lifecycle.md @@ -0,0 +1,87 @@ +--- +id: PLN-0115 +ticket: real-render-worker-establishment +title: Implement Render Worker Controller Lifecycle +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, lifecycle, concurrency] +--- + +## Briefing + +`DEC-0033` requires a runtime-owned worker controller in `prometeu-system`, with stop signaling, bounded shutdown, pending/in-flight separation, typed errors, and telemetry. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Implement the production worker controller lifecycle around the handoff primitive and backend trait shape. + +## Escopo + +- Add worker controller type in `prometeu-system`. +- Spawn and join a worker thread. +- Add configurable shutdown timeout with initial default `250ms`. +- Add stop token/wakeup behavior. +- Preserve pending/in-flight separation. +- Capture panic as typed internal failure. + +## Fora de Escopo + +- No desktop host presentation. +- No full runtime tick integration. +- No stale epoch/repeat behavior beyond lifecycle foundations. + +## Plano de Execucao + +### Step 1 - Define controller and config + +**What:** Add worker controller and configuration. +**How:** Include shutdown timeout, default `250ms`, and hooks for backend and handoff dependencies. +**File(s):** new `render_worker.rs` or similar in `prometeu-system`. + +### Step 2 - Implement start and run loop + +**What:** Start worker execution. +**How:** Spawn a thread that waits on the handoff, takes submissions, marks in-flight locally, calls backend, and publishes results through a frame sink abstraction. +**File(s):** worker controller module. + +### Step 3 - Implement stop and bounded join + +**What:** Make shutdown observable and bounded. +**How:** Signal stop, wake the condvar, join with timeout strategy available in Rust implementation, and return/report `ShutdownTimeout` when exceeded. +**File(s):** worker controller module. + +### Step 4 - Add panic containment + +**What:** Convert worker panic into typed failure. +**How:** Use panic containment around backend calls or worker thread join result and update telemetry/errors. +**File(s):** worker controller module. + +### Step 5 - Add lifecycle tests + +**What:** Prove start/stop/join behavior. +**How:** Use deterministic harness from `PLN-0114`. +**File(s):** worker tests. + +## Criterios de Aceite + +- [ ] Worker controller lives in `prometeu-system`. +- [ ] Controller can start and stop a real worker thread. +- [ ] Shutdown wakes waiting worker and completes within configured bound in tests. +- [ ] Shutdown timeout is typed and observable. +- [ ] Worker panic is captured as typed internal failure. + +## Tests / Validacao + +- `cargo test -p prometeu-system render_worker` +- `cargo test -p prometeu-system` + +## Riscos + +- Rust thread join timeout requires careful design because standard `JoinHandle::join` has no timeout. +- Backend ownership must be `'static + Send` without leaking host-specific types into system contracts. diff --git a/discussion/workflow/plans/PLN-0116-implement-fake-local-render-backend.md b/discussion/workflow/plans/PLN-0116-implement-fake-local-render-backend.md new file mode 100644 index 00000000..f1c94e45 --- /dev/null +++ b/discussion/workflow/plans/PLN-0116-implement-fake-local-render-backend.md @@ -0,0 +1,78 @@ +--- +id: PLN-0116 +ticket: real-render-worker-establishment +title: Implement Fake Local Render Backend +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, backend, drivers] +--- + +## Briefing + +`DEC-0033` requires fake/local backend behavior before desktop integration so worker semantics can be proven without a window. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Implement backend contracts that consume `RenderSubmission` plus read-only resources and produce `OwnedRgba8888Frame`. + +## Escopo + +- Define or finalize a backend trait for worker rendering. +- Add a fake backend for deterministic tests. +- Add a local framebuffer backend that can rasterize through existing driver/GFX logic without exposing mutable `Hardware` as the worker contract. +- Verify output frame ownership and pixels. + +## Fora de Escopo + +- No desktop upload/present. +- No runtime tick integration. +- No resource mutation policy changes. + +## Plano de Execucao + +### Step 1 - Define backend trait + +**What:** Encode backend consumption contract. +**How:** Trait consumes `RenderSubmission` and read-only resource access and returns `OwnedRgba8888Frame` or `RenderWorkerError`. +**File(s):** HAL if shared, or system if internal; prefer HAL if host/drivers implement it. + +### Step 2 - Implement fake backend + +**What:** Provide test backend. +**How:** Fake backend returns deterministic frames, can block through harness, and can return typed errors. +**File(s):** system test module or driver test utility. + +### Step 3 - Implement local framebuffer backend + +**What:** Provide non-window raster backend. +**How:** Use existing GFX rendering internally to turn submissions into `OwnedRgba8888Frame`, but expose only the backend trait and read-only resources. +**File(s):** `prometeu-drivers` rendering modules, possibly a new backend module. + +### Step 4 - Add output tests + +**What:** Prove frame content and metadata. +**How:** Render simple Game2D and ShellUi submissions and compare `OwnedRgba8888Frame` pixels/metadata. +**File(s):** driver/system tests. + +## Criterios de Aceite + +- [ ] Backend trait does not expose mutable `Hardware`, `Gfx`, `FrameComposer`, or VM state. +- [ ] Fake backend supports deterministic blocking/error behavior. +- [ ] Local backend produces `OwnedRgba8888Frame`. +- [ ] Game2D and ShellUi submissions can produce frame output without a native window. + +## Tests / Validacao + +- `cargo test -p prometeu-drivers -p prometeu-system` +- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-hal crates/console/prometeu-system/src/services/vm_runtime -n` + +## Riscos + +- Local backend may be tempted to reuse `Hardware` directly as the public worker contract. +- Resource access gaps may surface when moving from fake to local rasterization. diff --git a/discussion/workflow/plans/PLN-0117-integrate-runtime-submission-with-worker.md b/discussion/workflow/plans/PLN-0117-integrate-runtime-submission-with-worker.md new file mode 100644 index 00000000..9fa5f8ea --- /dev/null +++ b/discussion/workflow/plans/PLN-0117-integrate-runtime-submission-with-worker.md @@ -0,0 +1,80 @@ +--- +id: PLN-0117 +ticket: real-render-worker-establishment +title: Integrate Runtime Submission With Worker +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, integration] +--- + +## Briefing + +`DEC-0033` requires VM/render production to submit work without blocking on worker consumption. This plan connects runtime frame closure to the worker handoff while preserving local synchronous fallback. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Route eligible Game render submissions from `RenderManager` into the real worker handoff and keep Shell/local paths correct. + +## Escopo + +- Add worker-capable runtime path. +- Submit owned `RenderSubmission` to the handoff. +- Preserve AppMode policy: Game may use worker; Shell remains local unless a future decision changes it. +- Keep local synchronous fallback. +- Prove VM tick returns without waiting for worker backend completion. + +## Fora de Escopo + +- No desktop host presentation. +- No final stale/repeat behavior beyond integration needed for basic worker use. +- No spec edits. + +## Plano de Execucao + +### Step 1 - Add worker ownership to runtime state + +**What:** Store worker controller/handoff in runtime-owned state. +**How:** Extend `VirtualMachineRuntime` or `RenderManager` integration points without moving policy to host. +**File(s):** `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, `render_manager.rs`, worker modules. + +### Step 2 - Submit Game frames to worker handoff + +**What:** Replace local worker prototype path with real worker submission. +**How:** On eligible Game frame closure, publish owned `RenderSubmission` into the handoff and return to VM tick without waiting for consumption. +**File(s):** runtime tick/render manager integration. + +### Step 3 - Preserve local fallback + +**What:** Keep current local synchronous behavior available. +**How:** Use existing `RenderConsumerPath`/policy or update it to select local fallback when worker is disabled/unavailable. +**File(s):** `render_manager.rs`, `tick.rs`. + +### Step 4 - Add non-blocking tests + +**What:** Prove VM producer does not block. +**How:** Use harness to hold backend render, run tick/publish additional frames, assert return and replacement telemetry. +**File(s):** runtime worker tests. + +## Criterios de Aceite + +- [ ] Game render submissions can be sent to the real worker handoff. +- [ ] VM tick does not wait for worker rasterization. +- [ ] Shell/local policy remains unchanged. +- [ ] Local synchronous fallback still passes existing tests. +- [ ] Replacement telemetry increments when producer outruns worker. + +## Tests / Validacao + +- `cargo test -p prometeu-system` +- `cargo test -p prometeu-firmware` + +## Riscos + +- Accidentally making frame closure wait for worker consumption would violate DEC-0033. +- Mixing Shell lifecycle rendering into the worker path too early would broaden scope. diff --git a/discussion/workflow/plans/PLN-0118-add-stale-epoch-and-repeat-frame-behavior.md b/discussion/workflow/plans/PLN-0118-add-stale-epoch-and-repeat-frame-behavior.md new file mode 100644 index 00000000..343ac32d --- /dev/null +++ b/discussion/workflow/plans/PLN-0118-add-stale-epoch-and-repeat-frame-behavior.md @@ -0,0 +1,85 @@ +--- +id: PLN-0118 +ticket: real-render-worker-establishment +title: Add Stale Epoch and Repeat Frame Behavior +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, ownership, telemetry] +--- + +## Briefing + +`DEC-0033` requires the worker to discard stale in-flight frames before publication and repeat the last published `OwnedRgba8888Frame` rather than recomposing. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Complete ownership/epoch checks and repeat-last-published-frame behavior for the worker path. + +## Escopo + +- Add shared active ownership/epoch observation for worker publication checks. +- Discard stale in-flight frames before publication. +- Store and expose the latest published `OwnedRgba8888Frame`. +- Implement repeat-last-frame behavior and telemetry. + +## Fora de Escopo + +- No desktop upload/present. +- No new AppMode policy. +- No native window invalidation changes. + +## Plano de Execucao + +### Step 1 - Expose ownership/epoch to worker + +**What:** Let worker validate in-flight submissions before publishing. +**How:** Add a thread-safe snapshot or handle that the worker can read without mutating runtime state. +**File(s):** `render_manager.rs`, worker modules. + +### Step 2 - Implement stale discard + +**What:** Prevent stale pixels from publication. +**How:** Before publishing frame output, compare submission ownership/epoch with active ownership/epoch; discard on mismatch and increment telemetry. +**File(s):** worker controller module. + +### Step 3 - Store latest published frame + +**What:** Make the latest valid frame available to host/fallback tests. +**How:** Add a published-frame slot distinct from pending submission and in-flight work. +**File(s):** worker controller or published frame module. + +### Step 4 - Implement repeat behavior + +**What:** Repeat last valid frame without recomposition. +**How:** Add API to fetch/reuse the latest published `OwnedRgba8888Frame`; increment repeat telemetry when cadence requests reuse. +**File(s):** worker modules, tests. + +### Step 5 - Add tests + +**What:** Prove stale discard and repeat. +**How:** Use harness to hold in-flight work, change owner/epoch, release backend, and assert no publication; separately assert repeat returns last frame. +**File(s):** worker tests. + +## Criterios de Aceite + +- [ ] Worker checks active owner/epoch before publishing. +- [ ] Stale in-flight frames are discarded and counted. +- [ ] Latest published frame is an `OwnedRgba8888Frame`. +- [ ] Repeat uses the last published frame and does not recompose. +- [ ] Tests cover stale discard and repeat deterministically. + +## Tests / Validacao + +- `cargo test -p prometeu-system render_worker` +- `cargo test -p prometeu-system` + +## Riscos + +- Reading active ownership from the wrong layer may reintroduce mutable runtime coupling. +- Repeat behavior must not hide render failures unless telemetry records them. diff --git a/discussion/workflow/plans/PLN-0119-integrate-desktop-host-worker-presentation.md b/discussion/workflow/plans/PLN-0119-integrate-desktop-host-worker-presentation.md new file mode 100644 index 00000000..2c97edd8 --- /dev/null +++ b/discussion/workflow/plans/PLN-0119-integrate-desktop-host-worker-presentation.md @@ -0,0 +1,81 @@ +--- +id: PLN-0119 +ticket: real-render-worker-establishment +title: Integrate Desktop Host Worker Presentation +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, host, desktop] +--- + +## Briefing + +`DEC-0033` is not complete until the real host path uses the worker. This plan integrates desktop presentation with the latest published `OwnedRgba8888Frame` while keeping native upload/present in the host event loop. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Make `prometeu-host-desktop-winit` present frames produced by the worker path. + +## Escopo + +- Wire the host to enable/use the worker path. +- Read the latest published `OwnedRgba8888Frame`. +- Upload/copy RGBA8888 pixels to the existing pixels/winit presentation surface in the event loop. +- Preserve host invalidation and redraw behavior. +- Keep worker free of native window dependencies. + +## Fora de Escopo + +- No SDL migration. +- No change to logical pixel format. +- No change to input/audio/filesystem host behavior. + +## Plano de Execucao + +### Step 1 - Add host access to published frame + +**What:** Expose latest worker-published frame to desktop host. +**How:** Add an API through runtime/platform integration that returns or copies the latest `OwnedRgba8888Frame` for host upload. +**File(s):** system worker modules, host runner integration. + +### Step 2 - Upload RGBA8888 in event loop + +**What:** Present worker output through existing host surface. +**How:** Convert/copy `Vec` RGBA8888 into the existing pixels frame buffer using existing RGBA8888 utility conventions. +**File(s):** `crates/host/prometeu-host-desktop-winit/src/runner.rs`, `utilities.rs` if needed. + +### Step 3 - Preserve invalidation model + +**What:** Keep host redraw policy coherent. +**How:** Trigger redraw when a new frame is published or host invalidation occurs; repeat uses the last published frame. +**File(s):** host runner/presentation state. + +### Step 4 - Add host tests + +**What:** Prove host consumes worker-published frame. +**How:** Add unit tests for RGBA8888 copy/upload helper and presentation state transitions without opening a native window. +**File(s):** host tests. + +## Criterios de Aceite + +- [ ] Desktop host presents the latest worker-published `OwnedRgba8888Frame`. +- [ ] Worker code does not import winit, pixels, SDL, swapchain, native texture, or window APIs. +- [ ] Host event loop remains responsible for native present. +- [ ] Existing host invalidation tests still pass. +- [ ] Real host path can run with worker enabled. + +## Tests / Validacao + +- `cargo test -p prometeu-host-desktop-winit` +- `cargo test -p prometeu-system -p prometeu-firmware` +- Manual run of a simple cartridge through desktop host with worker path enabled. + +## Riscos + +- Upload/copy can accidentally reinterpret RGBA8888 as native endian bytes. +- Host redraw policy can regress into perpetual polling if publication/invalidation are not kept separate. diff --git a/discussion/workflow/plans/PLN-0120-update-real-render-worker-specs.md b/discussion/workflow/plans/PLN-0120-update-real-render-worker-specs.md new file mode 100644 index 00000000..b87f770e --- /dev/null +++ b/discussion/workflow/plans/PLN-0120-update-real-render-worker-specs.md @@ -0,0 +1,79 @@ +--- +id: PLN-0120 +ticket: real-render-worker-establishment +title: Update Real Render Worker Specs +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, specs] +--- + +## Briefing + +`DEC-0033` requires canonical runtime specs to document the real worker contract after implementation publishes the behavior. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Update English canonical specs to describe `OwnedRgba8888Frame`, worker handoff, host presentation split, read-only bank access, shutdown, errors, and telemetry. + +## Escopo + +- Update GFX/render specs. +- Update portability/host presentation specs. +- Update host ABI/syscall specs if worker behavior affects published runtime surfaces. +- Ensure no spec says the worker owns native window present. + +## Fora de Escopo + +- No new architecture beyond `DEC-0033`. +- No lesson writing. +- No implementation changes except documentation. + +## Plano de Execucao + +### Step 1 - Update GFX spec + +**What:** Document worker frame publication. +**How:** Add `OwnedRgba8888Frame`, RGBA8888 `Vec` semantics, latest published frame, and repeat behavior. +**File(s):** `docs/specs/runtime/04-gfx-peripheral.md`. + +### Step 2 - Update portability spec + +**What:** Document worker/host split. +**How:** State that worker produces owned RGBA8888 frames and host event loop performs native upload/present. +**File(s):** `docs/specs/runtime/11-portability-and-cross-platform-execution.md`. + +### Step 3 - Update concurrency/events spec if needed + +**What:** Document handoff and shutdown behavior. +**How:** Add single-slot latest-wins, bounded shutdown, and non-blocking producer semantics where concurrency is specified. +**File(s):** `docs/specs/runtime/09-events-and-concurrency.md` or adjacent runtime spec. + +### Step 4 - Update README/index references + +**What:** Keep spec map discoverable. +**How:** Add any needed cross-reference to worker/render sections. +**File(s):** `docs/specs/runtime/README.md`. + +## Criterios de Aceite + +- [ ] Specs define `OwnedRgba8888Frame`. +- [ ] Specs state worker does not own native window present. +- [ ] Specs state producer does not block on worker rasterization/present. +- [ ] Specs document read-only bank access by id. +- [ ] Specs document bounded shutdown and typed error expectations. + +## Tests / Validacao + +- `rg "OwnedRgba8888Frame|latest-wins|shutdown|read-only" docs/specs/runtime -n` +- `discussion validate` + +## Riscos + +- Updating specs before implementation may accidentally publish intent as completed behavior; execute after code plans that establish the behavior. +- Spec wording must remain English and normative. diff --git a/discussion/workflow/plans/PLN-0121-final-worker-path-validation-and-hardening.md b/discussion/workflow/plans/PLN-0121-final-worker-path-validation-and-hardening.md new file mode 100644 index 00000000..40fa25cf --- /dev/null +++ b/discussion/workflow/plans/PLN-0121-final-worker-path-validation-and-hardening.md @@ -0,0 +1,93 @@ +--- +id: PLN-0121 +ticket: real-render-worker-establishment +title: Final Worker Path Validation and Hardening +status: open +created: 2026-06-15 +completed: +ref_decisions: [DEC-0033] +tags: [runtime, renderer, worker, validation, hardening] +--- + +## Briefing + +`DEC-0033` is complete only when the worker functions on the real host path and the contract is proven end to end. This plan performs final validation, residue scans, and hardening before housekeeping. + +## Decisions de Origem + +- `DEC-0033`: Real Render Worker Contract. + +## Alvo + +Prove the real render worker path satisfies DEC-0033 across HAL, system, drivers, firmware, host, specs, and tests. + +## Escopo + +- Run broad test suites. +- Add missing edge tests found during validation. +- Scan for forbidden coupling. +- Verify host real path uses worker. +- Verify local fallback still works. +- Prepare evidence for discussion housekeeping. + +## Fora de Escopo + +- No new worker architecture. +- No SDL migration. +- No unrelated performance tuning. + +## Plano de Execucao + +### Step 1 - Run full affected test suite + +**What:** Validate all touched crates. +**How:** Run workspace tests and focused worker/host tests. +**File(s):** repository root. + +### Step 2 - Run coupling residue scans + +**What:** Enforce DEC-0033 boundaries. +**How:** Search worker/system/HAL code for native window dependencies, mutable hardware/GFX/composer leaks, bank copying/snapshot terminology, and sleeps in concurrency tests. +**File(s):** repository root. + +### Step 3 - Add missing hardening tests + +**What:** Close any discovered gaps. +**How:** Add focused tests for missing telemetry/error/shutdown/host-path cases. +**File(s):** affected test modules. + +### Step 4 - Verify host path + +**What:** Prove desktop host uses worker output. +**How:** Run host tests and a manual/simple cartridge path with worker enabled; record evidence in final summary. +**File(s):** host runner and runtime integration. + +### Step 5 - Prepare housekeeping evidence + +**What:** Make `DSC-0042` ready for final lesson/housekeeping. +**How:** Record completed plan state and validation evidence for later `discussion-housekeep`. +**File(s):** discussion artifacts if needed. + +## Criterios de Aceite + +- [ ] `cargo test --workspace` passes. +- [ ] Focused worker, system, drivers, firmware, and host tests pass. +- [ ] Residue scans show worker code does not depend on native window APIs. +- [ ] Residue scans show worker boundary does not expose `&mut Hardware`, `&mut Gfx`, live `FrameComposer`, or mutable VM state. +- [ ] Desktop host path uses the real worker output. +- [ ] Local fallback still works. +- [ ] `discussion validate` passes. + +## Tests / Validacao + +- `cargo test --workspace` +- `cargo test -p prometeu-system -p prometeu-drivers -p prometeu-hal -p prometeu-firmware -p prometeu-host-desktop-winit` +- `discussion validate` +- `rg "winit|pixels|SDL|swapchain|native texture" crates/console/prometeu-system crates/console/prometeu-hal -n` +- `rg "&mut Hardware|&mut Gfx|FrameComposer" crates/console/prometeu-system/src/services/vm_runtime crates/console/prometeu-hal -n` +- `rg "thread::sleep|sleep\\(" crates/console/prometeu-system/src/services/vm_runtime -n` + +## Riscos + +- Final validation may expose earlier plan gaps; fix them in the narrowest affected plan/module. +- Manual host evidence can be flaky if tied to native window availability; keep automated host-unit evidence as the primary gate.