[PERF] Host Debug Overlay Isolation
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
---
|
||||
id: PLN-0008
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: PR/Plan - Host Overlay Native Composition Alignment
|
||||
status: in_progress
|
||||
created: 2026-04-10
|
||||
completed:
|
||||
tags: [performance, host, gfx, telemetry]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Bring the desktop debug overlay implementation back into compliance with `DEC-0007`, `DEC-0009`, and `DEC-0010` by keeping the overlay in the host layer while rendering it in a dedicated host module and separate host layer, outside the emulated hardware framebuffer and outside `hardware.gfx`.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0007` requires the debug overlay to be a host-only layer composed after the emulated frame is complete. `DEC-0009` further clarifies that `fill_rect` and `draw_text` remain part of the emulated machine contract, but the host overlay must not depend on them and must live in a dedicated host module and separate host layer. `DEC-0010` fixes the semantics of the visible `LOGS` metric so the Host overlay reads the last completed frame value instead of a transient intra-frame counter.
|
||||
|
||||
The current `HostRunner` still calls `hardware.gfx.fill_rect()` and `hardware.gfx.draw_text()` for the overlay, which means the HUD is still being injected into the emulated graphics path even though its data source already comes from `AtomicTelemetry`.
|
||||
|
||||
`PLN-0007` completed the telemetry migration, so the remaining gap is no longer data access. The remaining gap is presentation architecture in the desktop host.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Remove all overlay rendering calls that write through `hardware.gfx`.
|
||||
- Introduce a desktop-host-native overlay composition path in `prometeu-host-desktop-winit`.
|
||||
- Implement the overlay in a dedicated host module instead of ad hoc logic inside `runner.rs`.
|
||||
- Keep overlay visibility and lifecycle fully controlled by the desktop host.
|
||||
- Continue reading inspection data through `AtomicTelemetry::snapshot()` and host-side log access.
|
||||
- Expose `LOGS` to the overlay as the last completed logical frame value.
|
||||
- Update runtime specifications so they explicitly state that the overlay is host-native and not part of the emulated machine framebuffer.
|
||||
- Add verification that enabling the overlay does not mutate emulated pixels.
|
||||
|
||||
### Excluded
|
||||
- Adding overlays to non-desktop hosts.
|
||||
- Reopening the telemetry model or changing `TelemetryFrame` semantics.
|
||||
- Reworking unrelated presentation, frame pacing, debugger transport, or certification behavior.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Extract overlay responsibilities into a dedicated host module
|
||||
|
||||
**What:**
|
||||
Move overlay formatting, layout, and drawing responsibilities out of `runner.rs` and into a dedicated host module.
|
||||
|
||||
**How:**
|
||||
Create a dedicated module such as `overlay.rs` that owns host overlay data preparation, panel layout, simple bars, and text rendering. `runner.rs` should orchestrate visibility and presentation only. The new module must never call emulated graphics primitives.
|
||||
|
||||
**File(s):**
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/stats.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
|
||||
### Step 2 - Compose the overlay in a separate host layer
|
||||
|
||||
**What:**
|
||||
Ensure the overlay is rendered in a separate host layer/surface and never blitted into the emulated framebuffer.
|
||||
|
||||
**How:**
|
||||
Preserve the `F1` toggle in `HostRunner`, keep telemetry reads on the host side, and present the overlay after the emulated frame is already ready for display. The implementation may transport the emulated framebuffer into the host presentation surface, but the overlay must remain a separate host composition step and must not write back into `hardware.gfx`.
|
||||
|
||||
**File(s):**
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
|
||||
### Step 3 - Add regression coverage for framebuffer purity
|
||||
|
||||
**What:**
|
||||
Add tests or deterministic checks that prove the overlay no longer modifies emulated graphics output.
|
||||
|
||||
**How:**
|
||||
Cover the overlay toggle and composition boundary with focused host tests where practical. At minimum, add a test seam or helper that lets the host render path be exercised without requiring overlay drawing through `hardware.gfx`. If a full automated framebuffer assertion is not practical yet, add a narrow unit test around the new composition entry point plus manual verification instructions that compare raw emulated output with overlay enabled and disabled.
|
||||
|
||||
**File(s):**
|
||||
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/tests.rs` or existing test module location
|
||||
|
||||
### Step 4 - Align log metric semantics with frame-end snapshots
|
||||
|
||||
**What:**
|
||||
Ensure the visible `LOGS` metric represents the last completed frame instead of a transient in-flight counter.
|
||||
|
||||
**How:**
|
||||
Persist the completed-frame log count into `AtomicTelemetry` before resetting the transient `LogService` counter. Keep certification evaluation and host overlay consumption aligned on that persisted frame-end value.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/log/log_service.rs`
|
||||
- `crates/console/prometeu-hal/src/telemetry.rs`
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
||||
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
|
||||
### Step 5 - Update normative documentation
|
||||
|
||||
**What:**
|
||||
Align specs and workflow artifacts with the corrected execution path.
|
||||
|
||||
**How:**
|
||||
Update the runtime debug and portability specifications to explicitly say the overlay is desktop-host-native, post-upscaling, and outside the emulated framebuffer. Keep the discussion workflow aligned by referencing this corrective plan during execution and closure.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
||||
- `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Host overlay toggle logic remains host-owned and does not require `hardware.gfx` text drawing.
|
||||
- New host-native overlay composition entry point can format and present telemetry without mutating the emulated framebuffer abstraction.
|
||||
- Simple bars and text layout are owned by the dedicated host overlay module.
|
||||
|
||||
### Integration Tests
|
||||
- `cargo check` for `prometeu-host-desktop-winit`, `prometeu-system`, and any touched supporting crate.
|
||||
- If automated host rendering tests are feasible, verify an emulated frame buffer dump is identical with overlay off and overlay on before the host-only composition stage.
|
||||
|
||||
### Manual Verification
|
||||
- Run the desktop host, toggle `F1`, and confirm the overlay appears and disappears correctly.
|
||||
- Capture or inspect the emulated framebuffer path and confirm no HUD pixels are written into machine output.
|
||||
- Confirm telemetry values still update through `AtomicTelemetry`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] No desktop overlay code writes through `hardware.gfx.fill_rect`, `hardware.gfx.draw_text`, or equivalent emulated-machine drawing APIs.
|
||||
- [ ] `fill_rect` and `draw_text` remain intact as part of the emulated graphics contract and are not repurposed for host overlay rendering.
|
||||
- [ ] The desktop overlay remains controlled by `HostRunner` and uses host-side telemetry snapshots.
|
||||
- [ ] The visible overlay is composed in a separate host layer after the emulated frame and is not burned into the emulated framebuffer.
|
||||
- [ ] Runtime telemetry remains gated by inspection state and continues to function for overlay consumption.
|
||||
- [ ] The visible `LOGS` metric represents the last completed logical frame.
|
||||
- [ ] Specs describe the overlay as host-native and outside the emulated hardware contract.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0007` accepted and unchanged.
|
||||
- `DEC-0008` accepted and unchanged.
|
||||
- `DEC-0009` accepted and unchanged.
|
||||
- `DEC-0010` accepted and unchanged.
|
||||
- Existing `AtomicTelemetry` host snapshot path remains available.
|
||||
|
||||
## Risks
|
||||
|
||||
- Desktop-native text and alpha composition may require extra host rendering plumbing that is more complex than the previous `hardware.gfx` path.
|
||||
- Without an explicit test seam, it is easy to accidentally reintroduce overlay writes into the emulated graphics path during future host refactors.
|
||||
- Host composition cost may rise slightly, but that cost is acceptable as long as it remains outside runtime cycle accounting.
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
id: PLN-0010
|
||||
ticket: generic-memory-bank-slot-contract
|
||||
title: PR/Plan - Asset Manager Bank Telemetry Slot Contract
|
||||
status: open
|
||||
created: 2026-04-10
|
||||
completed:
|
||||
tags: [runtime, asset, memory-bank, slots, host, telemetry]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the `DEC-0012` bank telemetry contract so `AssetManager` exposes slot-based bank summaries using canonical bank names `GLYPH` and `SOUND`, while host overlay and certification consume slot-based limits instead of byte-based bank metrics.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0012` locked the bank telemetry contract around a simple slot-first structure:
|
||||
|
||||
```rust
|
||||
pub struct BankTelemetry {
|
||||
pub bank_type: BankType,
|
||||
pub used_slots: usize,
|
||||
pub total_slots: usize,
|
||||
}
|
||||
```
|
||||
|
||||
This replaces the old bank telemetry path that relied on byte-oriented structures and presentation aliases. The implementation must remove `BankPolicy` and `BankStats` from the exposed bank telemetry contract path, move visible bank summaries to `AssetManager`, and migrate certification rules from byte-based thresholds to slot-based thresholds.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Add a visible slot-based `BankTelemetry` contract owned by `AssetManager`.
|
||||
- Remove `BankStats` from the public bank telemetry contract path.
|
||||
- Remove `BankPolicy` from the bank telemetry contract path and refactor internal code accordingly.
|
||||
- Update bridge/consumer APIs so bank summaries come from `AssetManager` slot telemetry.
|
||||
- Migrate certification from `max_gfx_bytes` / `max_audio_bytes` to slot-based limits for `GLYPH` and `SOUND`.
|
||||
- Update host overlay to iterate `AssetManager` bank telemetry using canonical `GLYPH` and `SOUND` labels.
|
||||
- Update specs/docs affected by the contract change.
|
||||
|
||||
### Excluded
|
||||
- Adding new bank kinds beyond the currently supported `GLYPH` and `SOUND`.
|
||||
- Reworking unrelated asset load/commit semantics.
|
||||
- Redesigning generic slot-detail payloads beyond the accepted summary shape unless implementation requires a narrowly scoped helper.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Introduce `BankTelemetry` in the exposed asset contract
|
||||
|
||||
**What:**
|
||||
Define the new slot-based summary type and make it the canonical visible representation of bank telemetry.
|
||||
|
||||
**How:**
|
||||
Add `BankTelemetry` to the HAL asset domain and ensure canonical naming uses `GLYPH` and `SOUND`. Remove or deprecate exposed `BankStats` paths that conflict with the new contract.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/asset.rs`
|
||||
- `crates/console/prometeu-hal/src/asset_bridge.rs`
|
||||
|
||||
### Step 2 - Make `AssetManager` expose bank telemetry directly
|
||||
|
||||
**What:**
|
||||
Implement `AssetManager` support for returning `Vec<BankTelemetry>` from live slot occupancy.
|
||||
|
||||
**How:**
|
||||
Compute `used_slots` from current slot occupancy and `total_slots` from the fixed slot arrays for `GLYPH` and `SOUND`. Keep implementation simple and derive the summary directly from the installed slots. Refactor any existing public bank-info consumers away from byte-oriented APIs.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- `crates/console/prometeu-drivers/src/memory_banks.rs`
|
||||
|
||||
### Step 3 - Remove byte-based bank certification rules
|
||||
|
||||
**What:**
|
||||
Replace byte-based certification limits for banks with slot-based limits.
|
||||
|
||||
**How:**
|
||||
Remove `max_gfx_bytes` and `max_audio_bytes` from certification config and certifier checks. Introduce slot-based limits such as `max_glyph_slots_used` and `max_sound_slots_used`, and evaluate them against `BankTelemetry` summaries or equivalent slot-based data available at frame-end.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-hal/src/telemetry.rs`
|
||||
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
||||
|
||||
### Step 4 - Update host overlay to consume slot telemetry
|
||||
|
||||
**What:**
|
||||
Replace hardcoded bank presentation with iteration over `AssetManager` bank telemetry.
|
||||
|
||||
**How:**
|
||||
Render one bar per bank using `bank_type`, `used_slots`, and `total_slots`. Use canonical labels `GLYPH` and `SOUND`, and remove any byte-based bank presentation from the overlay.
|
||||
|
||||
**File(s):**
|
||||
- `crates/host/prometeu-host-desktop-winit/src/overlay.rs`
|
||||
- Any host-side adapter/helper used to access asset telemetry
|
||||
|
||||
### Step 5 - Remove obsolete structures from the contract path
|
||||
|
||||
**What:**
|
||||
Eliminate `BankPolicy` and `BankStats` from the exposed bank telemetry path.
|
||||
|
||||
**How:**
|
||||
Refactor code so the new slot-based path is the only public contract. If internal implementation helpers must remain temporarily during migration, keep them private and make sure no consumer depends on them as contract.
|
||||
|
||||
**File(s):**
|
||||
- `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- `crates/console/prometeu-hal/src/asset.rs`
|
||||
- Related callers revealed during implementation
|
||||
|
||||
### Step 6 - Update normative documentation
|
||||
|
||||
**What:**
|
||||
Align specifications with the new slot-based bank telemetry contract.
|
||||
|
||||
**How:**
|
||||
Update relevant runtime documentation to describe bank occupancy in terms of `GLYPH` and `SOUND` slot usage, and remove outdated references to byte-based bank telemetry where they were treated as visible contract.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- Any additional touched runtime spec chapter
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- `AssetManager` reports correct `BankTelemetry` for empty and occupied `GLYPH` / `SOUND` slots.
|
||||
- Certification slot limits trigger correctly for `GLYPH` and `SOUND`.
|
||||
- Overlay rendering accepts generic bank telemetry iteration.
|
||||
|
||||
### Integration Tests
|
||||
- `cargo check` for affected HAL, drivers, system, and host crates.
|
||||
- Focused tests for asset bank telemetry and certification migration.
|
||||
|
||||
### Manual Verification
|
||||
- Run the desktop host and confirm banks appear as `GLYPH` and `SOUND`.
|
||||
- Confirm bank bars track occupied slots instead of bytes.
|
||||
- Confirm certification behavior still reports bank pressure using slot limits.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `AssetManager` exposes a visible `BankTelemetry` summary with `bank_type`, `used_slots`, and `total_slots`.
|
||||
- [ ] Canonical bank names in the new contract are `GLYPH` and `SOUND`.
|
||||
- [ ] Byte-based bank certification limits are removed and replaced by slot-based limits.
|
||||
- [ ] Host overlay renders bank occupancy from generic slot telemetry rather than byte-oriented hardcoded bank logic.
|
||||
- [ ] `BankPolicy` and `BankStats` are no longer part of the exposed bank telemetry contract path.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `DEC-0012` accepted and unchanged.
|
||||
|
||||
## Risks
|
||||
|
||||
- Removing byte-based bank paths may have wider ripple effects than expected if old APIs are reused outside the overlay.
|
||||
- The line between “removed from contract path” and “removed completely from implementation” must stay explicit during refactor to avoid accidental partial migration.
|
||||
- Certification migration must stay synchronized with telemetry migration or the host and certifier will diverge semantically.
|
||||
Reference in New Issue
Block a user