44r0n7/Project-Kiln
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7d1077c0cb4747fe61bbbceb05ede3f9a6c34460
Project-Kiln/docs/spec/07_RISKS_DECISIONS_AND_HISTORY.md
T
44r0n7 7d1077c0cb feat: complete Steam execution
2026-07-20 15:51:11 -04:00

30 KiB
Raw Blame History

17. Risks and mitigations

Risk Mitigation
Wayland compositor or Gamescope instability, especially on NVIDIA Maintain Xorg, TTY, and safe-mode fallbacks; test pinned driver/kernel combinations.
Provider configuration changes Keep adapters isolated, capability-based, version-tested, and replaceable.
Heroic lacks a stable comprehensive CLI API Use supported launch mechanisms where possible and treat internal parsing as provisional.
Heroic store support is treated as one uniform backend Test Epic/Legendary, GOG/GOGDL, and Amazon/Nile independently; Heroic's Legendary fork and shared state are not assumed compatible with standalone helpers.
UMU performs an unexpected first-launch download Provide explicit prefetch/update commands, managed caches, verified acquisition where available, offline tests, progress reporting, and prompt failure when uncached offline.
GameMode is tied to an unreliable launch or tracking PID Keep a real GameMode client/wrapper request alive for the game; test Steam and provider handoffs instead of toggling from heuristic state.
MangoHud is injected into Gamescope as though it were supported Use MangoApp with Gamescope and reserve ordinary MangoHud for validated non-Gamescope launches.
CLI backend diverges from Heroic per-game configuration Define ownership boundaries, compare generated launch plans, and require provider-specific integration tests.
Resident launchers consume resources without benefit Keep Lean as default, hide inactive UIs, pause downloads during play where supported, and benchmark actual frametime impact.
Optimization folklore causes regressions Require benchmarks and remove changes that lack measurable value.
Arch rolling updates break the appliance Use normal complete Arch upgrades without a separate delayed channel; minimize fragile integration, publish project fixes, detect known incompatibilities, and retain recovery entries, logs, downgrade guidance, and optional snapshots.
Scope expands into a universal store manager Limit version 1 to discovery, information, launch, scan, and diagnostics.
Minimal GUI omits hidden dependencies Test authentication, file pickers, portals, fonts, Polkit, audio, and multiarch explicitly.
Pegasus integration becomes project-specific glue Generate its metadata through a dedicated adapter and keep all provider logic in the shared core.
Premature frontend work delays the backend Keep Pegasus, OpenGamepadUI integration, forks, and a first-party GUI outside version 1 implementation scope.
Public API freezes weak early assumptions Version contracts explicitly; stabilize only operations proven by the CLI and reference frontend.
Premature repository splitting creates coordination overhead Keep explicit crate and component boundaries in one repository; extract only independently useful, stable components with preserved history.
Broad implementation makes failures difficult to isolate Enforce narrow vertical tasks and four test gates before dependent work begins.
Temporary codename leaks into public compatibility surfaces Centralize branding, prefer functional internal identifiers, maintain a rename checklist, and scan before stable release.
Work Mode resource limits obscure failures or waste usage Reserve compilation, large tests, VM work, dependency downloads, and performance validation for local Codex CLI.
Provider launch commands detach from the actual game Track owned scopes when possible; otherwise use provider state or conservative correlation and report confidence explicitly.
Store identity, installation manager, and runtime are conflated Model game identity, installation UUID, configuration owner, execution backend, and Wine/Proton/UMU runtime separately.
Untrusted provider or frontend metadata becomes a shell command Use typed arguments and validated descriptor files; never interpolate titles or metadata into sh -c.
Upstream and community packages expand supply-chain risk Prefer official packages; pin, review, isolate, sign, inventory, and publish provenance for project-supplied community builds.
Optional reused tools become accidental core dependencies Keep Blueman, ProtonPlus, InputPlumber, snapshot recovery, and post-v1 frontends behind explicit profiles or capability checks; preserve direct diagnostic and filesystem-neutral paths.
Labwc cannot satisfy programmatic window-focus assumptions Treat focus as a session-adapter capability, keep compositor keybindings as the baseline, and report unsupported focus requests explicitly; upstream intentionally exposes no D-Bus or custom IPC.
AUR or bundled launcher packages silently bypass release controls Maintain a reviewed package/source inventory, build and sign pinned artifacts in isolation, and never resolve live AUR content during installation or update.
Malicious or corrupted provider data crosses a privilege boundary Apply file-size/path/symlink limits, argument-safe execution, XDG confinement, redaction, atomic writes, and adversarial fixtures; keep parsers and games unprivileged.
Real provider tests leak personal accounts or proprietary data into fixtures Use dedicated test accounts where practical, sanitize evidence, forbid live tokens and personal library dumps in the repository, and document provider-specific test constraints.
Temporary Kiln names collide with existing software, leak into stable surfaces, or drift away from the final project brand Keep kiln, kiln-core, and related labels repository-local; maintain a rename manifest and automated scan; select the related product and technical naming system before anything is published or globally installed.

