Project-Kiln/docs/spec/04_BASE_PERFORMANCE_RELIABILITY.md

10. Base operating system

Version 1 targets x86_64 systems booted through UEFI. Legacy BIOS and other CPU architectures are not release-tested. AMD and NVIDIA graphics profiles are release-blocking; Intel graphics remains best-effort until representative hardware is available for the same session, game, update, and recovery matrix.

Core	Arch base, systemd, CPU microcode, zsh, NetworkManager, synchronized time/keyring initialization, and official multilib; bootloader and firmware support boundary remain to be selected
Kernel	Regular Arch linux is the reference kernel; linux-lts may be retained as a recovery fallback
Audio	PipeWire, WirePlumber, ALSA compatibility, Bluetooth audio components where needed
Graphics	Vulkan stack, 32-bit libraries, vendor-specific AMD/NVIDIA/Intel profile
Gaming	Steam, Wine, Winetricks, UMU, Proton management, Lutris, Heroic, Gamescope, GameMode, MangoHud, MangoApp support for Gamescope, and optional ProtonPlus maintenance GUI
Input	BlueZ, Bluetui, udev rules, SDL tools, kernel HID drivers, optional Blueman GUI, optional device-specific drivers, and post-v1-leaning InputPlumber evaluation
GUI support	Minimal compositor, Xwayland, portals, Polkit agent, fonts, file picker
Operations	Logging, diagnostics, package transaction history, recovery entries

Reproducibility initially means recorded repository state, exact package versions and hashes, project versions, configuration, and build inputs can reconstruct an equivalent system. ISO and package builds record their toolchain and archiso inputs. Bit-for-bit reproducible artifacts and independent rebuild verification are later hardening goals and are not claimed until tested.

11. Performance strategy

11.1 Definition of performance

Performance means consistent frametimes, low latency, stable clocks, reliable input, and minimal interference. Average FPS alone is not an adequate success metric.

11.2 Dynamic optimization

• Activate GameMode only through a request whose lifetime is tied to actual game execution; do not toggle it from an uncertain process heuristic.
• Use MangoApp for the Gamescope HUD path; upstream does not support ordinary MangoHud inside Gamescope. Use MangoHud directly only for non-Gamescope Vulkan/OpenGL launches where validated.
• Select an appropriate CPU power profile during play and restore it afterward only through a tested existing interface such as GameMode or power-profiles-daemon. Any privileged integration is a narrow static system service/policy that accepts typed bounded requests and never parses provider or game metadata as root.
• Apply GPU- and game-specific environment settings through explicit profiles.
• Inhibit sleep and disruptive scheduled work while a game is active.
• Avoid permanent maximum-performance settings unless measurement justifies them.

11.3 Benchmarking

Average FPS	Throughput; never used alone
1% and 0.1% lows	Short and severe stalls
Frametime distribution	Smoothness and pacing
Input latency	Responsiveness where measurable
CPU/GPU utilization	Bottleneck and scheduling evidence
RAM/VRAM	Capacity pressure and background overhead
Power and clocks	Thermal or power-management behavior
Launch time	Provider cold-start cost, session-shell overhead, and lazy-launch latency

12. Reliability, recovery, privacy, and security

• Retain at least two bootable kernels.
• Preserve or recover a known-good NVIDIA driver/kernel pairing where practical.
• Keep game libraries separate from replaceable system state where possible.
• The initial bare-metal reference is the project's Ryzen 9 7900X3D and RTX 5070 desktop, with the project OS installed to a dedicated external USB drive. Storage-sensitive results must identify the USB enclosure, interface, and drive and must not be generalized as CPU/GPU or distro overhead when external storage is the bottleneck.
• Provide package transaction logs and an optional Btrfs recovery profile using Snapper plus pacman pre/post transaction hooks; retain a filesystem-neutral path.
• Collect per-launch logs without capturing authentication secrets or unnecessary personal data.
• Store launcher tokens only through their provider's normal mechanism; do not duplicate credentials in the unified cache.
• Require no telemetry from project-owned components.
• Provide direct provider and safe-mode paths when abstraction fails.

