---
id: PLN-0038
ticket: runtime-edge-test-plan
title: Plan - Firmware and Host-Dependent Domain Coverage Expansion
status: open
created: 2026-04-20
completed:
tags: [tests, firmware, host, coverage]
---

## Briefing

This plan executes the priority expansion areas mandated by `DEC-0020`: `firmware` and `host-dependent`.
The objective is not blanket test growth, but closing the most important domain gaps first.

## Decisions de Origem

- `DEC-0020`

## Alvo

Expand automated evidence for:

- firmware load and state-transition rules;
- `AppMode` branching;
- crash-path transitions from VM/runtime initialization and runtime execution;
- host-dependent desktop/debugger behaviors that legitimately require socket or window integration.

## Escopo

- Add or refine firmware tests in `prometeu-firmware`.
- Add or refine isolated host-dependent tests in the desktop host crate.
- Clarify which host behaviors must remain ignored/integration-style and which deterministic pieces should move below the host.

## Fora de Escopo

- Full test-tree reorganization across all runtime domains.
- Hard domain thresholds above baseline `0`.
- Reworking the public debugger protocol itself unless required by testability.

## Plano de Execucao

### Step 1 - Close firmware state-transition gaps

**What:**
Expand firmware coverage around canonical state behavior, not only isolated happy paths.

**How:**
Add tests around:

- `Reset` to boot-target-driven transitions;
- `LaunchHub` behavior for `BootTarget::Hub` versus `BootTarget::Cartridge`;
- `LoadCartridge` branch behavior for `AppMode::Game` versus `AppMode::System`;
- transition to `AppCrashes` when initialization or runtime execution fails.

**File(s):**
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_reset.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_launch_hub.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_load_cartridge.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
- `crates/console/prometeu-firmware/src/firmware/firmware_step_crash_screen.rs`

### Step 2 - Delimit host-dependent versus deterministic behavior

**What:**
Make the boundary between true host integration and lower-layer deterministic behavior explicit in tests.

**How:**
Review existing desktop-host tests and classify them:

- tests that truly require socket bind/connect or window integration remain host-dependent and may stay `#[ignore]`;
- deterministic logic should be covered in firmware/runtime/host-internal tests that do not require real integration.

**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`

### Step 3 - Strengthen the host-dependent suite without widening its scope

**What:**
Keep real integration tests focused on behaviors the lower layers cannot prove.

**How:**
Prioritize cases such as:

- debugger socket open/handshake lifecycle;
- reconnect/refuse-second-connection behavior;
- resume/pause/disconnect coordination when the real host wiring is part of the rule.

Avoid pushing general deterministic state logic into ignored desktop-only tests if it can be covered below the host.

**File(s):**
- `crates/host/prometeu-host-desktop-winit/src/runner.rs`
- `crates/host/prometeu-host-desktop-winit/src/debugger.rs`

### Step 4 - Capture evidence for the two priority domains

**What:**
Produce explicit review evidence showing that `firmware` and `host-dependent` are now governed domains rather than implied gaps.

**How:**
Use the governance helpers from `PLN-0037` if available, or temporary documented evidence if it lands first.

**File(s):**
- firmware and host test targets
- coverage/report artifacts as defined by the governance plan

## Criterios de Aceite

- [ ] Firmware has explicit automated coverage for boot-target transitions, `AppMode` branching, and crash-path transitions.
- [ ] Host-dependent tests are clearly limited to behaviors that genuinely require desktop/socket integration.
- [ ] Deterministic behavior that does not need real host integration is covered below the host when feasible.
- [ ] Review evidence can point to firmware and host-dependent coverage separately from the global aggregate.

## Tests / Validacao

### Unit / Integration

- Run `cargo test -p prometeu-firmware`.
- Run the relevant desktop host tests.

### Host-Dependent

- Run `cargo test -p prometeu-host-desktop-winit --lib -- --ignored`.

### Evidence

- Produce coverage evidence for touched firmware files and host-dependent integration paths.

## Riscos

- Adding host-only tests for behavior that belongs below the host boundary.
- Expanding firmware tests without aligning them to the state machine contract in the specs.
- Overfitting ignored integration tests to desktop timing details.