18. Open questions

  • What final public project name and related technical naming system should replace Project Kiln and the temporary kiln/kiln-* family? This is intentionally deferred and does not block private implementation, but must be resolved and collision-checked before any package, crate, global executable, configuration namespace, or IPC name is published or installed.
  • Does Labwc pass the session prototype on AMD, Intel, and NVIDIA with Steam, Heroic, Lutris, portals, multi-monitor layouts, and nested Gamescope; which failures trigger Xorg fallback or a different compositor?
  • Which representative controllers must pass the first compatibility matrix?
  • Which bootloader and boot-menu integration should accompany the optional Btrfs/Snapper recovery profile?
  • Which vendor launcher should be the first post-v1 managed-prefix integration: Battle.net, EA App, Ubisoft Connect, Rockstar, or another?
  • Which terminal emulator should be the phase 5 reference after measuring startup, Wayland behavior, controller/font needs, and maintenance status?
  • What concrete frontend or live-state requirement, if any, will justify a resident backend service beyond the small session supervisor?
  • Which Pegasus limitations appear during real integration, and should they be solved externally, upstream, through a small patch set, or in a first-party frontend?
  • Which Heroic settings and credentials can supported CLI backends safely reuse, and which require an explicit import or independent configuration model?
  • Post-v1 only: after profiling, should Lean offer an explicit opt-in Steam idle-exit policy? Version 1 does not close provider clients automatically.
  • What questions and presets should the eventual installer present? This is intentionally deferred to a later discussion.

19. Decision log

