feat: complete native execution and Steam discovery

2026-07-18 20:11:52 -04:00
parent 514f87dacb
commit bc0090c63d
42 changed files with 6403 additions and 97 deletions
@@ -33,4 +33,4 @@ This directory is the starting point for project planning and later implementati

 ## Integrity note

-The numbered topic files are the current v0.15 source of truth. `99_FULL_SPEC_ARCHIVE.md` preserves the complete monolithic v0.4 specification for historical and integrity checks, so it no longer matches the evolving numbered files byte-for-byte.
+The numbered topic files are the current v0.22 source of truth. `99_FULL_SPEC_ARCHIVE.md` preserves the complete monolithic v0.4 specification for historical and integrity checks, so it no longer matches the evolving numbered files byte-for-byte.
@@ -2,9 +2,9 @@

 > Performance-first Linux gaming appliance with a unified launcher backend

-| **Status**         | Implementation — phase 0 complete; phase 1 ready     |
+| **Status**         | Implementation — phases 0–3 complete; phase 4 ready |
 |--------------------|----------------------------------------------------|
-| **Version**        | 0.18                                               |
+| **Version**        | 0.22                                               |
 | **Created**        | July 17, 2026                                      |
 | **Document type**  | Living project specification                       |
 | **Current target** | Purpose-built, performance-focused gaming distribution |
@@ -9,7 +9,7 @@
 - Do not split components into separate Git repositories during early development. Avoid submodules and multi-repository coordination while interfaces are still changing.
 - A component may later move to its own repository with history preserved when it has a stable public contract, independent tests, clear external value, and a genuinely independent release lifecycle.
 - The repository and task documentation must allow one Codex CLI session started at the repository root to work across the complete project without manual context handoffs.
- Bootstrap the repository before feature work with a pinned Rust toolchain, committed dependency lockfile, formatting and lint policy, deny-by-default CI checks, license/security auditing, fixture conventions, changelog/version policy, and an architecture-decision-record directory. The first vertical slice must not invent these piecemeal.
+- Bootstrap the repository before feature work with a pinned Rust toolchain, committed dependency lockfile, formatting and lint policy, deny-by-default local quality gates, license/security auditing, fixture conventions, changelog/version policy, and an architecture-decision-record directory. The first vertical slice must not invent these piecemeal.

 ### 5.1 Layer model

@@ -37,7 +37,7 @@ Development will use a layered workflow: fast, repeatable testing in virtual mac
 - A capability advances through four gates: unit tests for pure logic and parsers; contract tests for schemas and adapter behavior; isolated integration tests using fixtures or temporary state; and real-system or VM acceptance tests where applicable.
 - Work may proceed in parallel only when tasks are demonstrably independent and do not edit the same files or depend on unsettled contracts.
 - Failures at any gate block the next dependent phase. Exceptions require an explicit documented decision rather than silent scope expansion.
- Treat the workspace MSRV and the reviewed development toolchain as separate controls: the MSRV describes compatible source, while local and CI gates verify the exact active compiler selected for reproducible development.
+- Rust 1.97.1 is both the minimum supported compiler and the reviewed local toolchain. The complete local gate rejects any different active compiler before compilation.
 - Every internal path dependency declares an exact compatible version as well as its path. Dependency changes update the lockfile, source inventory where applicable, license policy, and advisory/license/source audit evidence in the same task.
 - Do not preapprove dependency licenses that are not present. Add a license to the allowlist only with the reviewed dependency that requires it.
 - Each real-system gate records the exact package versions, hardware/driver/kernel tuple, fixture or test account, commands, expected result, observed result, logs, and cleanup. "Launch one game" without a reproducible evidence record is not an acceptance test.
@@ -54,7 +54,7 @@ Development will use a layered workflow: fast, repeatable testing in virtual mac

 | **Phase** | **Focus**       | **Exit condition**                                                                             |
 |-----------|-----------------|------------------------------------------------------------------------------------------------|
-| 0         | Repository and evidence baseline | Create the Rust workspace and component boundaries using the approved temporary, repository-local Kiln family; establish a rename manifest and automated placeholder scan; pin the toolchain and lockfile; configure formatting, linting, tests, CI, dependency/license/security audits, release/version policy, ADRs, fixture rules, threat model, package/source inventory, test-evidence template, requirement-to-test traceability matrix, and supported-platform decision record. Final collision-checked project/package/crate/executable/configuration/IPC namespaces are required before any public, published, or globally installed artifact, but do not block private implementation. No provider implementation begins before the remaining baseline passes. |
+| 0         | Repository and evidence baseline | Create the Rust workspace and component boundaries using the approved temporary, repository-local Kiln family; establish a rename manifest and automated placeholder scan; pin the local toolchain and lockfile; configure formatting, linting, tests, a complete local verification entrypoint, dependency/license/security audits, release/version policy, ADRs, fixture rules, threat model, package/source inventory, test-evidence template, requirement-to-test traceability matrix, and supported-platform decision record. Final collision-checked project/package/crate/executable/configuration/IPC namespaces are required before any public, published, or globally installed artifact, but do not block private implementation. No provider implementation begins before the remaining baseline passes. |
 | 1         | Contracts       | Define and aggressively test versioned game/installation identity, the durable installation registry, store/adapter/configuration-owner/execution-backend separation, provider and runtime interfaces, JSON records, launch plans, lifecycle confidence, structured errors, and configuration precedence/provenance using a mock adapter. |
 | 2         | Native vertical slice | Complete native discovery, normalization, search, dry-run planning, launch execution, logging, and failure handling before beginning Steam execution. |
 | 3         | Steam discovery | Parse Steam installation and library state through read-only, fixture-driven tests; normalize installed games without launching them. |
