prometeu-runtime/discussion/workflow/plans/PLN-0038-firmware-and-host-dependent-domain-coverage-expansion.md

id	ticket	title	status	created	completed	tags
PLN-0038	runtime-edge-test-plan	Plan - Firmware and Host-Dependent Domain Coverage Expansion	done	2026-04-20	2026-04-20	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.