ID Date State Decision
D-001 2026-07-17 Confirmed Arch Linux is the base.
D-002 2026-07-17 Confirmed Version 1 is CLI-first and has no conventional persistent DE.
D-003 2026-07-17 Confirmed USB and Bluetooth controller support is required.
D-004 2026-07-17 Confirmed Performance is the primary optimization target.
D-005 2026-07-17 Confirmed The design includes a unified launcher backend suitable for future frontends.
D-006 2026-07-17 Confirmed Build and validate the desired system as a base Arch package/configuration project before producing a distributable ISO as an installation convenience.
D-007 2026-07-17 Deferred A persistent lightweight desktop may become an optional profile.
D-008 2026-07-18 Confirmed Use QEMU/KVM through libvirt as the primary development and disposable test environment.
D-009 2026-07-18 Confirmed Use dedicated spare-SSD or test-machine bare metal for hardware compatibility and performance validation.
D-010 2026-07-18 Confirmed No project-integrated catalogue frontend owns discovery or normalized launch logic; the CLI and project graphical interfaces are replaceable clients of the shared backend, while provider-native clients retain native behavior.
D-011 2026-07-18 Confirmed Use unmodified upstream Pegasus as the first reference controller frontend through generated metadata that calls the shared project CLI, temporarily kiln.
D-012 2026-07-18 Confirmed Do not fork Pegasus or build a first-party graphical frontend initially; revisit either option only after the upstream integration exposes concrete limitations.
D-013 2026-07-18 Confirmed Initial-shell and frontend startup policy must be changeable after installation and support terminal, manual, automatic, and TTY modes.
D-014 2026-07-18 Proposed Publish a versioned local API and example client after its contracts are proven by the CLI and frontend integration.
D-015 2026-07-18 Confirmed Normal gaming mode uses a persistent minimal graphical session with a fullscreen terminal as the default visible shell.
D-016 2026-07-18 Confirmed Preserve a true TTY-only target for recovery and explicit console-only use.
D-017 2026-07-18 Confirmed Lean is the default runtime profile; Ready supports autostarted resident launchers and rapid switching.
D-018 2026-07-18 Confirmed Steam is started silently when required; unsupported attempts to split or strip the Steam client are not a project dependency.
D-019 2026-07-18 Confirmed Heroic-managed providers may use validated command-line backends without Heroic's GUI, through capability-based adapters that preserve configuration ownership.
D-020 2026-07-18 Deferred Installer questions and their presentation will be designed in a later discussion.
D-021 2026-07-18 Confirmed Use Project Kiln as a temporary internal codename; centralize branding and keep a tested rename path for the final public name.
D-022 2026-07-18 Confirmed Use Rust for project-owned backend, CLI, and provider-adapter software.
D-023 2026-07-18 Confirmed Begin in one Git repository with strict workspace and crate boundaries; extract stable independently useful components later rather than using early multi-repository development or submodules.
D-024 2026-07-18 Confirmed Implement one narrow vertical capability at a time and require unit, contract, isolated integration, and real-system or VM acceptance gates before dependent work proceeds.
D-025 2026-07-18 Confirmed Keep heavy compilation, dependency, VM, graphical, controller, package, ISO, and performance work local in Codex CLI; use Work Mode for lightweight planning, scaffolding, fixtures, and review.
D-026 2026-07-18 Confirmed License project-owned software under AGPL-3.0-or-later.
D-027 2026-07-18 Confirmed Upstream Pegasus integration is the first planned reference-frontend milestone after version 1 and does not block the version 1 release.
D-028 2026-07-18 Confirmed Every future spec change requires a cross-spec integrity check; unresolved conflicts that materially affect scope, architecture, release timing, compatibility, or user-visible behavior require owner clarification before a choice is recorded.
D-029 2026-07-18 Confirmed UMU is an execution runtime rather than a library provider; game identity remains store-qualified or custom while launch plans may select UMU.
D-030 2026-07-18 Confirmed Track game lifetime only as needed for temporary performance policy, sleep inhibition, state, logging, and cleanup; do not automatically close Steam, Heroic, Lutris, or other provider clients after play.
D-031 2026-07-18 Confirmed Use normal complete Arch updates without maintaining a delayed tested package channel; deliver project compatibility fixes independently and retain recovery safeguards.
D-032 2026-07-18 Confirmed Use the regular Arch linux kernel as the reference; do not prefer linux-zen, while allowing linux-lts as a tested recovery fallback.
D-033 2026-07-18 Confirmed Steam, Heroic-managed stores, and Lutris remain required for version 1; third-party vendor-launcher integrations move outside version 1. D-038 later makes the three Heroic-managed store targets explicit.
D-034 2026-07-18 Confirmed Separate game identity, installation instance, configuration owner, execution backend, and compatibility runtime; version machine-readable schemas from phase 1 without promising public stability before 1.0.
D-035 2026-07-18 Confirmed Use validated inert descriptors for Pegasus exports, define reload/restart behavior, and never interpolate metadata into shell commands.
D-036 2026-07-18 Confirmed Resolve login, seat, user-session, and recovery-loop behavior during the session proof rather than deferring it to ISO work.
D-037 2026-07-18 Confirmed Define reproducibility initially as reconstruction from recorded repository/package/build inputs; treat bit-for-bit verification as later hardening and require signed releases, provenance, and an SBOM.
D-038 2026-07-18 Confirmed Treat Heroic-managed Epic, GOG, and Amazon support as three independent v1 capability targets using validated Legendary, GOGDL, and Nile paths; do not infer standalone-helper compatibility from Heroic's integration.
D-039 2026-07-18 Confirmed Make UMU runtime acquisition explicit and testable through managed caching, prefetch/update, verified downloads where available, and defined offline behavior.
D-040 2026-07-18 Confirmed Tie GameMode to a real client/wrapper request lasting for actual game execution; lifecycle confidence alone does not activate it.
D-041 2026-07-18 Confirmed Use MangoApp for Gamescope HUD integration and ordinary MangoHud only on validated non-Gamescope paths.
D-042 2026-07-18 Confirmed Adopt Bluetui as the interactive Bluetooth TUI, retain project-owned structured diagnostics and automation, and offer Blueman as the optional desktop-neutral Bluetooth GUI.
D-043 2026-07-18 Confirmed Evaluate InputPlumber as an optional, post-v1-leaning prototype for advanced routing, remapping, virtual devices, overlays, and controller shell control; do not make it a v1 baseline without evidence.
D-044 2026-07-18 Confirmed Offer ProtonPlus as an optional maintenance GUI while retaining backend ownership of runtime resolution, validation, pinning, provenance, caching, prefetch, and offline behavior.
D-045 2026-07-18 Confirmed Build the guided installer on archinstall with a maintained project profile/configuration and a pinned local plugin or custom script only where necessary; do not reimplement storage, encryption, account, or base-install functions or fetch unpinned executable plugins.
D-046 2026-07-18 Confirmed Offer an optional Btrfs recovery profile using Snapper and pacman transaction hooks; do not require Btrfs, and defer boot integration until the bootloader is selected.
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 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.
D-054 2026-07-18 Confirmed Establish explicit XDG, filesystem, process-execution, redaction, atomic-write, local-IPC, and privilege trust boundaries before provider implementation, with adversarial acceptance tests.
D-055 2026-07-18 Confirmed Do not install Heroic or other non-repository components from live AUR state. Release profiles consume reviewed, pinned, reproducibly built and project-signed packages or verified upstream artifacts recorded in the source inventory.
D-056 2026-07-18 Confirmed Never guess through ambiguous game names: exact stable IDs are deterministic, unique names/aliases may launch directly, interactive terminals may present a numbered/TUI choice, and noninteractive callers receive a structured ambiguity error with candidates.
D-057 2026-07-18 Confirmed Persist installation UUIDs and move aliases in a small schema-versioned, atomic project-owned XDG state registry when adapters lack a stable native installation ID; this identity state is distinct from an optional disposable discovery cache.
D-058 2026-07-18 Confirmed Maintain requirement-to-phase-to-test traceability from phase 0 onward; a release cannot pass with an orphaned Required requirement or prose-only evidence.
D-059 2026-07-18 Superseded by D-065 Originally required collision-checked install/package/crate/configuration/IPC names during phase 0 before scaffolding public surfaces. D-065 narrows the gate to public, published, or globally installed artifacts so private implementation can proceed with repository-local placeholders.
D-060 2026-07-18 Confirmed Limit version 1 to x86_64 UEFI systems; legacy BIOS and non-x86 architectures are outside the v1 support boundary.
D-061 2026-07-18 Confirmed Ship v1 as a single-local-gaming-user appliance while keeping state, services, credentials, paths, libraries, saves, and profiles per-user so multi-user Steam-machine use can be added later.
D-062 2026-07-18 Confirmed Make AMD and NVIDIA GPU/driver coverage release-blocking for v1; treat Intel as tested best-effort until representative hardware can run the full matrix.
D-063 2026-07-18 Confirmed Use versioned TOML with commented generated defaults and CLI editing/validation for user configuration; retain JSON for machine-readable contracts and output.
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

