First-class application diagnostics adapters (RyuDeck baseline)

[deucebucket]

Goal

DeckDoc must diagnose the whole Steam Deck, including failures inside our own applications, without becoming part of those applications or treating an app symptom as a hardware verdict.

The first adapter is RyuDeck because it exposes structured runtime stages and progress telemetry. The adapter contract should be reusable for other first-party and supported third-party apps.

Failure boundary

Each adapter should distinguish:

1. intended production install/profile absent or duplicated;
2. app/process launch failure;
3. host initialization failure (renderer, audio, input, files/runtime);
4. workload/guest start failure;
5. active process with no progress;
6. active progress/rendering;
7. app/guest fatal, OOM, or renderer device loss;
8. downstream Gamescope/display/input/audio failure;
9. historical evidence versus a current live incident.

A running PID is not proof of progress, and a black screen is not proof of hardware failure.

RyuDeck baseline

The v3.4 work adds a privacy-safe ryudeck_app.sh module with:

• production install/profile and active-runtime state;
• firmware content count and runtime firmware version when available;
• emulation_running, bounded zero/nonzero FPS, and latest progress;
• PTC/shader/cache, background-pipeline, controller/input, and scheduler counters;
• renderer/device-loss, OOM, guest/process fatal classes;
• GUEST_STARTUP_STALL, STALE_TITLE_CACHE_SUSPECTED, ACTIVE_RUNTIME_LOG_STALLED, RENDERER_OR_PROCESS_FATAL, and RENDERING signatures;
• mocked absent, stall, cache, rendering, fatal, and privacy fixtures.

Privacy and safety requirements

Adapters must parse locally and emit minimized structured fields only. Reports must not include:

• titles or title IDs;
• usernames, home/library paths, filenames, or launch arguments;
• account, controller, friend, device, or console identifiers;
• tokens, keys, credentials, ROM/content inventory, screenshots, saves, or raw app-log lines.

The shared pre-write filter remains a second boundary. Cache/config tests must be advisory, exact-target, backed up, reversible, and never delete saves or firmware.

Follow-up scope

• define a versioned generic app-adapter schema and normalized lifecycle/progress fields;
• improve session-aware log selection when UI/library and title logs overlap;
• compare app build/profile/config capabilities without exposing values;
• model firmware compatibility as evidence rather than assuming newest or file-count equality;
• generate a public-safe app issue packet correlated with GPU, coredump, memory, Gamescope, storage, and probe timelines;
• add adapters for other deucebucket applications and high-value Deck runtimes;
• add DeckMD routes from application symptoms to adapter signatures and connected system checks.

Acceptance criteria

• Each supported app has an explicit module, schema/version, prerequisites, and limitations.
• Current versus historical app evidence is unambiguous.
• Progress and fatal states correlate with system modules before assigning a failure boundary.
• No raw app log is persisted by normal DeckDoc collection.
• Adversarial privacy fixtures cover app-specific identifiers and arguments.
• Reversible A/B guidance preserves exact backups and requires the app to be closed.
• Unknown apps still receive generic process/coredump/session guidance instead of a guessed diagnosis.
• Documentation explains that DeckDoc diagnoses the app; it does not become or embed into the app.