docs(phase4): Phase 4 overview — offline emulator → Steam Linux Runtime container (4.1–4.4)

[weter11]

Summary

Phase 4 — Containerized Steam Launch (Phases 4.1–4.4): SteamFlow can now run Windows games inside Valve's official Steam Linux Runtime (SLR) container, alongside the existing client-based and offline modes.

⚠️ Note on scope: the Phase 4 code already landed on main via the phase4/containerized-launch branch (commits 9402712…ff71bfe, rebased + fast-forwarded). This PR adds the umbrella overview document (docs/architecture/phase4-overview.md) that ties the four sub-phase docs together — the PR record describing what was done in Phase 4, mirroring PR #82 for Phases 1–3.

What was delivered

Three Steam-mediated launch modes (Auto / OfflineEmulated / OnlineContainerized):

SteamMode	Client	Game runs in	Steamworks bridge
Auto	Windows Steam client (Wine prefix)	Wine/Proton prefix	Windows steamclient.dll (named pipe)
OfflineEmulated	none	Wine prefix	local Goldberg-style emulator
OnlineContainerized	native Linux Steam (host)	SLR container (steamrt4)	Proton lsteamclient.dll → steamclient.so (network IPC)

Phase 4.1 — Offline emulator mode

• OfflineEmulated SteamMode: clientless launch with a local emulator satisfying the Steam API surface.

Phase 4.2 — Runtime provisioning + command builder

• RuntimeManager: SLR download/verify/extract/parse into ~/.config/SteamFlow/runtimes/<id>/ (scout/soldier/sniper/steamrt4), client-managed SteamLinuxRuntime_<line> detection, mtree/hash ArchiveVerification.
• PressureVesselBuilder: native Rust argv builder for pressure-vessel-wrap/bwrap with host Vulkan/EGL/dri/nvidia/display/audio pass-through.

Phase 4.3 — Containerized launch pipeline + Steam IPC bridge

• Real pressure-vessel-wrap contract: the runtime's run script is the entry point; valid flags are --filesystem / --env-if-host / one -- (the earlier --runtime-path/--env/--bind-mount etc. were falsified against the real binary and corrected).
• No secondary Windows steam.exe: SteamAPI_Init() is intercepted by Proton's lsteamclient.dll and routed to the host Steam client.

Phase 4.4 — Runtime integrity repair, parity, UI status

• steamflow runtime status [<line>] and runtime repair <line> [--force] (re-download + force_reprovision after purge).
• TUI: Runtime Settings shows Steam Linux Runtime 4.0 (steamrt4) [Valid · <rev>] with an inline Repair Runtime action (AsyncOp::RuntimeRepaired).
• test-diff auto-provisions the native reference capture (PROTON_LOG=1 → ~/steam-<appid>.log).
• Root-cause fixes found during live testing: PICS access-token support for tool-app depots (SLR/Proton); whole-tree exec-bit repair (ensure_runtime_executable) — the depot downloader strips exec bits, which broke both preflight and pressure-vessel's graphics-provider detection ("no common CPU arch"); VERSIONS.txt tab-separated table parsing; dropped the bogus manifest.json requirement.

Verification

• cargo check --all-targets clean; cargo test --all-targets green (140 lib tests + all integration suites).
• Live repair: steamflow runtime repair steamrt4 --force — re-downloaded the corrupt SLR 4.0 depot (672 MB), ✅ repaired (revision 4.0.20260805.254769), ✅ passes is_usable_runtime_root(). Truncated usr-mtree.txt.gz (0 B → 358 KB) replaced.
• Live boot: steamflow test-launch 620 (OnlineContainerized, pure-PE Proton) boots Portal 2 inside steamrt4 — bwrap up, Proton running, portal2.exe alive, d3dx assets loading. Both the Phase 4.3 truncated-archive error and the Phase 4.4 arch abort are gone.

Docs

• docs/architecture/phase4-overview.md ← this PR
• docs/architecture/phase4-offline-emulator-mode.md (4.1)
• docs/architecture/phase4-runtime-provisioning.md (4.2)
• docs/architecture/phase4-containerized-launch.md (4.3)
• docs/architecture/phase4-runtime-repair.md (4.4)

Known limitations

• OnlineContainerized requires the native Linux Steam client on the host (its 32-bit core needs i386 libs this host lacks) — the container boot is verified; full Steamworks connectivity is environment-gated.
• runtime repair --force always re-downloads the depot even when the client-managed runtime is already usable (future optimization).