Version Date Summary
0.1 2026-07-17 Initial living specification created from planning discussion. Added controller requirements, CLI-only scope, unified backend concept, optional future desktop, roadmap, risks, and open questions.
0.2 2026-07-18 Confirmed a libvirt/QEMU-first development workflow, layered VM and bare-metal validation, spare-SSD isolation, and optional-only GPU passthrough.
0.3 2026-07-18 Defined replaceable frontend architecture, upstream Pegasus reference integration, changeable graphical-session startup policies, fork/custom-frontend escalation rules, and a phased public API path.
0.4 2026-07-18 Replaced ephemeral per-launch graphics with a persistent minimal compositor shell and fullscreen terminal; added Lean/Ready/Frontend/Custom/TTY profiles, launcher switching and residency policy, Steam client constraints, Heroic CLI-backend integration, and deferred installer questions.
0.5 2026-07-18 Adopted the Project Kiln codename and rename policy, Rust, AGPL-3.0-or-later, a modular monorepo with extractable provider crates, strict incremental test gates, and a lightweight Work Mode/local Codex CLI execution split.
0.6 2026-07-18 Corrected spec authority wording, Pegasus status language, controller CLI namespacing, a deferred-capability example, bootloader status, and AGPL network-use wording; recorded the unresolved version 1 Pegasus boundary explicitly.
0.7 2026-07-18 Confirmed Pegasus integration as post-version-1 work, removed the related open question, and added an explicit version 1 release boundary after roadmap phase 11.
0.8 2026-07-18 Added a mandatory cross-spec integrity procedure for future planning changes, including dependency, release-boundary, status, example, ID, link, and version checks plus an explicit clarification rule for material ambiguity.
0.9 2026-07-18 Reclassified UMU as a runtime; separated game, installation, owner, backend, and runtime identity; defined confidence-based lifecycle tracking; adopted normal Arch updates and the regular kernel; confirmed base-Arch-first/ISO-later delivery; moved vendor launchers post-v1; and added configuration precedence, session ownership, controller states, safe Pegasus descriptors, reproducibility levels, and supply-chain requirements.
0.10 2026-07-18 Split Heroic-managed Epic, GOG, and Amazon into independent v1 targets; corrected Lutris local-ID handling, GameMode lifetime semantics, Gamescope HUD integration, and UMU acquisition/offline requirements using current upstream documentation.
0.11 2026-07-18 Reused maintained upstream components where appropriate: Bluetui and optional Blueman for Bluetooth, optional ProtonPlus, archinstall-based installation, optional Snapper/pacman-hook Btrfs recovery, gamescope-session references for dedicated frontend sessions, post-v1 OpenGamepadUI and InputPlumber evaluation, and Labwc as the leading compositor prototype.
0.12 2026-07-18 Completed a build-readiness audit: added phase 0 and reproducible evidence requirements; corrected store/adapter identity, durable installation-ID state, frontend/provider-native boundaries, ambiguous-name behavior, and post-v1 CLI leakage; made caching conditional; fixed session target ownership and duplicate headings; accounted for Labwc's lack of IPC; defined controller recovery, package-source, AUR, trust-boundary, adversarial-test, and release-matrix requirements; and narrowed the remaining owner decisions.
0.13 2026-07-18 Confirmed the x86_64/UEFI and single-user v1 boundaries with a multi-user-safe architecture; made AMD/NVIDIA release-blocking and Intel best-effort; selected versioned TOML plus CLI configuration; recorded the external-USB Ryzen 9/RTX 5070 reference system; and required Xbox/PlayStation USB and Bluetooth coverage.
0.14 2026-07-18 Deferred technical naming until the final project brand is selected; allowed private implementation with repository-local functional placeholders; and required a rename manifest, automated placeholder scan, collision check, and completed rename before public, published, or globally installed artifacts.
0.15 2026-07-18 Adopted the temporary Kiln development family throughout the active specification: a single repository-local kiln CLI and functional kiln-* component labels, with no separate convenience or administrative executable.
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.
0.23 2026-07-20 Completed Phase 4 with typed native and Flatpak Steam launch plans, shell-free client submission, structured failures, and real native Terraria plus GE-Proton Overlord II acceptance tests.

21. Reference notes

Reference in New Issue View Git Blame Copy Permalink