@@ -100,7 +100,7 @@
 | D-047  | 2026-07-18 | Confirmed | Reference or reuse ChimeraOS gamescope-session for dedicated frontend sessions where appropriate, but not as the Lean/Ready general multi-window shell. |
 | D-048  | 2026-07-18 | Confirmed | Add OpenGamepadUI as a post-v1 frontend candidate beside Pegasus without granting its internal catalog or plugins backend authority. |
 | D-049  | 2026-07-18 | Confirmed | Use Labwc as the leading stacking-compositor prototype while keeping final selection conditional on application, hardware, portal, multi-monitor, and nested-Gamescope tests. |
-| D-050  | 2026-07-18 | Confirmed | Add a phase 0 repository/evidence baseline before feature work: pinned toolchain and lockfile, CI quality gates, audits, ADRs, fixture rules, threat model, package/source inventory, test-evidence format, and supported-platform record. |
+| D-050  | 2026-07-18 | Superseded by D-067 | Originally required hosted CI quality gates as part of the phase 0 repository/evidence baseline. D-067 replaces hosted execution with mandatory local verification. |
 | D-051  | 2026-07-18 | Confirmed | Start with on-demand authoritative discovery and no persistent database; add only a disposable cache or SQLite index when measured latency or live-state requirements justify it, preserving a no-cache path. |
 | D-052  | 2026-07-18 | Confirmed | Store IDs remain storefront-qualified (`epic:`, `gog:`, `amazon:`) even when Heroic owns configuration; the management client is not part of canonical game identity. |
 | D-053  | 2026-07-18 | Confirmed | Treat window focus as a compositor/session-adapter capability. Labwc keybindings are the baseline because Labwc intentionally exposes no D-Bus or custom IPC; unsupported programmatic focus is reported honestly. |
@@ -117,6 +117,7 @@
 | D-064  | 2026-07-18 | Confirmed | Use the Ryzen 9 7900X3D/RTX 5070 desktop with a dedicated external USB project drive as the initial bare-metal reference, and require Xbox-family and PlayStation-family controller coverage over both USB and Bluetooth. |
 | D-065  | 2026-07-18 | Confirmed | Defer technical names until the final public project name can define one related naming system. Permit only clearly temporary repository-local labels during private development, and require the rename manifest, collision screen, and final rename before anything is published or globally installed. |
 | D-066  | 2026-07-18 | Confirmed | Use the temporary Project Kiln naming family for private development: one repository-local `kiln` CLI with subcommands, plus functional `kiln-core`, `kiln-cli`, `kiln-session`, and `kiln-adapter-*` component labels. Do not create separate `play` or administrative executables. |
+| D-067  | 2026-07-18 | Confirmed | Keep Gitea as source storage only. Run compilation, tests, Clippy, dependency audits, VM work, and release verification locally on the development desktop through one recorded gate. Rust 1.97.1 is both the minimum supported and reviewed compiler; hosted workflows are not required. |

 ## 20. Change log

@@ -140,6 +141,10 @@
 | 0.16        | 2026-07-18 | Began private phase 0 implementation; pinned Rust 1.97.1 after the upstream miscompilation-fix release, established the initial workspace/evidence baseline, and changed project status from planning to implementation. |
 | 0.17        | 2026-07-18 | Closed phase 0 after the exact Rust toolchain, formatting, compilation, unit tests, Clippy, canonical AGPL license, workspace/source checks, temporary-name scan, and cargo-deny advisory/bans/license/source gates all passed. |
 | 0.18        | 2026-07-18 | Promoted Phase 0 lessons into binding development rules: distinguish MSRV from the enforced toolchain pin, version local path dependencies, keep license allowlists evidence-based, audit pinned development tools, and use Phase 0 completion as the Codex CLI handoff point with a root `AGENTS.md`. |
+| 0.19        | 2026-07-18 | Completed phases 1 and 2: versioned provider-independent contracts, durable installation identity, native manifest and approved Desktop Entry discovery, normalized search and resolution, dry-run planning, owned process execution, private logging, structured failures, and their automated evidence. |
+| 0.20        | 2026-07-18 | Replaced the unused hosted-CI plan with mandatory local verification, made Rust 1.97.1 the minimum and reviewed compiler, and scheduled closure of the remaining configuration and adversarial-test gaps before phase 3. |
+| 0.21        | 2026-07-18 | Closed the pre-phase-3 gaps with local configuration defaults, validation, explanation and safe edits; native launch-plan configuration integration; removal of the obsolete file-lock dependency; bounded redacted process logs; and expanded adversarial tests. |
+| 0.22        | 2026-07-18 | Completed Phase 3 with bounded read-only Steam library and app-manifest parsing, stable App ID identities, provider-scoped CLI discovery, adversarial fixtures, and a non-launching check against the local Steam installation. |

 ## 21. Reference notes