12.1 Update policy

• Use the normal signed Arch repositories and ordinary complete pacman -Syu upgrades; do not maintain a delayed or separately tested Arch package channel.
• Partial upgrades are unsupported and must not be presented as a recovery or compatibility strategy.
• Keep project-owned packages independently updateable through the project's signed package repository so integration fixes can be delivered without replacing Arch's update model.
• Minimize reliance on undocumented provider internals and test against current upstream packages during development, but do not claim that the project can prevent every upstream regression.
• Detect and warn about known incompatible package, driver, kernel, or project-version combinations where practical.
• Retain recovery entries, package transaction history, and straightforward downgrade guidance. Snapshots remain optional; for the Btrfs recovery profile, use Snapper and pacman transaction hooks rather than project-owned snapshot machinery. Boot-menu integration is selected only after the bootloader is chosen and must be tested independently from snapshot creation.
• A future distributable ISO is an installation convenience built from the proven base-Arch configuration, not the initial development target or a separate frozen distribution branch.

12.2 Supply-chain and privilege policy

• Sign project repositories and public release artifacts and publish verification instructions.
• Track package source, version, checksum/signature, license, and required notices; generate an SBOM for public releases.
• Pin security and license audit tools in the development source inventory as well as configuring their policies. Exact-toolchain verification must inspect the active compiler because distro-provided Rust binaries may not honor rust-toolchain.toml.
• Keep dependency-license allowlists limited to licenses actually present and reviewed. New dependencies require an explicit license-policy change; speculative broad allowlists are not accepted.
• Prefer official Arch packages. Project-supplied AUR/community packages require pinned build recipes, review, isolated builds, and project-signed binaries; arbitrary user-installed AUR packages remain outside project guarantees.
• Validate provenance and checksums/signatures for externally downloaded Proton, UMU runtime payloads, and provider helpers where upstream provides them. Prefetchable runtime assets must have explicit cache, update, offline, and failure behavior.
• Offer ProtonPlus as an optional graphical maintenance tool for user-managed Proton, Wine, DXVK, and VKD3D variants. The backend may detect compatible tools it installs, but ProtonPlus does not replace project-owned runtime resolution, validation, pinning, cache provenance, prefetch, or offline contracts.
• Ordinary discovery and launches run unprivileged. Installer/system-integration privileges are isolated from parsers, frontends, provider clients, artwork handling, and games.
• Project-owned v1 components open no TCP/UDP listening sockets. Any later local service defaults to a per-user Unix socket under XDG_RUNTIME_DIR with owner-only permissions, peer-credential checks, request limits, and no network bridge unless remote control becomes a separately approved feature.
• Treat manifests, custom launch definitions, artwork paths, and generated frontend commands as untrusted input. Validate size and paths and use argument-safe process execution rather than interpolated shell commands.
• Maintain a machine-readable package/source inventory before packaging begins. It records official-repository packages, reviewed project builds, verified upstream binaries, transient build dependencies, bundled helper versions, signatures/hashes, licenses, and the responsible update path. Live AUR resolution is never part of an installation or update transaction.
• Define a small threat model before phase 2 covering malicious provider metadata, hostile game directories, symlink/path traversal, command and environment injection, local socket impersonation, credential leakage in logs, unsafe support bundles, and privilege-boundary mistakes.

12.3 Project licensing

• Project-owned software is licensed under GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
• Commercial use and sale remain permitted. Conveying covered binaries requires the corresponding source under the AGPL, and a modified version that supports remote network interaction must offer its corresponding source to users interacting with it over the network. Running an unmodified copy as a network service does not by itself create a new modification-specific source obligation.
• Third-party components retain their own licenses. Packaging, integration, and distribution work must track license compatibility and required notices rather than assuming the project license overrides dependencies.
• Documentation and non-software assets may receive appropriate compatible licenses later; their licensing must be explicit before public release.