# MVGAL Architectural Decisions

This document tracks intentional deviations from the original system specification or upstream defaults, serving as the system of record for design ambiguity resolution as mandated by the project requirements.

## 1. Interception vs. Kernel Replacement
**Decision**: The MVGAL architecture intercepts Vulkan, CUDA, OpenCL, and OpenGL at the userspace API boundary rather than creating a virtual DRM driver that entirely replaces the `amdgpu`/`nvidia` kernel modules.
**Rationale**: Upstream drivers do not expose a uniform command buffer format or job submission ABI at the DRM ioctl level. Attempting to parse and rewrite raw ring buffer submissions for a proprietary hardware queue (like NVIDIA's GSP or AMD's hardware scheduler) is intractable and fragile. Intercepting higher-level API calls (like `vkQueueSubmit` or `cudaLaunchKernel`) allows us to translate rendering and compute intents into multiple physical command buffers natively understood by each vendor's userspace driver (ICD).

## 2. NTSYNC Kernel Integration
**Decision**: MVGAL will implement a targeted, standalone `mvgal_ntsync.ko` kernel module rather than depending solely on upstream kernel patches.
**Rationale**: While NTSYNC is an active patch series in the Linux kernel, it is not universally available on all stable kernels (e.g., LTS branches). To meet the requirement of broad distribution support, a localized module ensures Proton compatibility works out of the box without requiring users to install custom experimental kernels.

## 3. WoW64 Thunk Layer Scope
**Decision**: The 32-bit to 64-bit translation thunk will be scoped explicitly to the graphics API boundaries (Vulkan/DXVK/OpenCL) rather than attempting a full system-wide `ntdll` emulation.
**Rationale**: Full WoW64 emulation is incredibly complex and better handled by Wine itself. By providing thunks specifically for the `libVK_LAYER_MVGAL` and intercept libraries, 32-bit Windows applications run by Proton can transparently access the 64-bit multi-GPU MVGAL backend without rewriting Wine's core memory manager.

## 4. Power Management Escalation
**Decision**: `pkexec` will be used explicitly for all power curve control CLI commands instead of a background root daemon.
**Rationale**: The specification strictly mandates `pkexec` and prohibits `sudo` for privilege escalation. Polkit provides fine-grained control and integrates perfectly with desktop environment authentication agents when modifying sensitive `/sys` nodes like `pp_od_clk_voltage`.
