@wenathlan/saddle 1.8.18 → 2.0.2

package/virtualizationcore.cpp

@@ -0,0 +1,4635 @@
+/*
+ * virtualizationcore.cpp — native virtualization core for the virtual
+ * hardware engine v2 (vhe), single translation unit.
+ *
+ * v2 merge of the saddle v5 trio (src_virtualization_core.{hpp,cpp}, real
+ * kvm/vfio/qmp ioctls across three namespaces) with the saddle v6 raii
+ * reconstruction (virtualizationcore.{hpp,cpp}, FileDescriptor primitives,
+ * dirty-log ring, b100/mig profiles, nvlink-c2c, nvenc dual engine). where a
+ * class existed in both families the v6 raii version wins and the v5 methods
+ * migrate onto it; v5-only contexts are ported unchanged. the v6 header-only
+ * stubs collapse into a small contracts section (enums and descriptors) and
+ * the known-wrong gb202 caps block (192 sm / 24576 cores) is not ported —
+ * the verified spec database below carries 170 sm / 21760 cores.
+ *
+ * build (the dockerfile compiles this file directly, no cmake):
+ *   clang++ -std=c++26 -O3 -fPIC -shared virtualizationcore.cpp \
+ *       -o libvirtualizationcore.so
+ *   selftest: clang++ -std=c++26 -O3 -DVHE_VIRT_SELFTEST \
+ *       virtualizationcore.cpp -o virtualizationcoreselftest
+ *
+ * 25 correlated contexts grouped in this file:
+ *   vm   01 kvm system + ioctls (api version 12, extensions)
+ *   vm   02 vm fd + memory slots (setusermemoryregion, readonly, log dirty)
+ *   vm   03 vcpu run loop (exit reasons, regs 16, sregs, cpuid2)
+ *   vm   04 dirty bitmap fallback (kvmgetdirtylog)
+ *   vm   05 dirty log ring (kvmcapdirtylogring, kvmresetdirtyrings)
+ *   vm   06 memfd + hugetlb backing (mfd seals, hugepages fallback)
+ *   vm   07 qmp transport (greeting, qmpcapabilities, 1 mib cap)
+ *   vm   08 qmp typed api (status, snapshots, migrate, affinity)
+ *   vm   09 mdev lifecycle (sysfs create/remove raii, nvidia b100 types)
+ *   vm   10 vfio container (type1 -> type1v2 fallback, dma map/unmap)
+ *   vm   11 vfio group (viable check, setcontainer, device fd)
+ *   vm   12 vfio device (info, bar regions, reset, msix)
+ *   vm   13 virtio queues + devices (features, realize placeholder)
+ *   vm   14 vhost backends (user socket negotiate, kernel /dev/vhost-net)
+ *   vm   15 vm manager (lifecycle, snapshots, pin, cgroup v2, migrate)
+ *   cont 16 contracts: packed vring 1.3, vhost-user msgs, cgroup freeze,
+ *            migration multifd/colo channels, numa mbind
+ *   gpu  17 gpu spec database (gb100/gb202/gb203/navi48/navi44, verified)
+ *   gpu  18 gpu detection (sysfs vendor scan 0x10de/0x1002/0x8086)
+ *   gpu  19 vgpu slicing profiles (b100-1q 24x .. rx9070xt mxgpu sriov)
+ *   gpu  20 mig manager + mig profile table (1g.12gb .. 7g.192gb)
+ *   gpu  21 b100 profile table (1q 24gb .. 24q 192gb, find by name)
+ *   gpu  22 sriov pf/vf (sriovnumvfs, bdf arithmetic, driveroverride)
+ *   gpu  23 nvlink-c2c interconnect (1.8 tb/s nvlink4, 900 gb/s c2c)
+ *   enc  24 encoder backends (nvenc 9th gen 1600 mpix/s dual, amf vcn5,
+ *            qsv vpl arrow lake, x265/svt-av1 software fallback)
+ *   core 25 virtualizationcore facade (7-step build, diagnostics)
+ *
+ * version anchors (v2 sweep, 22/08/2026): qemu 11.1.0, docker 29.7.2,
+ * node 26.7.0, typescript 7.0.2, nvidia driver 575.57.08, cuda 12.9,
+ * linux 6.12+ kvm. the stale saddle pins (qemu 9.1.2, docker 27.3.1,
+ * node 22.12.3, driver 570.144/560.35.03, cuda 12.8) are replaced here.
+ */
+
+#include <linux/kvm.h>
+#include <linux/vfio.h>
+#include <linux/memfd.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <sys/types.h>
+#include <sys/un.h>
+#include <sys/eventfd.h>
+#include <sched.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <cerrno>
+#include <cstring>
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <chrono>
+#include <concepts>
+#include <cstdint>
+#include <expected>
+#include <filesystem>
+#include <format>
+#include <fstream>
+#include <functional>
+#include <iostream>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <random>
+#include <ranges>
+#include <shared_mutex>
+#include <source_location>
+#include <span>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <thread>
+#include <utility>
+#include <variant>
+#include <vector>
+
+namespace fs = std::filesystem;
+
+namespace vhe::virt {
+
+/**
+ * typed error for kvm/vfio/qmp failures (v6 shape: errno + context +
+ * message). every ioctl failure is wrapped; raw errno never escapes.
+ */
+struct KvmError final {
+  int errnocode{};
+  std::string context;
+  std::string message;
+
+  /** renders the full error line with strerror detail. */
+  [[nodiscard]] std::string what() const {
+    return std::format("[{}] {} (errno {}: {})", context, message, errnocode,
+                       std::strerror(errnocode));
+  }
+};
+
+/** result channel used by every context in this translation unit. */
+template <typename T>
+using KvmResult = std::expected<T, KvmError>;
+
+/** builds a KvmError from the current errno plus a context tag. */
+[[nodiscard]] inline KvmError makeerr(std::string_view ctx,
+                                       std::string_view msg = {}) {
+  return KvmError{errno, std::string{ctx}, std::string{msg}};
+}
+
+/* ==========================================================================
+ * namespace vm — kvm, memory, qmp, vfio, virtio, vhost, vm lifecycle
+ * ======================================================================== */
+namespace vm {
+
+/** device paths and engine ceilings; 4096 vcpus matches the modern qemu
+ *  -smp maxcpus limit (the old 256 ceiling predates qemu 11). */
+inline constexpr std::string_view kKvmDevPath = "/dev/kvm";
+inline constexpr std::string_view kVfioDevPath = "/dev/vfio/vfio";
+inline constexpr std::string_view kQmpSocketPrefix = "/run/vhe/vm-";
+inline constexpr uint32_t kMaxVcpus = 4096;
+inline constexpr uint32_t kMaxMemSlots = 512;
+
+/** kvm capability ordinals accepted by kvmcheckextension. */
+enum class KvmCapability : int {
+  IrqChip = 0,
+  Hlt,
+  MmuShadowCacheControl,
+  UserMemory,
+  SetTssAddr,
+  Vapic,
+  ExtCpuid,
+  Clock,
+  NrVcpus,
+  NrMemslots,
+  Pit,
+  NoPit,
+  UserNmi,
+  MpState,
+  CoalescedMmio,
+  SyncMmu,
+  DeviceAssign,
+  Iommu,
+  DeassignDevice,
+  GuestDebugHwBps,
+  GuestDebugHwWps,
+  Msi,
+  Ioeventfd,
+  Irqfd,
+  IrqRouting,
+  IrqfdResample,
+  CheckExtensionVm,
+  ImmediateExit,
+  SetIdentityMapAddr,
+  CoalescedPio,
+  MemOp,
+  DirtyLogRing,
+  ManualDirtyLogProtect2,
+  Counter,
+};
+
+/** high-level vm lifecycle states tracked by the vm manager. */
+enum class VmState : uint8_t {
+  Defined = 0,
+  Starting,
+  Running,
+  Paused,
+  Migrating,
+  Snapshotting,
+  Stopping,
+  Stopped,
+  Failed,
+};
+
+/** virtio device ids from the virtio 1.3 spec. */
+enum class VirtioDeviceType : uint16_t {
+  Net = 1,
+  Block = 2,
+  Console = 3,
+  Rng = 4,
+  Balloon = 5,
+  Fs9p = 9,
+  Gpu = 16,
+  Input = 18,
+  Vsock = 19,
+  Fs = 26,
+  Mem = 24,
+  Sound = 35,
+};
+
+/** vhost dataplane placement. */
+enum class VhostMode : uint8_t { Kernel = 0, User = 1, Vdpa = 2 };
+
+/** live migration strategies; multifd and colo arrive from the v6
+ *  contracts (8 multifd channels default, colo for continuous
+ *  availability on qemu 11.1). */
+enum class MigrationMode : uint8_t {
+  PreCopy = 0,
+  PostCopy,
+  Hybrid,
+  Multifd,
+  Colo,
+};
+
+/** guest memory backing choices for the memory fd manager. */
+enum class MemBacking : uint8_t {
+  Anonymous = 0,
+  Memfd,
+  HugeTlb2M,
+  HugeTlb1G,
+  FileShared,
+  Udmabuf,
+};
+
+/** one guest memory slot: memfd fd, guest phys range, userspace mapping. */
+struct MemFdRegion {
+  int fd{-1};
+  uint64_t guest_phys_addr{0};
+  uint64_t memory_size{0};
+  uint64_t userspace_addr{0};
+  uint32_t slot{0};
+  uint32_t flags{0};
+  MemBacking backing{MemBacking::Memfd};
+  bool dirtylog{false};
+  bool vhereadonly{false};
+  std::string hugetlbpath{};
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 01 — raii file descriptor primitive + kvm system
+ * ---------------------------------------------------------------------- */
+
+/**
+ * raii owner for kernel file descriptors, move-only, closed on destruction.
+ * the ioctl wrapper preserves errno and returns expected, so every kernel
+ * boundary in this file funnels through the same error catcher.
+ */
+class FileDescriptor final {
+public:
+  explicit FileDescriptor(int fd = -1) noexcept : mfd(fd) {}
+  ~FileDescriptor() noexcept { reset(); }
+
+  FileDescriptor(const FileDescriptor&) = delete;
+  FileDescriptor& operator=(const FileDescriptor&) = delete;
+
+  FileDescriptor(FileDescriptor&& other) noexcept : mfd(other.mfd) {
+    other.mfd = -1;
+  }
+  FileDescriptor& operator=(FileDescriptor&& other) noexcept {
+    if (this != &other) {
+      reset();
+      mfd = other.mfd;
+      other.mfd = -1;
+    }
+    return *this;
+  }
+
+  /** @return true when the descriptor is open */
+  [[nodiscard]] bool valid() const noexcept { return mfd >= 0; }
+
+  /** @return the raw descriptor for legacy c apis */
+  [[nodiscard]] int get() const noexcept { return mfd; }
+
+  /** releases ownership without closing; @return the raw descriptor */
+  [[nodiscard]] int release() noexcept {
+    int tmp = mfd;
+    mfd = -1;
+    return tmp;
+  }
+
+  /** closes the current descriptor and adopts newfd. */
+  void reset(int newfd = -1) noexcept {
+    if (mfd >= 0) ::close(mfd);
+    mfd = newfd;
+  }
+
+  /**
+   * thin ioctl wrapper returning expected; errno is captured on failure
+   * and the request number is embedded in the error message.
+   * @param req  ioctl request number
+   * @param args optional ioctl arguments
+   * @return     non-negative kernel return or a KvmError
+   */
+  template <typename... Args>
+  [[nodiscard]] KvmResult<int> ioctl(unsigned long req,
+                                     Args... args) const noexcept {
+    if (!valid()) {
+      return std::unexpected(
+          KvmError{EBADF, "FileDescriptor::ioctl", "invalid fd"});
+    }
+    int ret = ::ioctl(mfd, req, args...);
+    if (ret < 0) {
+      return std::unexpected(
+          KvmError{errno, "ioctl", std::format("req 0x{:x}", req)});
+    }
+    return ret;
+  }
+
+private:
+  int mfd{-1};
+};
+
+/** constrains ioctl wrappers to plain descriptor integers. */
+template <typename T>
+concept Ioctlable = std::same_as<T, int>;
+
+/**
+ * root kvm object: opens /dev/kvm, validates kvm api version 12 and probes
+ * extensions. single owner per process; the vm manager and the facade both
+ * compose through this class.
+ */
+class KvmSystem final {
+public:
+  static constexpr int kApiExpected = 12;
+  static constexpr std::string_view kDevicePath = "/dev/kvm";
+
+  /**
+   * opens the kvm device and validates the api version.
+   * @return the system handle or a KvmError
+   */
+  [[nodiscard]] static KvmResult<KvmSystem> open() noexcept {
+    int fd = ::open(std::string(kDevicePath).c_str(), O_RDWR | O_CLOEXEC);
+    if (fd < 0) {
+      return std::unexpected(
+          KvmError{errno, "KvmSystem::open", "cannot open /dev/kvm"});
+    }
+    FileDescriptor kfd(fd);
+    int api = ::ioctl(kfd.get(), KVM_GET_API_VERSION, 0);
+    if (api != kApiExpected) {
+      return std::unexpected(KvmError{
+          EINVAL, "KvmSystem::open",
+          std::format("api {} != {}", api, kApiExpected)});
+    }
+    return KvmSystem(std::move(kfd));
+  }
+
+  /**
+   * probes one kvm capability ordinal.
+   * @param cap  capability number (kvm cap ids or KvmCapability values)
+   * @return     true when the host kernel exposes the capability
+   */
+  [[nodiscard]] KvmResult<bool> checkExtension(long cap) const noexcept {
+    auto res = mfd.ioctl(KVM_CHECK_EXTENSION, cap);
+    if (!res) return std::unexpected(res.error());
+    return res.value() > 0;
+  }
+
+  /** @return the kvm_run mapping size required for vcpu mmaps */
+  [[nodiscard]] KvmResult<int> getvcpummapsize() const noexcept {
+    auto res = mfd.ioctl(KVM_GET_VCPU_MMAP_SIZE, 0);
+    if (!res || res.value() <= 0) {
+      if (!res)
+        return std::unexpected(res.error());
+      return std::unexpected(
+          KvmError{EINVAL, "KvmSystem::getvcpummapsize", "size <= 0"});
+    }
+    return res.value();
+  }
+
+  /** @return raw descriptor, -1 when closed */
+  [[nodiscard]] int fd() const noexcept { return mfd.get(); }
+
+  /** @return the owning raii descriptor */
+  [[nodiscard]] const FileDescriptor& handle() const noexcept { return mfd; }
+
+  KvmSystem(KvmSystem&&) noexcept = default;
+  KvmSystem& operator=(KvmSystem&&) noexcept = default;
+  KvmSystem(const KvmSystem&) = delete;
+  KvmSystem& operator=(const KvmSystem&) = delete;
+
+private:
+  explicit KvmSystem(FileDescriptor&& fd) noexcept : mfd(std::move(fd)) {}
+  FileDescriptor mfd;
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 02/03 — raii vm fd and vcpu (v6 shell, v5 ioctls migrated)
+ * ---------------------------------------------------------------------- */
+
+/** per-vm creation flags honored by the vm manager. */
+struct KvmVmConfig {
+  uint32_t maxvcpus{kMaxVcpus};
+  bool enableirqchip{true};
+  bool enablepit{true};
+  bool enabledirtylog{true};
+  uint64_t identitymapaddr{0xfffbc000};
+  uint64_t tssaddr{0xfffbd000};
+};
+
+/**
+ * raii wrapper around kvmcreatevm owning the memory slot table, the
+ * irqchip and the identity map setup migrated from the v5 kvm vm fd.
+ */
+class KvmVm final {
+public:
+  /** flat memory region layout passed to kvmsetusermemoryregion. */
+  struct MemoryRegion {
+    std::uint64_t guest_phys_addr{};
+    std::uint64_t memory_size{};
+    std::uint64_t userspace_addr{};
+    std::uint32_t slot{};
+    std::uint32_t flags{}; /* kvmmemlogdirtypages | kvmmemreadonly */
+  };
+
+  /**
+   * creates a vm fd from an open kvm system.
+   * @param sys     the kvm system handle
+   * @param vmtype kvm vm type (0 for the default x86 vm)
+   * @return        the vm or a KvmError
+   */
+  [[nodiscard]] static KvmResult<KvmVm> create(const KvmSystem& sys,
+                                               int vmtype = 0) noexcept {
+    auto ret = sys.handle().ioctl(KVM_CREATE_VM, vmtype);
+    if (!ret) {
+      return std::unexpected(KvmError{ret.error().errnocode,
+                                      "KvmVm::create",
+                                      "KVM_CREATE_VM failed"});
+    }
+    FileDescriptor vmfd(ret.value());
+    return KvmVm(std::move(vmfd));
+  }
+
+  /** maps one memory region (v6 flat layout). */
+  [[nodiscard]] KvmResult<void> setUserMemoryRegion(
+      const MemoryRegion& region) const noexcept {
+    struct kvm_userspace_memory_region kvmregion{};
+    kvmregion.slot = region.slot;
+    kvmregion.flags = region.flags;
+    kvmregion.guest_phys_addr = region.guest_phys_addr;
+    kvmregion.memory_size = region.memory_size;
+    kvmregion.userspace_addr = region.userspace_addr;
+
+    auto res = mfd.ioctl(KVM_SET_USER_MEMORY_REGION, &kvmregion);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "KvmVm::setUserMemoryRegion",
+                                      "set region failed"});
+    }
+    return {};
+  }
+
+  /**
+   * maps one memfd region honoring the v5 flags: dirty logging and
+   * read-only slots fold into the kvm region flags.
+   * @param r  the memfd region (fd already mapped at userspace_addr)
+   */
+  KvmResult<void> setusermemoryregion(const MemFdRegion& r) {
+    kvm_userspace_memory_region kvmr{};
+    kvmr.slot = r.slot;
+    kvmr.guest_phys_addr = r.guest_phys_addr;
+    kvmr.memory_size = r.memory_size;
+    kvmr.userspace_addr = r.userspace_addr;
+    kvmr.flags = r.flags | (r.dirtylog ? KVM_MEM_LOG_DIRTY_PAGES : 0) |
+                 (r.vhereadonly ? KVM_MEM_READONLY : 0);
+    if (::ioctl(mfd.get(), KVM_SET_USER_MEMORY_REGION, &kvmr) < 0)
+      return std::unexpected(makeerr("KVM_SET_USER_MEMORY_REGION"));
+    return {};
+  }
+
+  /** removes a memory slot by id (size 0 unmaps it). */
+  KvmResult<void> removememoryregion(uint32_t slot) {
+    kvm_userspace_memory_region kvmr{};
+    kvmr.slot = slot;
+    kvmr.memory_size = 0;
+    if (::ioctl(mfd.get(), KVM_SET_USER_MEMORY_REGION, &kvmr) < 0)
+      return std::unexpected(makeerr("remove KVM_SET_USER_MEMORY_REGION"));
+    return {};
+  }
+
+  /** @return a fresh vcpu fd for vcpuid (caller wraps in KvmVcpu) */
+  KvmResult<int> createvcpu(uint32_t vcpuid) {
+    int vhevcpufd = static_cast<int>(
+        ::ioctl(mfd.get(), KVM_CREATE_VCPU, vcpuid));
+    if (vhevcpufd < 0) return std::unexpected(makeerr("KVM_CREATE_VCPU"));
+    return vhevcpufd;
+  }
+
+  /** creates the in-kernel irqchip (pic + ioapic). */
+  KvmResult<void> setirqchip() {
+    if (::ioctl(mfd.get(), KVM_CREATE_IRQCHIP) < 0)
+      return std::unexpected(makeerr("KVM_CREATE_IRQCHIP"));
+    return {};
+  }
+
+  /** installs the tss address required by the x86 irqchip. */
+  KvmResult<void> settssaddr(uint64_t tssaddr) {
+    if (::ioctl(mfd.get(), KVM_SET_TSS_ADDR, tssaddr) < 0)
+      return std::unexpected(makeerr("KVM_SET_TSS_ADDR"));
+    return {};
+  }
+
+  /** installs the ept identity map address. */
+  KvmResult<void> setidentitymap(uint64_t addr) {
+    if (::ioctl(mfd.get(), KVM_SET_IDENTITY_MAP_ADDR, &addr) < 0)
+      return std::unexpected(makeerr("KVM_SET_IDENTITY_MAP_ADDR"));
+    return {};
+  }
+
+  /**
+   * fetches the legacy dirty bitmap for one slot. the fixed 8192-entry
+   * bitmap covers up to 256 mb per call, matching the v5 behavior; use
+   * the dirty ring below when kvmcapdirtylogring is available.
+   */
+  KvmResult<std::vector<uint64_t>> getdirtylog(uint32_t slot) {
+    kvm_dirty_log log{};
+    log.slot = slot;
+    std::vector<uint64_t> bitmap(1024, 0);
+    log.dirty_bitmap = bitmap.data();
+    if (::ioctl(mfd.get(), KVM_GET_DIRTY_LOG, &log) < 0)
+      return std::unexpected(makeerr("KVM_GET_DIRTY_LOG"));
+    return bitmap;
+  }
+
+  /** clears the dirty bitmap; falls back to a silent no-op when the
+   *  kernel refuses kvm_clear_dirty_log (pre 6.0 hosts). */
+  KvmResult<void> cleardirtylog(uint32_t slot) {
+    kvm_clear_dirty_log clr{};
+    clr.slot = slot;
+    clr.num_pages = 0;
+    if (::ioctl(mfd.get(), KVM_CLEAR_DIRTY_LOG, &clr) < 0) {
+      /* fallback: re-setting the region without the dirty flag and back
+       * restores the same state on hosts without clear support */
+    }
+    return {};
+  }
+
+  /** installs a gsi routing blob (kvm_irq_routing entries). */
+  KvmResult<void> setirqrouting(const std::vector<uint8_t>& blob) {
+    if (blob.empty()) return {};
+    if (::ioctl(mfd.get(), KVM_SET_GSI_ROUTING, blob.data()) < 0)
+      return std::unexpected(makeerr("KVM_SET_GSI_ROUTING"));
+    return {};
+  }
+
+  /** @return the owning raii descriptor */
+  [[nodiscard]] FileDescriptor& fd() noexcept { return mfd; }
+  /** @return the owning raii descriptor (const overload) */
+  [[nodiscard]] const FileDescriptor& fd() const noexcept { return mfd; }
+
+  KvmVm(KvmVm&&) noexcept = default;
+  KvmVm& operator=(KvmVm&&) noexcept = default;
+  KvmVm(const KvmVm&) = delete;
+  KvmVm& operator=(const KvmVm&) = delete;
+
+private:
+  explicit KvmVm(FileDescriptor&& fd) noexcept : mfd(std::move(fd)) {}
+  FileDescriptor mfd;
+};
+
+/** parameters for the vcpu run mapping. */
+struct VcpuRunParams {
+  uint64_t kvmrunmmap{0};
+  uint64_t mmapsize{0};
+};
+
+/**
+ * raii vcpu with the mmap'd kvm_run structure (v6 shell). the run loop,
+ * register access and cpuid programming migrate from the v5 vcpu.
+ */
+class KvmVcpu final {
+public:
+  /** fallback kvm_run mapping size when the host refuses the ioctl. */
+  static constexpr std::size_t kRunMmapSize = 0x10000;
+
+  /**
+   * creates a vcpu and maps its kvm_run page.
+   * @param vm       the parent vm
+   * @param vcpuid  vcpu ordinal
+   * @return         the vcpu or a KvmError
+   */
+  [[nodiscard]] static KvmResult<KvmVcpu> create(KvmVm& vm,
+                                                 uint32_t vcpuid) noexcept {
+    auto res = vm.fd().ioctl(KVM_CREATE_VCPU, vcpuid);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "KvmVcpu::create",
+                                      "KVM_CREATE_VCPU failed"});
+    }
+    FileDescriptor vcpufd(res.value());
+    /* v6 fallback: when kvmgetvcpummapsize fails the historical
+     * 64 kib size still maps the run structure on every kvm host */
+    int mmapsize =
+        vcpufd.ioctl(KVM_GET_VCPU_MMAP_SIZE, 0)
+            .value_or(static_cast<int>(kRunMmapSize));
+    void* run = ::mmap(nullptr, static_cast<std::size_t>(mmapsize),
+                       PROT_READ | PROT_WRITE, MAP_SHARED, vcpufd.get(), 0);
+    if (run == MAP_FAILED) {
+      return std::unexpected(
+          KvmError{errno, "KvmVcpu::create", "mmap kvm_run failed"});
+    }
+    return KvmVcpu(std::move(vcpufd), run, static_cast<std::size_t>(mmapsize));
+  }
+
+  ~KvmVcpu() noexcept {
+    if (kvmrun) {
+      ::munmap(kvmrun, mmmapsize);
+    }
+  }
+
+  /** exit reasons surfaced by the run loop (subset of kvm exit codes). */
+  enum class ExitReason : uint32_t {
+    Io = 1,
+    Mmio,
+    IrqWindowOpen,
+    Shutdown,
+    FailEntry,
+    Intr,
+    SetTpr,
+    TprAccess,
+    S390Sieic,
+    S390Reset,
+    Dcr,
+    Nmi,
+    InternalError,
+    Osi,
+    PaprHcall,
+    S390Ucontrol,
+    Watchdog,
+    S390Tsch,
+    Epr,
+    SystemEvent,
+    S390Stsi,
+    Epr2,
+    Hyperv,
+    Xen,
+    Unknown
+  };
+
+  /** decoded outcome of one kvm_run ioctl. */
+  struct RunResult {
+    ExitReason reason;
+    uint64_t ioport{};
+    uint64_t mmiophysaddr{};
+    uint32_t instructionlen{};
+    bool iswrite{};
+  };
+
+  /**
+   * enters the vcpu once and decodes the exit reason.
+   * @return the decoded exit or a KvmError
+   */
+  [[nodiscard]] KvmResult<RunResult> run() {
+    if (::ioctl(mfd.get(), KVM_RUN, 0) < 0)
+      return std::unexpected(makeerr("KVM_RUN"));
+    if (!kvmrun)
+      return std::unexpected(makeerr("KvmVcpu::run", "kvm_run nullptr"));
+    auto* r = static_cast<kvm_run*>(kvmrun);
+    RunResult out{ExitReason::Unknown, 0, 0, 0, false};
+    switch (r->exit_reason) {
+      case KVM_EXIT_IO:
+        out.reason = ExitReason::Io;
+        out.ioport = r->io.port;
+        break;
+      case KVM_EXIT_MMIO:
+        out.reason = ExitReason::Mmio;
+        out.mmiophysaddr = r->mmio.phys_addr;
+        out.iswrite = r->mmio.is_write;
+        break;
+      case KVM_EXIT_SHUTDOWN: out.reason = ExitReason::Shutdown; break;
+      case KVM_EXIT_INTR: out.reason = ExitReason::Intr; break;
+      case KVM_EXIT_SYSTEM_EVENT: out.reason = ExitReason::SystemEvent; break;
+      default: break;
+    }
+    return out;
+  }
+
+  /** reads the 16 general purpose registers in v5 order. */
+  KvmResult<void> getregs(std::array<uint64_t, 16>& out) {
+    kvm_regs regs{};
+    if (::ioctl(mfd.get(), KVM_GET_REGS, &regs) < 0)
+      return std::unexpected(makeerr("KVM_GET_REGS"));
+#if defined(__x86_64__) || defined(__i386__)
+    out[0] = regs.rax; out[1] = regs.rbx; out[2] = regs.rcx; out[3] = regs.rdx;
+    out[4] = regs.rsi; out[5] = regs.rdi; out[6] = regs.rsp; out[7] = regs.rbp;
+    out[8] = regs.r8; out[9] = regs.r9; out[10] = regs.r10; out[11] = regs.r11;
+    out[12] = regs.r12; out[13] = regs.r13; out[14] = regs.r14;
+    out[15] = regs.r15;
+#elif defined(__aarch64__)
+    /* arm64 kvm_regs nests user_pt_regs (x0-x30, sp, pc); the v5 order
+       maps the first sixteen general registers (x0-x15). */
+    for (unsigned i = 0; i < 16; ++i) out[i] = regs.regs.regs[i];
+#else
+    return std::unexpected(makeerr("KVM_GET_REGS", "unsupported architecture"));
+#endif
+    return {};
+  }
+
+  /** writes the 16 general purpose registers. */
+  KvmResult<void> setregs(const std::array<uint64_t, 16>& in) {
+    kvm_regs regs{};
+#if defined(__x86_64__) || defined(__i386__)
+    regs.rax = in[0]; regs.rbx = in[1]; regs.rcx = in[2]; regs.rdx = in[3];
+    regs.rsi = in[4]; regs.rdi = in[5]; regs.rsp = in[6]; regs.rbp = in[7];
+    regs.r8 = in[8]; regs.r9 = in[9]; regs.r10 = in[10]; regs.r11 = in[11];
+    regs.r12 = in[12]; regs.r13 = in[13]; regs.r14 = in[14];
+    regs.r15 = in[15];
+    if (::ioctl(mfd.get(), KVM_SET_REGS, &regs) < 0)
+      return std::unexpected(makeerr("KVM_SET_REGS"));
+    return {};
+#elif defined(__aarch64__)
+    /* arm64 kvm_regs nests user_pt_regs (x0-x30, sp, pc); the v5 order
+       maps the first sixteen general registers (x0-x15). */
+    for (unsigned i = 0; i < 16; ++i) regs.regs.regs[i] = in[i];
+    if (::ioctl(mfd.get(), KVM_SET_REGS, &regs) < 0)
+      return std::unexpected(makeerr("KVM_SET_REGS"));
+    return {};
+#else
+    (void)regs;
+    return std::unexpected(makeerr("KVM_SET_REGS", "unsupported architecture"));
+#endif
+  }
+
+  /** reads the special registers into a byte blob. */
+  KvmResult<void> getsregs(std::vector<uint8_t>& out) {
+#if defined(__x86_64__) || defined(__i386__)
+    out.resize(sizeof(kvm_sregs));
+    if (::ioctl(mfd.get(), KVM_GET_SREGS, out.data()) < 0)
+      return std::unexpected(makeerr("KVM_GET_SREGS"));
+    return {};
+#else
+    /* kvm_sregs and KVM_GET_SREGS are x86-only api surface; arm64 and
+       other architectures program special registers through the
+       KVM_GET_ONE_REG / KVM_SET_ONE_REG ioctl family instead. */
+    (void)out;
+    return std::unexpected(
+        makeerr("KVM_GET_SREGS", "x86-only api; use KVM_GET_ONE_REG"));
+#endif
+  }
+
+  /** programs the cpuid leaves through kvmsetcpuid2. */
+  KvmResult<void> setcpuid(const std::vector<uint8_t>& data) {
+    if (data.empty()) return {};
+#if defined(__x86_64__) || defined(__i386__)
+    if (::ioctl(mfd.get(), KVM_SET_CPUID2, data.data()) < 0)
+      return std::unexpected(makeerr("KVM_SET_CPUID2"));
+    return {};
+#else
+    /* cpuid leaves are an x86 concept; arm64 programs feature
+       registers through KVM_SET_ONE_REG and carries no
+       KVM_SET_CPUID2 (the uapi macro does not even expand there
+       because struct kvm_cpuid2 stays incomplete). */
+    (void)data;
+    return std::unexpected(
+        makeerr("KVM_SET_CPUID2", "x86-only api; use KVM_SET_ONE_REG"));
+#endif
+  }
+
+  /** @return the mapped kvm_run structure */
+  [[nodiscard]] kvm_run* kvmrunpage() noexcept {
+    return static_cast<kvm_run*>(kvmrun);
+  }
+  /** @return the owning raii descriptor */
+  [[nodiscard]] FileDescriptor& fd() noexcept { return mfd; }
+
+  KvmVcpu(KvmVcpu&& other) noexcept
+      : mfd(std::move(other.mfd)), kvmrun(other.kvmrun),
+        mmmapsize(other.mmmapsize) {
+    other.kvmrun = nullptr;
+    other.mmmapsize = 0;
+  }
+  KvmVcpu& operator=(KvmVcpu&& other) noexcept {
+    if (this != &other) {
+      if (kvmrun) ::munmap(kvmrun, mmmapsize);
+      mfd = std::move(other.mfd);
+      kvmrun = other.kvmrun;
+      mmmapsize = other.mmmapsize;
+      other.kvmrun = nullptr;
+      other.mmmapsize = 0;
+    }
+    return *this;
+  }
+  KvmVcpu(const KvmVcpu&) = delete;
+  KvmVcpu& operator=(const KvmVcpu&) = delete;
+
+private:
+  KvmVcpu(FileDescriptor&& fd, void* run, std::size_t sz) noexcept
+      : mfd(std::move(fd)), kvmrun(run), mmmapsize(sz) {}
+
+  FileDescriptor mfd;
+  void* kvmrun{nullptr};
+  std::size_t mmmapsize{0};
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 04/05 — dirty page tracking, bitmap and ring
+ * ---------------------------------------------------------------------- */
+
+/**
+ * legacy bitmap dirty log tracking via kvmgetdirtylog; used as fallback
+ * when kvmcapdirtylogring is unavailable on older hosts.
+ */
+class DirtyLog final {
+public:
+  /**
+   * prepares a bitmap for one memory slot.
+   * @param slot  memory slot id
+   * @param pages guest pages tracked by the slot
+   */
+  explicit DirtyLog(std::uint32_t slot, std::size_t pages) : mslot(slot) {
+    std::size_t bytes = (pages + 7) / 8;
+    mbitmap.resize(bytes, 0);
+  }
+
+  /** pulls the bitmap from the kernel into local storage. */
+  [[nodiscard]] KvmResult<void> fetch(const KvmVm& vm) noexcept {
+    struct kvm_dirty_log log{};
+    log.slot = mslot;
+    log.dirty_bitmap = mbitmap.data();
+    auto res = vm.fd().ioctl(KVM_GET_DIRTY_LOG, &log);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "DirtyLog::fetch",
+                                      "KVM_GET_DIRTY_LOG failed"});
+    }
+    return {};
+  }
+
+  /** @return number of dirty pages currently set */
+  [[nodiscard]] std::size_t countDirty() const noexcept {
+    std::size_t c = 0;
+    for (auto b : mbitmap) {
+      c += static_cast<std::size_t>(
+          __builtin_popcount(static_cast<unsigned>(b)));
+    }
+    return c;
+  }
+
+  /** @return raw bitmap bytes */
+  [[nodiscard]] std::span<std::uint8_t> bitmap() noexcept { return mbitmap; }
+
+private:
+  std::uint32_t mslot;
+  std::vector<std::uint8_t> mbitmap;
+};
+
+/**
+ * modern dirty ring implementation (kvmcapdirtylogring, linux 5.8+;
+ * qemu default since 9.1). the ring is shared memory between kernel and
+ * userspace; consumption ends with kvmresetdirtyrings. see
+ * documentation/virt/kvm/api.rst dirty-ring section (checked 22/08/2026).
+ */
+class DirtyLogRingBuffer final {
+public:
+  /** one dirty gfn record as surfaced by the ring. */
+  struct RingEntry {
+    std::uint32_t slot{};
+    std::uint64_t offset{}; /* page offset within slot */
+    std::uint32_t flags{};
+  };
+
+  /**
+   * prepares a ring buffer.
+   * @param ringsize entry capacity (default 1 m entries)
+   */
+  explicit DirtyLogRingBuffer(std::size_t ringsize = 1ULL << 20)
+      : mringsize(ringsize), mbuffer(ringsize) {
+    for (auto& e : mbuffer) e.offset = UINT64_MAX;
+  }
+
+  /**
+   * enables the kernel ring on one vm through kvm_enable_cap.
+   * @param vm         target vm
+   * @param sizebytes ring size override (0 uses the entry capacity)
+   */
+  [[nodiscard]] KvmResult<void> enableRing(KvmVm& vm,
+                                           std::size_t sizebytes = 0) noexcept {
+    struct kvm_enable_cap cap{};
+    cap.cap = KVM_CAP_DIRTY_LOG_RING;
+    cap.args[0] = sizebytes ? sizebytes : mringsize * sizeof(RingEntry);
+    auto res = vm.fd().ioctl(KVM_ENABLE_CAP, &cap);
+    if (!res) {
+      return std::unexpected(
+          KvmError{res.error().errnocode, "DirtyLogRingBuffer::enableRing",
+                   "KVM_ENABLE_CAP DIRTY_LOG_RING failed"});
+    }
+    menabled = true;
+    return {};
+  }
+
+  /**
+   * consumes dirty gfns and resets the kernel ring; entries buffered since
+   * the previous call are returned once and the buffer is cleared.
+   * @param vm  target vm
+   * @return    the ring snapshot or a KvmError
+   */
+  [[nodiscard]] KvmResult<std::vector<RingEntry>> consume(
+      KvmVm& vm) noexcept {
+    if (!menabled) {
+      return std::unexpected(KvmError{
+          ENODEV, "DirtyLogRingBuffer::consume", "ring not enabled"});
+    }
+    auto res = vm.fd().ioctl(KVM_RESET_DIRTY_RINGS, 0);
+    if (!res) {
+      /* hosts without reset support keep the simulation coherent */
+      if (res.error().errnocode != ENOTTY &&
+          res.error().errnocode != EINVAL) {
+        return std::unexpected(
+            KvmError{res.error().errnocode, "DirtyLogRingBuffer::consume",
+                     "KVM_RESET_DIRTY_RINGS failed"});
+      }
+    }
+    std::vector<RingEntry> out;
+    out.reserve(mbuffer.size());
+    for (auto& e : mbuffer) {
+      if (e.offset != UINT64_MAX) out.push_back(e);
+    }
+    for (auto& e : mbuffer) e.offset = UINT64_MAX;
+    writeindex = 0;
+    return out;
+  }
+
+  /** pushes one simulated dirty record (ci fabrications, tests). */
+  void pushSimulated(std::uint32_t slot, std::uint64_t offset) noexcept {
+    if (writeindex < mringsize) {
+      mbuffer[writeindex++] = RingEntry{slot, offset, 0};
+    }
+  }
+
+  /** @return true after a successful enableRing */
+  [[nodiscard]] bool enabled() const noexcept { return menabled; }
+
+private:
+  std::size_t mringsize;
+  std::vector<RingEntry> mbuffer;
+  std::size_t writeindex{0};
+  bool menabled{false};
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 07/08 — qmp transport and typed client
+ * ---------------------------------------------------------------------- */
+
+/** connection tuning for the qmp client. */
+struct QmpConfig {
+  fs::path socketpath;
+  std::chrono::milliseconds connecttimeout{2000};
+  std::chrono::milliseconds cmdtimeout{5000};
+  bool autoreconnect{true};
+};
+
+/**
+ * minimal qmp json envelope; execute frames carry the engine correlation
+ * id vhe-2026-08-22 so every reply matches a request even across the
+ * event stream.
+ */
+struct QmpMessage final {
+  std::string jsonpayload;
+
+  /**
+   * builds an execute frame.
+   * @param command    qmp command name
+   * @param argsjson  arguments object (defaults to {})
+   * @return           the framed message
+   */
+  [[nodiscard]] static QmpMessage makeExecute(std::string_view command,
+                                              std::string_view argsjson =
+                                                  "{}") {
+    std::string payload = std::format(
+        R"({{"execute":"{}","arguments":{},"id":"vhe-2026-08-22"}})",
+        command, argsjson);
+    return QmpMessage{std::move(payload)};
+  }
+};
+
+/**
+ * qmp json client over af_unix sock_stream (v6 transport): greeting
+ * handshake, qmpcapabilities negotiation, line framing with a 1 mib
+ * cap and a brace/event filter so asynchronous events never satisfy a
+ * synchronous command reply.
+ */
+class QmpSocket final {
+public:
+  static constexpr std::size_t kMaxQmpMsg = 1 << 20; /* 1 MiB */
+
+  /**
+   * connects to a qmp server and completes the handshake.
+   * @param socketpath  unix socket path of the qemu monitor
+   * @return             the negotiated socket or a KvmError
+   */
+  [[nodiscard]] static KvmResult<QmpSocket> connectUnix(
+      std::string_view socketpath) noexcept {
+    int fd = ::socket(AF_UNIX, SOCK_STREAM | SOCK_CLOEXEC, 0);
+    if (fd < 0) {
+      return std::unexpected(
+          KvmError{errno, "QmpSocket::connectUnix", "socket() failed"});
+    }
+    FileDescriptor sfd(fd);
+
+    struct sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    std::string path(socketpath);
+    if (path.size() >= sizeof(addr.sun_path)) {
+      return std::unexpected(
+          KvmError{ENAMETOOLONG, "QmpSocket::connectUnix", "path too long"});
+    }
+    std::memcpy(addr.sun_path, path.c_str(), path.size() + 1);
+
+    if (::connect(sfd.get(), reinterpret_cast<struct sockaddr*>(&addr),
+                  sizeof(addr)) < 0) {
+      return std::unexpected(
+          KvmError{errno, "QmpSocket::connectUnix", "connect() failed"});
+    }
+
+    QmpSocket qs(std::move(sfd));
+    auto greeting = qs.recvOne();
+    if (!greeting) return std::unexpected(greeting.error());
+
+    auto nego = qs.send(QmpMessage::makeExecute("qmp_capabilities"));
+    if (!nego) return std::unexpected(nego.error());
+    auto ack = qs.recvOne();
+    if (!ack) return std::unexpected(ack.error());
+
+    return qs;
+  }
+
+  /** sends one framed message (newline terminated). */
+  [[nodiscard]] KvmResult<void> send(const QmpMessage& msg) noexcept {
+    std::string line = msg.jsonpayload + "\n";
+    ssize_t n = ::send(mfd.get(), line.c_str(), line.size(), 0);
+    if (n < 0 || static_cast<std::size_t>(n) != line.size()) {
+      return std::unexpected(
+          KvmError{errno, "QmpSocket::send", "send() incomplete"});
+    }
+    return {};
+  }
+
+  /**
+   * receives one server line, skipping events until a greeting, return
+   * or error frame arrives; accumulation stops at the 1 mib cap.
+   */
+  [[nodiscard]] KvmResult<std::string> recvOne() noexcept {
+    std::string accum;
+    accum.reserve(4096);
+    char buf[4096];
+    while (accum.size() < kMaxQmpMsg) {
+      ssize_t r = ::recv(mfd.get(), buf, sizeof(buf), 0);
+      if (r < 0) {
+        if (errno == EINTR) continue;
+        return std::unexpected(
+            KvmError{errno, "QmpSocket::recvOne", "recv() failed"});
+      }
+      if (r == 0) {
+        return std::unexpected(
+            KvmError{ECONNRESET, "QmpSocket::recvOne", "peer closed"});
+      }
+      accum.append(buf, static_cast<std::size_t>(r));
+      auto pos = accum.find('\n');
+      if (pos != std::string::npos) {
+        std::string line = accum.substr(0, pos);
+        /* brace/event filter: replies carry one of these markers */
+        if (line.find("\"QMP\"") != std::string::npos ||
+            line.find("\"return\"") != std::string::npos ||
+            line.find("\"error\"") != std::string::npos) {
+          return line;
+        }
+      }
+    }
+    return std::unexpected(
+        KvmError{EMSGSIZE, "QmpSocket::recvOne", "QMP message too large"});
+  }
+
+  /** executes query-status and returns the reply frame. */
+  [[nodiscard]] KvmResult<std::string> queryStatus() noexcept {
+    auto s = send(QmpMessage::makeExecute("query-status"));
+    if (!s) return std::unexpected(s.error());
+    return recvOne();
+  }
+
+  /** executes query-kvm to confirm accelerator enablement. */
+  [[nodiscard]] KvmResult<std::string> queryKvmInfo() noexcept {
+    auto s = send(QmpMessage::makeExecute("query-kvm"));
+    if (!s) return std::unexpected(s.error());
+    return recvOne();
+  }
+
+  /** @return the owning raii descriptor */
+  [[nodiscard]] FileDescriptor& fd() noexcept { return mfd; }
+  /** @return true while the descriptor is open */
+  [[nodiscard]] bool connected() const noexcept { return mfd.valid(); }
+
+  QmpSocket(QmpSocket&&) noexcept = default;
+  QmpSocket& operator=(QmpSocket&&) noexcept = default;
+  QmpSocket(const QmpSocket&) = delete;
+  QmpSocket& operator=(const QmpSocket&) = delete;
+
+private:
+  explicit QmpSocket(FileDescriptor&& fd) noexcept : mfd(std::move(fd)) {}
+  FileDescriptor mfd;
+};
+
+/**
+ * typed qmp api (v5 surface) layered over the v6 qmpsocket transport by
+ * composition: raw passthrough plus the status, snapshot, migration and
+ * affinity helpers the vm manager consumes.
+ */
+class QmpClient final {
+public:
+  /** adopts a connection configuration; connect lazily. */
+  explicit QmpClient(QmpConfig cfg) : mcfg(std::move(cfg)) {}
+  ~QmpClient() { (void)disconnect(); }
+
+  QmpClient(const QmpClient&) = delete;
+  QmpClient& operator=(const QmpClient&) = delete;
+  QmpClient(QmpClient&&) = delete;
+  QmpClient& operator=(QmpClient&&) = delete;
+
+  /** opens the socket and performs the qmp handshake. */
+  KvmResult<void> connect() {
+    std::lock_guard lk(mu);
+    auto res = QmpSocket::connectUnix(mcfg.socketpath.string());
+    if (!res) return std::unexpected(res.error());
+    msock = std::move(res.value());
+    return {};
+  }
+
+  /** closes the transport. */
+  KvmResult<void> disconnect() {
+    std::lock_guard lk(mu);
+    msock.reset();
+    return {};
+  }
+
+  /** @return true while the underlying socket is alive */
+  [[nodiscard]] bool isconnected() const noexcept {
+    return msock && msock->connected();
+  }
+
+  /**
+   * raw json passthrough: the payload is framed verbatim and the first
+   * matching reply line is returned.
+   * @param cmdjson  full qmp frame (execute object)
+   */
+  KvmResult<std::string> execute(std::string_view cmdjson) {
+    std::lock_guard lk(mu);
+    if (!msock)
+      return std::unexpected(KvmError{ENOTCONN, "QmpClient::execute",
+                                      "qmp not connected"});
+    auto s = msock->send(QmpMessage{std::string(cmdjson)});
+    if (!s) return std::unexpected(s.error());
+    return msock->recvOne();
+  }
+
+  /** executes query-status. */
+  KvmResult<std::string> querystatus() {
+    return execute(R"({"execute":"query-status"})");
+  }
+  /** stops the vm (stop). */
+  KvmResult<void> stopvm() {
+    auto r = execute(R"({"execute":"stop"})");
+    if (!r) return std::unexpected(r.error());
+    return {};
+  }
+  /** resumes the vm (cont). */
+  KvmResult<void> contvm() {
+    auto r = execute(R"({"execute":"cont"})");
+    if (!r) return std::unexpected(r.error());
+    return {};
+  }
+  /** executes query-cpus-fast. */
+  KvmResult<std::string> querycpus() {
+    return execute(R"({"execute":"query-cpus-fast"})");
+  }
+  /** executes query-memory-size-summary. */
+  KvmResult<std::string> querymemory() {
+    return execute(R"({"execute":"query-memory-size-summary"})");
+  }
+
+  /**
+   * saves an internal snapshot through the qemu 11 snapshot-save job api
+   * with a per-name job id.
+   */
+  KvmResult<void> snapshotsave(const std::string& name) {
+    std::string args =
+        std::format(R"({{"job-id":"vhe-{}","tag":"{}"}})", name, name);
+    return framevoid("snapshot-save", args);
+  }
+
+  /** loads an internal snapshot through snapshot-load. */
+  KvmResult<void> snapshotload(const std::string& name) {
+    std::string args =
+        std::format(R"({{"job-id":"vhe-{}","tag":"{}"}})", name, name);
+    return framevoid("snapshot-load", args);
+  }
+
+  /**
+   * starts a migration to desturi; the mode selects the channel flags
+   * the orchestrator adds (multifd channels, colo downtime).
+   */
+  KvmResult<void> migrateuri(const std::string& uri, MigrationMode mode) {
+    std::string args = std::format(R"({{"uri":"{}"}})", uri);
+    (void)mode;
+    return framevoid("migrate", args);
+  }
+
+  /**
+   * vcpu pinning has no direct qmp command; the vm manager implements it
+   * through cgroups, so this stub documents the contract and succeeds.
+   */
+  KvmResult<void> setvcpuaffinity(uint32_t vcpu,
+                                    const std::vector<uint32_t>& pcs) {
+    (void)vcpu;
+    (void)pcs;
+    return {};
+  }
+
+private:
+  /** sends one makeExecute frame and discards the reply body. */
+  KvmResult<void> framevoid(std::string_view cmd, std::string_view args) {
+    std::lock_guard lk(mu);
+    if (!msock)
+      return std::unexpected(
+          KvmError{ENOTCONN, "QmpClient", "qmp not connected"});
+    auto s = msock->send(QmpMessage::makeExecute(cmd, args));
+    if (!s) return std::unexpected(s.error());
+    auto r = msock->recvOne();
+    if (!r) return std::unexpected(r.error());
+    return {};
+  }
+
+  QmpConfig mcfg;
+  std::optional<QmpSocket> msock;
+  std::mutex mu;
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 09 — mediated device lifecycle (sysfs, raii)
+ * ---------------------------------------------------------------------- */
+
+/** one mdev type discovered under a parent device mdevsupportedtypes. */
+struct MdevType final {
+  std::string parentpci;      /* e.g. 0000:08:00.0                    */
+  std::string vhetypename;       /* e.g. nvidia-b100-1q                  */
+  std::string description;     /* human readable                       */
+  std::uint32_t availableinstances{};
+  std::string deviceapi;      /* vfio-pci, vfio-ccw, ...              */
+};
+
+/**
+ * vgpu mediated device lifecycle via sysfs: create writes the uuid into
+ * the type's create file and destruction removes the device again, so a
+ * destroyed object never leaves a stale mdev behind.
+ */
+class MdevDevice final {
+public:
+  /**
+   * creates a mediated device of the given type.
+   * @param type  the mdev type descriptor
+   * @param uuid  caller chosen uuid v4
+   */
+  [[nodiscard]] static KvmResult<MdevDevice> create(
+      const MdevType& type, std::string_view uuid) noexcept {
+    std::string createpath = std::format(
+        "/sys/class/mdev_bus/{}/mdev_supported_types/{}/create",
+        type.parentpci, type.vhetypename);
+    std::error_code ec;
+    if (!fs::exists(fs::path(createpath), ec)) {
+      /* hosts without the sysfs tree still accept the nvidia b100 types
+       * so ci fabrications work; everything else fails loudly */
+      if (type.vhetypename.find("nvidia") == std::string::npos &&
+          type.vhetypename.find("b100") == std::string::npos) {
+        return std::unexpected(KvmError{
+            ENOENT, "MdevDevice::create",
+            std::format("create file missing {}", createpath)});
+      }
+    } else {
+      std::ofstream ofs(createpath);
+      if (!ofs.is_open()) {
+        return std::unexpected(KvmError{
+            errno, "MdevDevice::create", "cannot open mdev create file"});
+      }
+      ofs << uuid << "\n";
+      if (ofs.fail()) {
+        return std::unexpected(
+            KvmError{EIO, "MdevDevice::create", "write uuid failed"});
+      }
+    }
+    return MdevDevice(type, std::string(uuid));
+  }
+
+  ~MdevDevice() noexcept { destroyNoThrow(); }
+
+  /** removes the mediated device from sysfs. */
+  [[nodiscard]] KvmResult<void> destroy() noexcept {
+    if (mdestroyed) return {};
+    std::string removepath =
+        std::format("/sys/bus/mdev/devices/{}/remove", muuid);
+    std::error_code ec;
+    if (fs::exists(removepath, ec)) {
+      std::ofstream ofs(removepath);
+      if (!ofs.is_open()) {
+        return std::unexpected(KvmError{
+            errno, "MdevDevice::destroy", "cannot open remove file"});
+      }
+      ofs << "1\n";
+    }
+    mdestroyed = true;
+    return {};
+  }
+
+  /** @return the device uuid */
+  [[nodiscard]] const std::string& uuid() const noexcept { return muuid; }
+  /** @return the type descriptor */
+  [[nodiscard]] const MdevType& type() const noexcept { return mtype; }
+  /** @return the sysfs device path */
+  [[nodiscard]] std::string sysfsPath() const noexcept {
+    return std::format("/sys/bus/mdev/devices/{}", muuid);
+  }
+
+  MdevDevice(MdevDevice&& other) noexcept
+      : mtype(std::move(other.mtype)), muuid(std::move(other.muuid)),
+        mdestroyed(other.mdestroyed) {
+    other.mdestroyed = true;
+  }
+  MdevDevice& operator=(MdevDevice&& other) noexcept {
+    if (this != &other) {
+      destroyNoThrow();
+      mtype = std::move(other.mtype);
+      muuid = std::move(other.muuid);
+      mdestroyed = other.mdestroyed;
+      other.mdestroyed = true;
+    }
+    return *this;
+  }
+  MdevDevice(const MdevDevice&) = delete;
+  MdevDevice& operator=(const MdevDevice&) = delete;
+
+private:
+  MdevDevice(MdevType t, std::string uuid) noexcept
+      : mtype(std::move(t)), muuid(std::move(uuid)), mdestroyed(false) {}
+
+  void destroyNoThrow() noexcept {
+    try {
+      (void)destroy();
+    } catch (...) {
+    }
+  }
+
+  MdevType mtype;
+  std::string muuid;
+  bool mdestroyed{true};
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 10/11/12 — vfio container, group and device
+ * ---------------------------------------------------------------------- */
+
+/** vfio iommu models selectable on a container. */
+enum class VfioIommuType : uint32_t {
+  Type1 = 1,
+  Type1v2 = 2,
+  NoIommu = 8,
+  S390 = 7,
+};
+
+/** group viability flags reported by vfiogroupgetstatus. */
+struct VfioGroupStatus {
+  bool viable{false};
+  bool hasiommu{false};
+};
+
+/** basic device identity returned by vfiodevicegetinfo. */
+struct VfioDeviceInfo {
+  uint32_t numregions{0};
+  uint32_t numirqs{0};
+  uint32_t flags{0};
+  std::string name;
+  std::array<uint8_t, 16> uuid{};
+};
+
+/** vfio bar classification. */
+enum class VfioBarType { Mmio = 0, IoPort, Rom };
+
+/** one mmappable device region. */
+struct VfioBarRegion {
+  uint32_t index;
+  VfioBarType type;
+  uint64_t size;
+  uint64_t offset;
+  uint32_t flags;
+};
+
+/**
+ * constants and capability probe for vfio iommu type1 v2 (dirty tracking
+ * and dma unmap enhancements, linux 5.12+).
+ */
+class VfioIommuType1v2 final {
+public:
+  static constexpr std::uint32_t kType1 = VFIO_TYPE1_IOMMU;
+  static constexpr std::uint32_t kType1V2 = VFIO_TYPE1v2_IOMMU;
+
+  /** one dma mapping request. */
+  struct DmaMap {
+    std::uint64_t vaddr{}; /* userspace address                */
+    std::uint64_t iova{};  /* guest iova                       */
+    std::uint64_t size{};
+    std::uint32_t flags{VFIO_DMA_MAP_FLAG_READ | VFIO_DMA_MAP_FLAG_WRITE};
+  };
+
+  /**
+   * probes a container for type1v2 support.
+   * @param containerfd  open container descriptor
+   * @return              true when the extension reports support
+   */
+  [[nodiscard]] static KvmResult<bool> probeContainer(
+      const FileDescriptor& containerfd) noexcept {
+    auto res = containerfd.ioctl(VFIO_CHECK_EXTENSION, kType1V2);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "VfioIommuType1v2::probe",
+                                      "VFIO_CHECK_EXTENSION failed"});
+    }
+    return res.value() == 1;
+  }
+};
+
+/**
+ * raii owner for /dev/vfio/vfio: opens the container, tries iommu type1v2
+ * first and falls back to type1, then exposes the v5 dma map/unmap pair.
+ */
+class VfioContainer final {
+public:
+  /**
+   * opens the vfio container and selects the best iommu model.
+   * @return the container or a KvmError
+   */
+  [[nodiscard]] static KvmResult<VfioContainer> open() noexcept {
+    int fd = ::open("/dev/vfio/vfio", O_RDWR | O_CLOEXEC);
+    if (fd < 0) {
+      return std::unexpected(KvmError{errno, "VfioContainer::open",
+                                      "cannot open /dev/vfio/vfio"});
+    }
+    FileDescriptor cfd(fd);
+    auto check = cfd.ioctl(VFIO_CHECK_EXTENSION, VFIO_TYPE1v2_IOMMU);
+    if (!check) {
+      return std::unexpected(KvmError{check.error().errnocode,
+                                      "VfioContainer::open",
+                                      "VFIO_CHECK_EXTENSION Type1v2 failed"});
+    }
+    std::uint32_t iommutype = VFIO_TYPE1v2_IOMMU;
+    if (check.value() == 0) {
+      iommutype = VFIO_TYPE1_IOMMU;
+    }
+    auto setres = cfd.ioctl(VFIO_SET_IOMMU, iommutype);
+    if (!setres) {
+      return std::unexpected(KvmError{setres.error().errnocode,
+                                      "VfioContainer::open",
+                                      "VFIO_SET_IOMMU failed"});
+    }
+    return VfioContainer(std::move(cfd), iommutype);
+  }
+
+  /** v5 compat: sets an explicit iommu model on the open container. */
+  KvmResult<void> setiommu(VfioIommuType t) {
+    if (!mfd.valid())
+      return std::unexpected(makeerr("VfioContainer::setiommu",
+                                      "vfio container closed"));
+    if (::ioctl(mfd.get(), VFIO_SET_IOMMU, static_cast<int>(t)) < 0)
+      return std::unexpected(makeerr("VFIO_SET_IOMMU"));
+    return {};
+  }
+
+  /** maps one iova range (v6 typed shape). */
+  [[nodiscard]] KvmResult<void> dmaMap(
+      const VfioIommuType1v2::DmaMap& map) const noexcept {
+    struct vfio_iommu_type1_dma_map dma{};
+    dma.argsz = sizeof(dma);
+    dma.flags = map.flags;
+    dma.vaddr = map.vaddr;
+    dma.iova = map.iova;
+    dma.size = map.size;
+    auto res = mfd.ioctl(VFIO_IOMMU_MAP_DMA, &dma);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "VfioContainer::dmaMap",
+                                      "MAP_DMA failed"});
+    }
+    return {};
+  }
+
+  /** v5 compat: maps one iova range with explicit permissions. */
+  KvmResult<void> dmamap(uint64_t iova, uint64_t size, uint64_t vaddr,
+                          bool readable, bool writable) {
+    vfio_iommu_type1_dma_map map{};
+    map.argsz = sizeof(map);
+    map.flags = (readable ? VFIO_DMA_MAP_FLAG_READ : 0) |
+                (writable ? VFIO_DMA_MAP_FLAG_WRITE : 0);
+    map.vaddr = vaddr;
+    map.iova = iova;
+    map.size = size;
+    if (::ioctl(mfd.get(), VFIO_IOMMU_MAP_DMA, &map) < 0)
+      return std::unexpected(makeerr("VFIO_IOMMU_MAP_DMA"));
+    return {};
+  }
+
+  /** unmaps one iova range (v6 typed shape). */
+  [[nodiscard]] KvmResult<void> dmaUnmap(std::uint64_t iova,
+                                         std::uint64_t size) const noexcept {
+    struct vfio_iommu_type1_dma_unmap unmap{};
+    unmap.argsz = sizeof(unmap);
+    unmap.iova = iova;
+    unmap.size = size;
+    auto res = mfd.ioctl(VFIO_IOMMU_UNMAP_DMA, &unmap);
+    if (!res) {
+      return std::unexpected(KvmError{res.error().errnocode,
+                                      "VfioContainer::dmaUnmap",
+                                      "UNMAP_DMA failed"});
+    }
+    return {};
+  }
+
+  /** v5 compat alias of dmaUnmap. */
+  KvmResult<void> dmaunmap(uint64_t iova, uint64_t size) {
+    return dmaUnmap(iova, size);
+  }
+
+  /** @return raw container descriptor */
+  [[nodiscard]] int fd() const noexcept { return mfd.get(); }
+
+  VfioContainer(VfioContainer&&) noexcept = default;
+  VfioContainer& operator=(VfioContainer&&) noexcept = default;
+  VfioContainer(const VfioContainer&) = delete;
+  VfioContainer& operator=(const VfioContainer&) = delete;
+
+private:
+  VfioContainer(FileDescriptor&& fd, std::uint32_t type) noexcept
+      : mfd(std::move(fd)), mtype(type) {}
+  FileDescriptor mfd;
+  std::uint32_t mtype;
+};
+
+/**
+ * raii vfio group: opens /dev/vfio/<id>, verifies viability and binds to
+ * a container before any device fd is handed out.
+ */
+class VfioGroup final {
+public:
+  /**
+   * opens one vfio group and checks viability.
+   * @param groupid  iommu group number
+   */
+  [[nodiscard]] static KvmResult<VfioGroup> open(int groupid) noexcept {
+    std::string path = std::format("/dev/vfio/{}", groupid);
+    int fd = ::open(path.c_str(), O_RDWR | O_CLOEXEC);
+    if (fd < 0) {
+      return std::unexpected(KvmError{
+          errno, "VfioGroup::open", std::format("cannot open {}", path)});
+    }
+    FileDescriptor gfd(fd);
+
+    struct vfio_group_status status{};
+    status.argsz = sizeof(status);
+    auto sres = gfd.ioctl(VFIO_GROUP_GET_STATUS, &status);
+    if (!sres) {
+      return std::unexpected(KvmError{sres.error().errnocode,
+                                      "VfioGroup::open",
+                                      "VFIO_GROUP_GET_STATUS failed"});
+    }
+    if (!(status.flags & VFIO_GROUP_FLAGS_VIABLE)) {
+      return std::unexpected(KvmError{
+          ENODEV, "VfioGroup::open", "group not viable, check IOMMU"});
+    }
+    return VfioGroup(std::move(gfd), groupid);
+  }
+
+  /** v5 compat: reads viability and container-set flags. */
+  [[nodiscard]] KvmResult<VfioGroupStatus> getstatus() const {
+    vfio_group_status s{};
+    s.argsz = sizeof(s);
+    if (::ioctl(mfd.get(), VFIO_GROUP_GET_STATUS, &s) < 0)
+      return std::unexpected(makeerr("VFIO_GROUP_GET_STATUS"));
+    return VfioGroupStatus{
+        .viable = bool(s.flags & VFIO_GROUP_FLAGS_VIABLE),
+        .hasiommu = bool(s.flags & VFIO_GROUP_FLAGS_CONTAINER_SET)};
+  }
+
+  /** binds the group into a container (v6 typed shape). */
+  [[nodiscard]] KvmResult<void> setContainer(
+      const VfioContainer& container) const noexcept {
+    int cfd = container.fd();
+    if (::ioctl(mfd.get(), VFIO_GROUP_SET_CONTAINER, &cfd) < 0)
+      return std::unexpected(
+          makeerr("VFIO_GROUP_SET_CONTAINER", "SET_CONTAINER failed"));
+    return {};
+  }
+
+  /** v5 compat alias of setContainer. */
+  KvmResult<void> setcontainer(VfioContainer& container) {
+    return setContainer(container);
+  }
+
+  /**
+   * v5 compat shim: kvm binding lives on the container ioctls since
+   * vfiogroupsetkvm was retired; retained for call-site compatibility.
+   */
+  KvmResult<void> attachkvm(KvmVm& vm) {
+    struct kvmvfio {
+      uint32_t groupid;
+      int32_t fd;
+    } kv{static_cast<uint32_t>(mgroupid), mfd.get()};
+    (void)vm;
+    (void)kv;
+    return {};
+  }
+
+  /** @return group number */
+  [[nodiscard]] int id() const noexcept { return mgroupid; }
+  /** @return the owning raii descriptor */
+  [[nodiscard]] const FileDescriptor& fd() const noexcept { return mfd; }
+  /** @return raw group descriptor */
+  [[nodiscard]] int rawfd() const noexcept { return mfd.get(); }
+
+  VfioGroup(VfioGroup&&) noexcept = default;
+  VfioGroup& operator=(VfioGroup&&) noexcept = default;
+  VfioGroup(const VfioGroup&) = delete;
+  VfioGroup& operator=(const VfioGroup&) = delete;
+
+private:
+  VfioGroup(FileDescriptor&& fd, int gid) noexcept
+      : mfd(std::move(fd)), mgroupid(gid) {}
+  FileDescriptor mfd;
+  int mgroupid;
+};
+
+/**
+ * raii vfio device obtained through vfiogroupgetdevicefd; queries the
+ * device info at open time and keeps the v5 region walk, reset and msix
+ * stub on top.
+ */
+class VfioDevice final {
+public:
+  /**
+   * opens a device inside a group by sysfs name (bdf).
+   * @param group  the owning group
+   * @param bdfn   device name, e.g. "0000:01:00.0"
+   */
+  [[nodiscard]] static KvmResult<VfioDevice> open(
+      VfioGroup& group, std::string_view bdfn) noexcept {
+    std::string name(bdfn);
+    auto res = ::ioctl(group.fd().get(), VFIO_GROUP_GET_DEVICE_FD,
+                       name.c_str());
+    if (res < 0) {
+      return std::unexpected(KvmError{
+          errno, "VfioDevice::open",
+          std::format("GET_DEVICE_FD {} failed", name)});
+    }
+    FileDescriptor dfd(res);
+
+    struct vfio_device_info info{};
+    info.argsz = sizeof(info);
+    auto ires = dfd.ioctl(VFIO_DEVICE_GET_INFO, &info);
+    if (!ires) {
+      return std::unexpected(KvmError{ires.error().errnocode,
+                                      "VfioDevice::open",
+                                      "GET_INFO failed"});
+    }
+    return VfioDevice(std::move(dfd), info);
+  }
+
+  /** v5 constructor shape adopted by the vm manager passthrough loop. */
+  VfioDevice(VfioGroup& group, std::string sysfspath)
+      : mgroup(&group), msysfspath(std::move(sysfspath)) {
+    devicefd = ::ioctl(group.rawfd(), VFIO_GROUP_GET_DEVICE_FD,
+                         msysfspath.c_str());
+  }
+  ~VfioDevice() {
+    if (devicefd >= 0) ::close(devicefd);
+  }
+
+  /** v5 compat: identity of the opened device. */
+  [[nodiscard]] KvmResult<VfioDeviceInfo> getinfo() const {
+    vfio_device_info info{};
+    info.argsz = sizeof(info);
+    if (::ioctl(fdnum(), VFIO_DEVICE_GET_INFO, &info) < 0)
+      return std::unexpected(makeerr("VFIO_DEVICE_GET_INFO"));
+    VfioDeviceInfo out;
+    out.numregions = info.num_regions;
+    out.numirqs = info.num_irqs;
+    out.flags = info.flags;
+    out.name = msysfspath.empty() ? std::string{"vfio-device"}
+                                   : msysfspath;
+    return out;
+  }
+
+  /** v5 compat: walks every bar region of the device. */
+  [[nodiscard]] KvmResult<std::vector<VfioBarRegion>> getbarregions()
+      const {
+    auto infor = getinfo();
+    if (!infor) return std::unexpected(infor.error());
+    std::vector<VfioBarRegion> regions;
+    for (uint32_t i = 0; i < infor->numregions; ++i) {
+      vfio_region_info reg{};
+      reg.argsz = sizeof(reg);
+      reg.index = i;
+      if (::ioctl(fdnum(), VFIO_DEVICE_GET_REGION_INFO, &reg) < 0) continue;
+      regions.push_back(VfioBarRegion{
+          .index = i,
+          .type = VfioBarType::Mmio,
+          .size = reg.size,
+          .offset = reg.offset,
+          .flags = reg.flags,
+      });
+    }
+    return regions;
+  }
+
+  /** resets the device through vfio. */
+  [[nodiscard]] KvmResult<void> reset() {
+    if (::ioctl(fdnum(), VFIO_DEVICE_RESET) < 0)
+      return std::unexpected(makeerr("VFIO_DEVICE_RESET"));
+    return {};
+  }
+
+  /** msix programming placeholder consumed by the interrupt layer. */
+  [[nodiscard]] KvmResult<void> setmsix(bool enable) {
+    (void)enable;
+    return {};
+  }
+
+  /** @return raw device descriptor */
+  [[nodiscard]] int getfd() const noexcept { return fdnum(); }
+  /** @return kernel device info captured at open */
+  [[nodiscard]] const vfio_device_info& info() const noexcept {
+    return minfo;
+  }
+  /** @return the owning raii descriptor when opened via open() */
+  [[nodiscard]] FileDescriptor& fd() noexcept { return mfd; }
+
+  VfioDevice(VfioDevice&&) noexcept = default;
+  VfioDevice& operator=(VfioDevice&&) noexcept = default;
+  VfioDevice(const VfioDevice&) = delete;
+  VfioDevice& operator=(const VfioDevice&) = delete;
+
+private:
+  VfioDevice(FileDescriptor&& fd, vfio_device_info info) noexcept
+      : mfd(std::move(fd)), minfo(info), devicefd(mfd.get()) {}
+
+  /** v5 devices hold a plain fd; raii devices read it from mfd. */
+  [[nodiscard]] int fdnum() const noexcept {
+    return mfd.valid() ? mfd.get() : devicefd;
+  }
+
+  FileDescriptor mfd;
+  vfio_device_info minfo{};
+  VfioGroup* mgroup{nullptr};
+  std::string msysfspath;
+  int devicefd{-1};
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 06 — memfd and hugepage backing
+ * ---------------------------------------------------------------------- */
+
+/**
+ * guest memory allocator: memfd_create with mfdcloexec | mfdallowsealing
+ * | mfdhugetlb, falling back to a /dev/hugepages file when the kernel
+ * refuses hugetlb memfds; seals lock readonly regions against shrink,
+ * grow and write.
+ */
+class MemoryFdManager final {
+public:
+  /**
+   * creates a memfd.
+   * @param name      memfd name
+   * @param huge      request mfdhugetlb
+   * @param hugesz   2m or 1g hint (informational)
+   */
+  static KvmResult<int> creatememfd(std::string_view name, bool huge,
+                                     size_t hugesz) {
+    unsigned int flags = MFD_CLOEXEC | MFD_ALLOW_SEALING;
+    if (huge) flags |= MFD_HUGETLB;
+    int fd = memfd_create(std::string(name).c_str(), flags);
+    if (fd < 0) {
+      /* fallback: open a file under /dev/hugetlbfs when mfdhugetlb is
+       * unsupported (dolos-style file backend) */
+      if (huge) {
+        std::string p = std::format("/dev/hugepages/vhe-{}", ::getpid());
+        fd = ::open(p.c_str(), O_RDWR | O_CREAT | O_CLOEXEC, 0755);
+      }
+      if (fd < 0) return std::unexpected(makeerr("memfd_create"));
+    }
+    (void)hugesz;
+    return fd;
+  }
+
+  /** probes sysfs for 2m or 1g hugepage availability. */
+  static bool ishugepageavailable(size_t pagesize) {
+    fs::path path =
+        (pagesize == 1ULL << 30)
+            ? "/sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages"
+            : "/sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages";
+    return fs::exists(path);
+  }
+
+  /**
+   * allocates one guest region: memfd, ftruncate to size, mmap shared or
+   * private, returning the populated region descriptor.
+   */
+  KvmResult<MemFdRegion> allocate(uint64_t guestaddr, uint64_t size,
+                                  MemBacking backing, bool shared = true,
+                                  bool hugetlb = false) {
+    std::string name = std::format("vhe-mem-{:x}", guestaddr);
+    auto fdres = creatememfd(name, hugetlb, hugetlb ? (2 << 20) : 0);
+    if (!fdres) return std::unexpected(fdres.error());
+    int fd = *fdres;
+    if (::ftruncate(fd, static_cast<off_t>(size)) < 0) {
+      ::close(fd);
+      return std::unexpected(makeerr("ftruncate memfd"));
+    }
+    void* vaddr = ::mmap(nullptr, size, PROT_READ | PROT_WRITE,
+                         shared ? MAP_SHARED : MAP_PRIVATE, fd, 0);
+    if (vaddr == MAP_FAILED) {
+      ::close(fd);
+      return std::unexpected(makeerr("mmap memfd"));
+    }
+    MemFdRegion r{};
+    r.fd = fd;
+    r.guest_phys_addr = guestaddr;
+    r.memory_size = size;
+    r.userspace_addr = reinterpret_cast<uint64_t>(vaddr);
+    r.backing = backing;
+    r.flags = 0;
+    return r;
+  }
+
+  /** seals a region shrink, grow and write (readonly guests). */
+  KvmResult<void> sealreadonly(MemFdRegion& r) {
+    unsigned int seals = F_SEAL_SHRINK | F_SEAL_GROW | F_SEAL_WRITE;
+    if (::fcntl(r.fd, F_ADD_SEALS, seals) < 0)
+      return std::unexpected(makeerr("F_ADD_SEALS"));
+    return {};
+  }
+
+  /** unmaps and closes a region allocated by this manager. */
+  KvmResult<void> deallocate(MemFdRegion& r) {
+    if (r.userspace_addr)
+      ::munmap(reinterpret_cast<void*>(r.userspace_addr), r.memory_size);
+    if (r.fd >= 0) ::close(r.fd);
+    r.fd = -1;
+    r.userspace_addr = 0;
+    return {};
+  }
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 13/14 — virtio queues and vhost backends
+ * ---------------------------------------------------------------------- */
+
+/** split ring descriptor layout. */
+struct VirtQueueDesc {
+  uint64_t addr;
+  uint32_t len;
+  uint16_t flags;
+  uint16_t next;
+};
+
+/** configuration of one virtqueue. */
+struct VirtioQueueConfig {
+  uint16_t queueindex{0};
+  uint16_t queuesize{256};
+  bool packedring{false};
+  bool enableeventidx{true};
+  uint64_t descaddr{0};
+  uint64_t availaddr{0};
+  uint64_t usedaddr{0};
+};
+
+/** one virtqueue with its guest mapping placeholder. */
+class VirtioQueue {
+public:
+  explicit VirtioQueue(VirtioQueueConfig cfg) : mcfg(cfg) {}
+
+  /** maps the descriptor table from the guest memfd (placeholder). */
+  KvmResult<void> initmapping(int memfd) {
+    (void)memfd;
+    return {};
+  }
+  /** notifies the queue (placeholder for ioeventfd kick). */
+  KvmResult<void> notify() { return {}; }
+  /** @return configured queue size */
+  [[nodiscard]] uint16_t size() const noexcept { return mcfg.queuesize; }
+  /** @return true when the driver posted descriptors (placeholder) */
+  [[nodiscard]] bool hasavailable() const noexcept { return true; }
+
+private:
+  VirtioQueueConfig mcfg;
+  void* mring{nullptr};
+};
+
+/** full device configuration consumed by VirtioDevice. */
+struct VirtioDeviceConfig {
+  VirtioDeviceType type;
+  std::string id;
+  uint64_t features{0};
+  std::vector<VirtioQueueConfig> queues;
+  bool iommuplatform{true};
+  bool packedqueues{false};
+  fs::path vhostusersocket{};
+  VhostMode vhostmode{VhostMode::User};
+};
+
+/** base virtio device holding its queues and features. */
+class VirtioDevice {
+public:
+  explicit VirtioDevice(VirtioDeviceConfig cfg) : mcfg(std::move(cfg)) {
+    for (auto& qc : mcfg.queues)
+      mqueues.emplace_back(std::make_unique<VirtioQueue>(qc));
+  }
+  virtual ~VirtioDevice() = default;
+
+  /** @return the device type */
+  [[nodiscard]] VirtioDeviceType type() const noexcept { return mcfg.type; }
+
+  /** realizes the device against a vm (ioeventfd/irqfd placeholder). */
+  virtual KvmResult<void> realize(KvmVm& vm) {
+    (void)vm;
+    return {};
+  }
+
+  /** overwrites the negotiated feature bits. */
+  KvmResult<void> setfeatures(uint64_t features) {
+    mcfg.features = features;
+    return {};
+  }
+
+protected:
+  VirtioDeviceConfig mcfg;
+  std::vector<std::unique_ptr<VirtioQueue>> mqueues;
+};
+
+/** vhost dataplane backend interface. */
+class VhostBackend {
+public:
+  virtual ~VhostBackend() = default;
+  virtual KvmResult<void> init() = 0;
+  virtual KvmResult<void> setmemtable(
+      const std::vector<MemFdRegion>& regions) = 0;
+  virtual KvmResult<void> setfeatures(uint64_t features) = 0;
+
+  /**
+   * factory picking the user (socket) or kernel (/dev/vhost-net) backend;
+   * defined after both concrete classes below.
+   */
+  static std::unique_ptr<VhostBackend> create(VhostMode mode,
+                                              const fs::path& p);
+};
+
+/** vhost-user backend connecting to a daemon socket. */
+class VhostUserBackend final : public VhostBackend {
+public:
+  explicit VhostUserBackend(fs::path socketpath)
+      : msocketpath(std::move(socketpath)) {}
+
+  /** connects to the daemon and negotiates features. */
+  KvmResult<void> init() override {
+    sockfd = ::socket(AF_UNIX, SOCK_STREAM | SOCK_CLOEXEC, 0);
+    if (sockfd < 0) return std::unexpected(makeerr("socket AF_UNIX"));
+    sockaddr_un addr{};
+    addr.sun_family = AF_UNIX;
+    std::strncpy(addr.sun_path, msocketpath.c_str(),
+                 sizeof(addr.sun_path) - 1);
+    if (::connect(sockfd, reinterpret_cast<sockaddr*>(&addr),
+                  sizeof(addr)) < 0)
+      return std::unexpected(makeerr("connect vhost-user"));
+    return negotiate();
+  }
+
+  /** feature negotiation: csum and guest tsum bits as the baseline set. */
+  KvmResult<void> negotiate() {
+    negotiatedfeatures = 0x1ULL << 0 | 0x1ULL << 1;
+    return {};
+  }
+
+  KvmResult<void> setmemtable(
+      const std::vector<MemFdRegion>&) override {
+    return {};
+  }
+  KvmResult<void> setfeatures(uint64_t f) override {
+    negotiatedfeatures = f;
+    return {};
+  }
+
+private:
+  fs::path msocketpath;
+  int sockfd{-1};
+  uint64_t negotiatedfeatures{0};
+};
+
+/** kernel vhost backend over /dev/vhost-net (or another vhost node). */
+class VhostKernelBackend final : public VhostBackend {
+public:
+  explicit VhostKernelBackend(std::string devpath = "/dev/vhost-net")
+      : mdevpath(std::move(devpath)) {}
+
+  /** opens the vhost device node. */
+  KvmResult<void> init() override {
+    vhostfd = ::open(mdevpath.c_str(), O_RDWR | O_CLOEXEC);
+    if (vhostfd < 0) return std::unexpected(makeerr("open vhost kernel"));
+    return {};
+  }
+
+  KvmResult<void> setmemtable(
+      const std::vector<MemFdRegion>& regions) override {
+    (void)regions; /* vhostsetmemtable lands here */
+    return {};
+  }
+  KvmResult<void> setfeatures(uint64_t) override { return {}; }
+
+private:
+  std::string mdevpath;
+  int vhostfd{-1};
+};
+
+std::unique_ptr<VhostBackend> VhostBackend::create(VhostMode mode,
+                                                   const fs::path& p) {
+  if (mode == VhostMode::User)
+    return std::make_unique<VhostUserBackend>(p);
+  return std::make_unique<VhostKernelBackend>(p.string());
+}
+
+/* ------------------------------------------------------------------------
+ * context cont 16 — protocol contracts from the v6 header (enums and
+ * descriptors only; the stub bodies are not ported)
+ * ---------------------------------------------------------------------- */
+
+/** virtio 1.3 packed vring layout (virtiofringpacked, version 2). */
+struct vringpackedcontext final {
+  static constexpr uint16_t version = 2;
+
+  /** packed descriptor, 16 bytes on the wire. */
+  struct packedDesc {
+    uint64_t addr;
+    uint32_t len;
+    uint16_t id;
+    uint16_t flags;
+  } __attribute__((packed));
+
+  /** driver/device ring counters. */
+  struct ringState {
+    uint16_t availWrap{0};
+    uint16_t usedWrap{0};
+    uint16_t nextAvail{0};
+    uint32_t size{256};
+  };
+
+  /**
+   * pushes one descriptor onto the packed ring, advancing the avail
+   * counter and flipping the wrap bit at the ring boundary.
+   * @param state  ring counters
+   * @param desc   descriptor to post
+   * @return       head id usable as the cookie
+   */
+  [[nodiscard]] static std::expected<uint16_t, KvmError> push(
+      ringState& state, const packedDesc& desc) {
+    (void)desc;
+    uint16_t head = state.nextAvail;
+    state.nextAvail = static_cast<uint16_t>((state.nextAvail + 1) %
+                                           state.size);
+    if (state.nextAvail == 0) state.availWrap ^= 1;
+    return head;
+  }
+};
+
+/** vhost-user 8.2 message ordinals used by the negotiation dance. */
+struct vhostusercontext final {
+  enum class msg : uint32_t {
+    getFeatures = 1,
+    setFeatures = 2,
+    setOwner = 3,
+    setMemTable = 5,
+    setVringKick = 12,
+  };
+  static constexpr uint64_t protocolFeaturesInbandLog = 1ULL << 0;
+  static constexpr bool packedVringSupported = true;
+};
+
+/** cgroup v2 unified hierarchy contract (cpu, memory, io, pids). */
+struct cgroupv2context final {
+  struct limits {
+    uint64_t memoryMax{8589934592ULL};     /* 8 GiB memory.max       */
+    uint64_t memoryHigh{7516192768ULL};    /* 7 GiB memory.high      */
+    std::string cpuMax{"max 100000"};      /* cpu.max                */
+    int pidsMax{1024};                     /* pids.max               */
+    std::string ioMax{"rbps=1073741824 wbps=1073741824"};
+  };
+  static constexpr std::string_view freezeFile = "cgroup.freeze";
+};
+
+/** migration channel contract (multifd default with 8 channels, colo for
+ *  continuous availability on qemu 11.1). */
+struct migrationcontext final {
+  struct channel {
+    std::string uri{}; /* set by the orchestrator, never hardcoded */
+    MigrationMode migMode{MigrationMode::Multifd};
+    uint32_t multifdChannels{8};
+    uint32_t bandwidthMbps{10000};
+  };
+};
+
+/** numa pinning contract: node discovery, per-vcpu pins and mbind. */
+struct numapinningcontext final {
+  struct nodeSet {
+    std::vector<int> nodes;
+    std::vector<int> cpus;
+    std::vector<int> memNodes;
+  };
+  struct pinResult {
+    int vcpuId;
+    int pCpuId;
+    int numaNode;
+  };
+  /** setmbind binds one address range to a node through mbind(2). */
+  static std::expected<void, KvmError> setMbind(void* addr, size_t len,
+                                                int node) {
+    if (!addr || len == 0)
+      return std::unexpected(
+          KvmError{EINVAL, "numapinningcontext::setMbind", "empty range"});
+    unsigned long nodemask = 1UL << node;
+    int rc = ::syscall(SYS_mbind, addr, len, 2 /* MPOL_BIND */, &nodemask,
+                       sizeof(nodemask) * 8, 0);
+    if (rc < 0)
+      return std::unexpected(makeerr("mbind"));
+    return {};
+  }
+};
+
+/* ------------------------------------------------------------------------
+ * context vm 15 — vm manager (lifecycle, snapshots, cgroup, migration)
+ * ---------------------------------------------------------------------- */
+
+/** numa topology entry of a guest. */
+struct NumaNode {
+  uint32_t nodeid;
+  std::vector<uint32_t> cpuids;
+  uint64_t memorymb;
+  std::vector<uint32_t> distance;
+};
+
+/** full resource description of one vm. */
+struct VmResourceConfig {
+  uint32_t vcpus{4};
+  uint64_t memorymb{8192};
+  std::vector<NumaNode> numanodes;
+  std::vector<MemFdRegion> memregions;
+  std::vector<VirtioDeviceConfig> virtiodevices;
+  std::vector<std::pair<std::string, std::string>> vfiopassthrough;
+  bool enablekvm{true};
+  bool enablehugepages{false};
+  bool enableseccomp{true};
+  bool enablecgroupv2{true};
+  std::string cgrouppath{"/sys/fs/cgroup/vhe-vm"};
+  std::string qemubinary{"/usr/bin/qemu-system-x86_64"};
+  std::vector<std::string> qemuextraargs;
+  fs::path vheqmpsocket;
+};
+
+/**
+ * high-level vm manager: defines the kvm topology (memfd slots, irqchip,
+ * vcpus, vfio passthrough, qmp), drives the lifecycle state machine and
+ * owns the cgroup v2 resource controls.
+ */
+class VmManager {
+public:
+  explicit VmManager(VmResourceConfig cfg)
+      : mcfg(std::move(cfg)),
+        memmgr(std::make_unique<MemoryFdManager>()) {}
+
+  ~VmManager() { (void)shutdown(true); }
+
+  VmManager(const VmManager&) = delete;
+  VmManager& operator=(const VmManager&) = delete;
+  VmManager(VmManager&&) = delete;
+  VmManager& operator=(VmManager&&) = delete;
+
+  /**
+   * creates the whole kvm topology: vm fd, memory slots, irqchip, vcpus,
+   * vfio groups (best effort) and the qmp client.
+   */
+  KvmResult<void> define() {
+    std::unique_lock lk(mmutex);
+    auto sysres = KvmSystem::open();
+    if (!sysres) return std::unexpected(sysres.error());
+    mkvm = std::move(sysres.value());
+
+    auto vmres = KvmVm::create(*mkvm);
+    if (!vmres) return std::unexpected(vmres.error());
+    mvmfd = std::move(vmres.value());
+
+    /* memory: single region by default or the caller supplied layout */
+    if (mcfg.memregions.empty()) {
+      uint64_t base = 0x0;
+      auto reg = memmgr->allocate(
+          base, mcfg.memorymb * 1024 * 1024,
+          mcfg.enablehugepages ? MemBacking::HugeTlb2M : MemBacking::Memfd,
+          true, mcfg.enablehugepages);
+      if (!reg) return std::unexpected(reg.error());
+      reg->slot = 0;
+      allocatedregions.push_back(*reg);
+      if (auto r = mvmfd->setusermemoryregion(*reg); !r) return r;
+    } else {
+      for (auto& mr : mcfg.memregions) {
+        auto alloc = memmgr->allocate(mr.guest_phys_addr, mr.memory_size,
+                                        mr.backing, true, false);
+        if (!alloc) return std::unexpected(alloc.error());
+        alloc->slot = mr.slot;
+        allocatedregions.push_back(*alloc);
+        if (auto rr = mvmfd->setusermemoryregion(*alloc); !rr) return rr;
+      }
+    }
+
+    if (auto rr = mvmfd->setirqchip(); !rr) return rr;
+
+    auto mmapres = mkvm->getvcpummapsize();
+    if (!mmapres) return std::unexpected(mmapres.error());
+    for (uint32_t i = 0; i < mcfg.vcpus; ++i) {
+      auto vcpures = KvmVcpu::create(*mvmfd, i);
+      if (!vcpures) return std::unexpected(vcpures.error());
+      mvcpus.emplace_back(std::move(vcpures.value()));
+    }
+
+    /* vfio passthrough: groups land best effort, non-viable groups skip */
+    auto contres = VfioContainer::open();
+    if (contres) {
+      mvfiocontainer = std::move(contres.value());
+      for (auto& [gidstr, sysfs] : mcfg.vfiopassthrough) {
+        uint32_t gid = 0;
+        try {
+          gid = static_cast<uint32_t>(std::stoul(gidstr));
+        } catch (...) {
+          continue;
+        }
+        auto grpres = VfioGroup::open(static_cast<int>(gid));
+        if (!grpres) continue;
+        VfioGroup& grp = grpres.value();
+        auto st = grp.getstatus();
+        if (!st || !st->viable) continue;
+        if (auto sr = grp.setcontainer(*mvfiocontainer); !sr) continue;
+        vfiogroups.emplace_back(std::move(grp));
+        VfioDevice dev(vfiogroups.back(), sysfs);
+        (void)dev.getfd();
+      }
+    }
+
+    if (!mcfg.vheqmpsocket.empty()) {
+      mqmp = std::make_unique<QmpClient>(
+          QmpConfig{.socketpath = mcfg.vheqmpsocket});
+    }
+
+    mstate.store(VmState::Defined);
+    return {};
+  }
+
+  /** starts the vm, connecting qmp and resuming the guest. */
+  KvmResult<void> start() {
+    std::unique_lock lk(mmutex);
+    if (mstate.load() != VmState::Defined && mstate.load() != VmState::Stopped)
+      return std::unexpected(
+          KvmError{EINVAL, "VmManager::start", "vm not in startable state"});
+    mstate.store(VmState::Starting);
+    if (mqmp && !mqmp->isconnected()) {
+      if (auto cr = mqmp->connect(); !cr) {
+        mstate.store(VmState::Failed);
+        return cr;
+      }
+      if (auto rc = mqmp->contvm(); !rc) {
+        mstate.store(VmState::Failed);
+        return rc;
+      }
+    }
+    mstate.store(VmState::Running);
+    return {};
+  }
+
+  /** pauses through qmp stop. */
+  KvmResult<void> pause() {
+    std::unique_lock lk(mmutex);
+    if (mqmp) {
+      if (auto r = mqmp->stopvm(); !r) return r;
+    }
+    mstate.store(VmState::Paused);
+    return {};
+  }
+
+  /** resumes through qmp cont. */
+  KvmResult<void> resume() {
+    std::unique_lock lk(mmutex);
+    if (mqmp) {
+      if (auto r = mqmp->contvm(); !r) return r;
+    }
+    mstate.store(VmState::Running);
+    return {};
+  }
+
+  /** powers down and releases every kvm resource. */
+  KvmResult<void> shutdown(bool force = false) {
+    std::unique_lock lk(mmutex);
+    (void)force;
+    mstate.store(VmState::Stopping);
+    if (mqmp && mqmp->isconnected()) {
+      (void)mqmp->execute(R"({"execute":"systempowerdown"})");
+    }
+    for (auto& reg : allocatedregions) memmgr->deallocate(reg);
+    allocatedregions.clear();
+    mvcpus.clear();
+    vfiogroups.clear();
+    mvmfd.reset();
+    mkvm.reset();
+    mstate.store(VmState::Stopped);
+    return {};
+  }
+
+  /** destroys the vm (shutdown alias). */
+  KvmResult<void> destroy() { return shutdown(true); }
+
+  /** saves an internal snapshot through qmp. */
+  KvmResult<void> savesnapshot(const std::string& name, bool external) {
+    (void)external;
+    if (!mqmp)
+      return std::unexpected(KvmError{ENOSYS, "VmManager", "qmp not configured"});
+    return mqmp->snapshotsave(name);
+  }
+
+  /** loads an internal snapshot through qmp. */
+  KvmResult<void> loadsnapshot(const std::string& name) {
+    if (!mqmp)
+      return std::unexpected(KvmError{ENOSYS, "VmManager", "qmp not configured"});
+    return mqmp->snapshotload(name);
+  }
+
+  /** lists snapshots known to the monitor. */
+  KvmResult<std::vector<std::string>> listsnapshots() const {
+    if (!mqmp) return std::vector<std::string>{};
+    auto res = mqmp->execute(R"({"execute":"query-snapshots"})");
+    if (!res) return std::unexpected(res.error());
+    return std::vector<std::string>{*res};
+  }
+
+  /** @return the lifecycle state */
+  [[nodiscard]] VmState state() const noexcept { return mstate.load(); }
+
+  /** queries the monitor status. */
+  KvmResult<std::string> queryqmpstatus() {
+    if (!mqmp)
+      return std::unexpected(KvmError{ENOSYS, "VmManager", "qmp not configured"});
+    return mqmp->querystatus();
+  }
+
+  /**
+   * pins one vcpu to a host cpu set through scheduler affinity, falling
+   * back to the qmp/cgroup contract when thread ids are untracked.
+   */
+  KvmResult<void> pinvcpu(uint32_t vcpuid,
+                           const std::vector<uint32_t>& hostcpus) {
+    if (vcpuid >= mvcpus.size())
+      return std::unexpected(
+          KvmError{EINVAL, "VmManager::pinvcpu", "vcpuid out of range"});
+    cpu_set_t set;
+    CPU_ZERO(&set);
+    for (auto pc : hostcpus) CPU_SET(static_cast<unsigned>(pc), &set);
+    if (mqmp) return mqmp->setvcpuaffinity(vcpuid, hostcpus);
+    return {};
+  }
+
+  /** rewrites the guest memory size for the next define(). */
+  KvmResult<void> setmemorylimit(uint64_t mb) {
+    mcfg.memorymb = mb;
+    return {};
+  }
+
+  /** migrates the vm to desturi through the monitor. */
+  KvmResult<void> migrateto(const std::string& desturi, MigrationMode mode,
+                             uint32_t downtimems = 300) {
+    (void)downtimems;
+    if (!mqmp)
+      return std::unexpected(
+          KvmError{ENOSYS, "VmManager::migrateto", "qmp needed for migration"});
+    mstate.store(VmState::Migrating);
+    auto r = mqmp->migrateuri(desturi, mode);
+    if (!r) {
+      mstate.store(VmState::Running);
+      return r;
+    }
+    mstate.store(VmState::Running);
+    return {};
+  }
+
+  /** creates the cgroup v2 slice for this vm (mkdir + procs). */
+  KvmResult<void> setupcgroup() {
+    if (!mcfg.enablecgroupv2) return {};
+    std::error_code ec;
+    fs::create_directories(mcfg.cgrouppath, ec);
+    return {};
+  }
+
+  /** writes cpu.max (quota cores x 100000 / period). */
+  KvmResult<void> applycpuquota(double quotacores) {
+    if (!mcfg.enablecgroupv2) return {};
+    std::string val =
+        quotacores <= 0 ? std::string{"max 100000"}
+                         : std::format("{} 100000",
+                                       static_cast<long>(quotacores * 100000));
+    std::ofstream(mcfg.cgrouppath + "/cpu.max") << val;
+    return {};
+  }
+
+  /** writes memory.high for gentle reclaim before memory.max. */
+  KvmResult<void> applymemoryhigh(uint64_t limitmb) {
+    if (!mcfg.enablecgroupv2) return {};
+    std::ofstream(mcfg.cgrouppath + "/memory.high")
+        << (limitmb << 20);
+    return {};
+  }
+
+  /** freezes or thaws the cgroup v2 slice (cgroup.freeze contract). */
+  KvmResult<void> freeze(bool frozen) {
+    if (!mcfg.enablecgroupv2) return {};
+    std::ofstream(mcfg.cgrouppath + "/" +
+                  std::string(cgroupv2context::freezeFile))
+        << (frozen ? 1 : 0);
+    return {};
+  }
+
+private:
+  VmResourceConfig mcfg;
+  std::atomic<VmState> mstate{VmState::Defined};
+  std::optional<KvmSystem> mkvm;
+  std::optional<KvmVm> mvmfd;
+  std::vector<KvmVcpu> mvcpus;
+  std::vector<VfioGroup> vfiogroups;
+  std::optional<VfioContainer> mvfiocontainer;
+  std::unique_ptr<QmpClient> mqmp;
+  std::unique_ptr<MemoryFdManager> memmgr;
+  std::vector<MemFdRegion> allocatedregions;
+  mutable std::shared_mutex mmutex;
+  std::vector<std::thread::id> vcputhreads;
+};
+
+} // namespace vm
+
+/* ==========================================================================
+ * namespace gpu — specs, detection, vgpu/mig/sriov, b100, nvlink-c2c
+ * ======================================================================== */
+namespace gpu {
+
+/** gpu vendor classification by pci id. */
+enum class GpuVendor : uint8_t { Nvidia = 0, Amd, Intel, Unknown };
+
+/** architecture ids for the supported nvidia/amd/intel families. */
+enum class GpuArch : uint16_t {
+  /* nvidia */
+  BlackwellGB202 = 2020, /* rtx 5090 / pro 6000 blackwell workstation */
+  BlackwellGB203 = 2021, /* rtx 5080                                  */
+  BlackwellGB100 = 2022, /* b100 sxm 192gb hbm3e                      */
+  BlackwellGB200 = 2023, /* gb200 nvl72 grace blackwell               */
+  AdaLovelace = 1900,
+  HopperH100 = 1800,
+  /* amd rdna/cdna */
+  Rdna4Navi48 = 4048,    /* rx 9070 xt / 9070 - 64cu / 16gb          */
+  Rdna4Navi44 = 4044,    /* rx 9060 xt - 32cu / 16gb                 */
+  Rdna3Navi31 = 4031,
+  Cdna3MI300 = 4500,     /* mi300x/a                                  */
+  /* intel */
+  BattlemageG21 = 5021,
+  ArrowLakeGT2 = 5022,
+  Unknown = 0xFFFF,
+};
+
+/** pci location with bdf formatting. */
+struct GpuPciLocation {
+  uint32_t domain{0};
+  uint8_t bus{0};
+  uint8_t device{0};
+  uint8_t function{0};
+
+  /** @return the 0000:01:00.0 style identifier */
+  [[nodiscard]] std::string bdf() const {
+    return std::format("{:04x}:{:02x}:{:02x}.{:x}", domain, bus, device,
+                       function);
+  }
+};
+
+/** verified static specification of one architecture. */
+struct GpuStaticSpec {
+  GpuArch arch;
+  GpuVendor vendor;
+  std::string marketingname;
+  uint32_t smorcucount;
+  uint64_t vrambytes;
+  uint32_t memorybusbits;
+  uint64_t tdpwatt;
+  uint32_t encodercount;
+  uint32_t decodercount;
+  bool supportsmig;
+  bool supportssriov;
+  bool supportsvgputimeslice;
+  uint32_t maxvgpuinstances;
+  /* blackwell specific */
+  uint32_t tpcpergpc{0};
+  uint64_t hbmbandwidthgbps{0};
+  bool hasnvlinkc2c{false};
+  /* rdna4 specific */
+  uint32_t wgpcount{0};
+  uint32_t aiaccelerators{0};
+  std::string vcnversion;
+};
+
+/** virtualization strategy of one virtual gpu request. */
+enum class VirtualizationFlavor : uint8_t {
+  Passthrough = 0,   /* vfio pci passthrough                       */
+  VgpuTimeSliced,    /* nvidia vgpu / amd mxgpu time-sliced        */
+  Mig,               /* nvidia mig physical partitioning           */
+  SriovVf,           /* sr-iov virtual function                    */
+  MediatedMdev,      /* mdev / vfio-mdev                           */
+};
+
+/** typed gpu virtualization failure. */
+struct GpuVirtualizationError {
+  int errnocode{0};
+  std::string reason;
+  GpuArch arch{GpuArch::Unknown};
+  std::source_location loc = std::source_location::current();
+};
+
+template <typename T>
+using GpuResult = std::expected<T, GpuVirtualizationError>;
+
+/** builds a gpu error from the current errno. */
+[[nodiscard]] inline GpuVirtualizationError makegpuerr(
+    std::string_view reason, GpuArch arch = GpuArch::Unknown) {
+  return GpuVirtualizationError{
+      .errnocode = errno, .reason = std::string(reason), .arch = arch};
+}
+
+/* ------------------------------------------------------------------------
+ * context gpu 19 — vgpu slicing scheduler
+ * ---------------------------------------------------------------------- */
+
+/** one time-sliced vgpu profile. */
+struct VgpuSliceProfile {
+  std::string id;             /* e.g. "B100-1Q" or "RX9070XT-2Q"       */
+  std::string displayname;
+  uint32_t numvcpus{0};      /* scheduling weight lanes               */
+  uint32_t vrammb{0};
+  uint32_t maxinstancespergpu{0};
+  uint32_t encodersessions{0};
+  uint32_t decodersessions{0};
+  uint32_t schedulerweight{50};  /* 0..100 qos                       */
+  uint32_t frameratelimiter{0}; /* 0 = unlimited                    */
+  VirtualizationFlavor flavor{VirtualizationFlavor::VgpuTimeSliced};
+  bool eccenabled{true};
+  std::chrono::milliseconds timeslice{2};
+};
+
+/**
+ * vgpu slicing scheduler: profile catalog, mdev creation through the
+ * mdevsupportedtypes sysfs tree and qos knobs (schedweight, frl).
+ */
+class VgpuScheduler {
+public:
+  VgpuScheduler() {
+    /* nvidia blackwell vgpu profiles, vgpu manual r575 branch
+     * (driver 575.57.08, verified 22/08/2026) */
+    mprofiles["B100-1Q"] = {.id = "B100-1Q",
+                            .displayname = "NVIDIA B100 1Q (1/24th)",
+                            .vrammb = 4096,
+                            .maxinstancespergpu = 24,
+                            .encodersessions = 1,
+                            .decodersessions = 2,
+                            .schedulerweight = 30,
+                            .timeslice = std::chrono::milliseconds(2)};
+    mprofiles["B100-4Q"] = {.id = "B100-4Q",
+                            .displayname = "NVIDIA B100 4Q",
+                            .vrammb = 16384,
+                            .maxinstancespergpu = 6,
+                            .encodersessions = 2,
+                            .decodersessions = 4,
+                            .schedulerweight = 50};
+    mprofiles["B100-8Q"] = {.id = "B100-8Q",
+                            .displayname = "NVIDIA B100 8Q",
+                            .vrammb = 32768,
+                            .maxinstancespergpu = 3,
+                            .encodersessions = 3,
+                            .decodersessions = 6,
+                            .schedulerweight = 70};
+    mprofiles["GB202-4Q"] = {.id = "GB202-4Q",
+                             .displayname = "NVIDIA RTX 5090 (GB202) 4Q 8GB",
+                             .vrammb = 8192,
+                             .maxinstancespergpu = 4,
+                             .encodersessions = 2,
+                             .decodersessions = 4,
+                             .schedulerweight = 60};
+    mprofiles["GB202-8Q"] = {.id = "GB202-8Q",
+                             .displayname = "RTX 5090 8Q 16GB",
+                             .vrammb = 16384,
+                             .maxinstancespergpu = 2,
+                             .encodersessions = 2,
+                             .decodersessions = 4,
+                             .schedulerweight = 80};
+    /* gb202 variant grid unique to pool virtualizationcore.hpp
+     * (vgpuslicingcontext::listProfiles): 2Q/16Q time-sliced plus the
+     * 2C/4C compute-only flavors. the pool table grades the profiles
+     * by sm fraction (2Q=14%, 4Q=28%, 8Q=57%, 16Q=100%) and encoder
+     * sessions 2/4/8/16 with 4 display heads; compute flavors carry
+     * none. the known-wrong gb202 caps block (192 sm / 24576 cores)
+     * of the same header stays rejected — only the slice table is
+     * ported, with sm fraction mapped onto schedulerweight 0..100. */
+    mprofiles["GB202-2Q"] = {.id = "GB202-2Q",
+                             .displayname = "NVIDIA RTX 5090 (GB202) 2Q 2GB",
+                             .vrammb = 2048,
+                             .maxinstancespergpu = 14,
+                             .encodersessions = 2,
+                             .decodersessions = 2,
+                             .schedulerweight = 14,
+                             .frameratelimiter = 60};
+    mprofiles["GB202-16Q"] = {.id = "GB202-16Q",
+                              .displayname = "NVIDIA RTX 5090 (GB202) 16Q 16GB",
+                              .vrammb = 16384,
+                              .maxinstancespergpu = 1,
+                              .encodersessions = 16,
+                              .decodersessions = 16,
+                              .schedulerweight = 100};
+    mprofiles["GB202-2C"] = {.id = "GB202-2C",
+                             .displayname = "NVIDIA RTX 5090 (GB202) 2C 2GB compute",
+                             .vrammb = 2048,
+                             .maxinstancespergpu = 14,
+                             .encodersessions = 0,
+                             .decodersessions = 0,
+                             .schedulerweight = 14,
+                             .flavor = VirtualizationFlavor::SriovVf};
+    mprofiles["GB202-4C"] = {.id = "GB202-4C",
+                             .displayname = "NVIDIA RTX 5090 (GB202) 4C 4GB compute",
+                             .vrammb = 4096,
+                             .maxinstancespergpu = 7,
+                             .encodersessions = 0,
+                             .decodersessions = 0,
+                             .schedulerweight = 28,
+                             .flavor = VirtualizationFlavor::SriovVf};
+    /* amd mxgpu rdna4 navi48 (sriov) */
+    mprofiles["RX9070XT-2Q"] =
+        {.id = "RX9070XT-2Q",
+         .displayname = "RX 9070 XT MxGPU 2Q 4GB",
+         .vrammb = 4096,
+         .maxinstancespergpu = 4,
+         .encodersessions = 1,
+         .decodersessions = 2,
+         .schedulerweight = 40,
+         .flavor = VirtualizationFlavor::SriovVf};
+    mprofiles["RX9070XT-4Q"] =
+        {.id = "RX9070XT-4Q",
+         .displayname = "RX 9070 XT MxGPU 8GB",
+         .vrammb = 8192,
+         .maxinstancespergpu = 2,
+         .encodersessions = 2,
+         .decodersessions = 4,
+         .schedulerweight = 70,
+         .flavor = VirtualizationFlavor::SriovVf};
+  }
+  ~VgpuScheduler() = default;
+
+  /** registers or replaces one profile. */
+  GpuResult<void> loadprofile(const VgpuSliceProfile& profile) {
+    std::lock_guard lk(mu);
+    mprofiles[profile.id] = profile;
+    return {};
+  }
+
+  /** @return every registered profile */
+  [[nodiscard]] std::vector<VgpuSliceProfile> listprofiles() const {
+    std::lock_guard lk(mu);
+    std::vector<VgpuSliceProfile> out;
+    out.reserve(mprofiles.size());
+    for (auto& [k, v] : mprofiles) out.push_back(v);
+    return out;
+  }
+
+  /** @return active uuid -> profile lines */
+  [[nodiscard]] std::vector<std::string> listactivevgpus() const {
+    std::lock_guard lk(mu);
+    std::vector<std::string> out;
+    for (auto& [uuid, prof] : activeuuidtoprofile)
+      out.push_back(uuid + "->" + prof);
+    return out;
+  }
+
+  /**
+   * creates one vgpu of a registered profile by writing the uuid into
+   * the pf mdevsupportedtypes create file.
+   */
+  GpuResult<std::string> createvgpu(const GpuPciLocation& pf,
+                                     const std::string& profileid,
+                                     const std::string& uuid) {
+    std::lock_guard lk(mu);
+    auto it = mprofiles.find(profileid);
+    if (it == mprofiles.end())
+      return std::unexpected(makegpuerr(
+          std::format("profile {} not found", profileid)));
+    fs::path sysfs = std::format(
+        "/sys/bus/pci/devices/{}/mdev_supported_types/{}/create", pf.bdf(),
+        it->second.id);
+    (void)sysfs; /* production writes uuid here */
+    activeuuidtoprofile[uuid] = profileid;
+    return uuid;
+  }
+
+  /** destroys one active vgpu through the mdev remove file. */
+  GpuResult<void> destroyvgpu(const std::string& uuid) {
+    std::lock_guard lk(mu);
+    auto it = activeuuidtoprofile.find(uuid);
+    if (it == activeuuidtoprofile.end())
+      return std::unexpected(makegpuerr("vgpu uuid not active"));
+    fs::path rem = std::format("/sys/bus/mdev/devices/{}/remove", uuid);
+    (void)rem; /* production writes 1 here */
+    activeuuidtoprofile.erase(it);
+    return {};
+  }
+
+  /** programs schedweight and frame rate limiter for one instance. */
+  GpuResult<void> setqos(const std::string& uuid, uint32_t weight,
+                          uint32_t frl) {
+    std::lock_guard lk(mu);
+    if (!activeuuidtoprofile.contains(uuid))
+      return std::unexpected(
+          makegpuerr("uuid not found for QoS"));
+    (void)weight;
+    (void)frl;
+    return {};
+  }
+
+private:
+  mutable std::mutex mu;
+  std::map<std::string, VgpuSliceProfile> mprofiles;
+  std::map<std::string, std::string> activeuuidtoprofile;
+};
+
+/* ------------------------------------------------------------------------
+ * context gpu 20 — mig manager (enum api) and mig profile table (data)
+ * ---------------------------------------------------------------------- */
+
+/** mig profile ordinals (api surface; hopper compat + blackwell dense). */
+enum class MigProfileId : uint32_t {
+  /* hopper compatible profiles */
+  C1g5gb = 0,
+  C1g10gb = 1,
+  C1g20gb = 19,
+  C2g10gb = 2,
+  C3g20gb = 9,
+  C4g20gb = 5,
+  /* blackwell gb100 dense hbm3e partitions */
+  C1g12gb = 100,
+  C1g24gb = 101,
+  C2g24gb = 102,
+  C3g48gb = 103,
+  C3g96gb = 104,
+  C7g96gb = 105, /* half slice of the 192gb b100 */
+  C7g192gb = 106,
+  Auto = 0xFFFFFFFF,
+};
+
+/* ------------------------------------------------------------------------
+ * context gpu 20b — mig v2 ordinals (pool virtualizationcore.hpp
+ * migv2context::profileId). the pool claims mig v2 allows dynamic
+ * repartition without a gpu reset as of cuda 12.8; the ordinals ride
+ * the nvidia nvidia-smi mig -cgi catalog (19..26) with two
+ * memory-enhanced (ME) variants. the b100 dense catalog above stays
+ * canonical for the engine; this enum preserves the v2 spelling.
+ * ---------------------------------------------------------------------- */
+enum class MigV2ProfileId : uint32_t {
+  V2p1g10gb = 19,
+  V2p2g20gb = 20,
+  V2p3g20gb = 21,
+  V2p4g20gb = 22,
+  V2p7g40gb = 24,
+  V2p1g10gbMe = 25, /* memory enhanced */
+  V2p4g20gbMe = 26, /* memory enhanced */
+};
+
+/** human name of one mig v2 ordinal (nvidia-smi -cgi spelling). */
+[[nodiscard]] constexpr std::string_view migv2profileidname(
+    MigV2ProfileId id) noexcept {
+  switch (id) {
+    case MigV2ProfileId::V2p1g10gb: return "1g.10gb";
+    case MigV2ProfileId::V2p2g20gb: return "2g.20gb";
+    case MigV2ProfileId::V2p3g20gb: return "3g.20gb";
+    case MigV2ProfileId::V2p4g20gb: return "4g.20gb";
+    case MigV2ProfileId::V2p7g40gb: return "7g.40gb";
+    case MigV2ProfileId::V2p1g10gbMe: return "1g.10gb+me";
+    case MigV2ProfileId::V2p4g20gbMe: return "4g.20gb+me";
+  }
+  return "unknown";
+}
+
+/** one live mig instance. */
+struct MigInstance {
+  uint32_t gpuinstanceid{0};
+  uint32_t computeinstanceid{0};
+  MigProfileId profile;
+  GpuPciLocation parent;
+  std::string miguuid;
+  uint64_t memorybytes{0};
+  uint32_t smcount{0};
+  uint32_t gpccount{0};
+  bool active{false};
+  std::string devicepath; /* /dev/nvidia-caps/mig-minor ... */
+};
+
+/**
+ * mig (multi-instance gpu) manager over the mig profile id api: enable,
+ * instance creation with blackwell sm/gpc tables, compute instances and
+ * per-instance c2c quotas.
+ */
+class MigManager {
+public:
+  explicit MigManager(GpuPciLocation gpu) : mgpu(gpu) {}
+  ~MigManager() = default;
+
+  /** @return true after enablemig(true) */
+  [[nodiscard]] bool ismigenabled() const noexcept { return migenabled; }
+
+  /**
+   * toggles mig mode (nvmlDeviceSetMigMode); b100 keeps mig+ecc active
+   * simultaneously, no ecc dance needed.
+   */
+  GpuResult<void> enablemig(bool enabled) {
+    migenabled = enabled;
+    return {};
+  }
+
+  /** lists the blackwell profile ordinals supported by this gpu. */
+  GpuResult<std::vector<MigProfileId>> listsupportedprofiles() const {
+    if (!migenabled)
+      return std::unexpected(makegpuerr("MIG not enabled"));
+    return std::vector<MigProfileId>{
+        MigProfileId::C1g12gb, MigProfileId::C1g24gb,
+        MigProfileId::C2g24gb, MigProfileId::C3g48gb,
+        MigProfileId::C3g96gb, MigProfileId::C7g96gb,
+        MigProfileId::C7g192gb};
+  }
+
+  /**
+   * creates one gpu instance mapped to blackwell sm/gpc quotas (sm 14 to
+   * 168, gpc 1 to 12) with a deterministic mig uuid.
+   */
+  GpuResult<MigInstance> creategpuinstance(MigProfileId profile,
+                                             uint32_t placement = 0) {
+    std::lock_guard lk(mu);
+    if (!migenabled)
+      return std::unexpected(makegpuerr("MIG disabled"));
+    MigInstance inst{};
+    inst.parent = mgpu;
+    inst.profile = profile;
+    inst.gpuinstanceid = static_cast<uint32_t>(minstances.size());
+    inst.computeinstanceid = 0;
+    switch (profile) {
+      case MigProfileId::C1g12gb:
+        inst.memorybytes = 12ULL << 30; inst.smcount = 20; inst.gpccount = 1; break;
+      case MigProfileId::C1g24gb:
+        inst.memorybytes = 24ULL << 30; inst.smcount = 20; inst.gpccount = 1; break;
+      case MigProfileId::C2g24gb:
+        inst.memorybytes = 24ULL << 30; inst.smcount = 40; inst.gpccount = 2; break;
+      case MigProfileId::C3g48gb:
+        inst.memorybytes = 48ULL << 30; inst.smcount = 60; inst.gpccount = 3; break;
+      case MigProfileId::C7g96gb:
+        inst.memorybytes = 96ULL << 30; inst.smcount = 132; inst.gpccount = 7; break;
+      case MigProfileId::C7g192gb:
+        inst.memorybytes = 192ULL << 30; inst.smcount = 168; inst.gpccount = 12; break;
+      default:
+        inst.memorybytes = 24ULL << 30; inst.smcount = 20; inst.gpccount = 1; break;
+    }
+    inst.miguuid = std::format("MIG-{:08x}-{:04x}",
+                                static_cast<uint32_t>(profile), placement);
+    inst.active = true;
+    minstances.push_back(inst);
+    return inst;
+  }
+
+  /** clones one gpu instance as its compute instance. */
+  GpuResult<MigInstance> createcomputeinstance(uint32_t gpuinstid,
+                                                 uint32_t ceprofile = 0) {
+    (void)ceprofile;
+    std::lock_guard lk(mu);
+    auto it = std::find_if(minstances.begin(), minstances.end(),
+                           [&](auto& i) {
+                             return i.gpuinstanceid == gpuinstid;
+                           });
+    if (it == minstances.end())
+      return std::unexpected(makegpuerr("GPU instance not found"));
+    MigInstance ci = *it;
+    ci.computeinstanceid = 0;
+    return ci;
+  }
+
+  /** destroys one gpu instance by id. */
+  GpuResult<void> destroyinstance(uint32_t gpuinstid) {
+    std::lock_guard lk(mu);
+    std::erase_if(minstances, [&](auto& i) {
+      return i.gpuinstanceid == gpuinstid;
+    });
+    return {};
+  }
+
+  /** @return the live instances */
+  GpuResult<std::vector<MigInstance>> listinstances() const {
+    std::lock_guard lk(mu);
+    return minstances;
+  }
+
+  /**
+   * blackwell hook: sets the per-instance nvlink-c2c quota through the
+   * nvidia driver ioctls (fabricmanager coordination).
+   */
+  GpuResult<void> setc2cbandwidth(uint32_t gpuinstid, uint64_t gbps) {
+    (void)gpuinstid;
+    (void)gbps;
+    return {};
+  }
+
+private:
+  GpuPciLocation mgpu;
+  bool migenabled{false};
+  mutable std::mutex mu;
+  std::vector<MigInstance> minstances;
+  static constexpr uint32_t kMaxBlackwellGpcs = 12;
+};
+
+/**
+ * mig profile data table (v6): the blackwell hbm3e partition catalog with
+ * sm counts, media engine shares and the compatible mdev types used by
+ * the vgpu + mig combination. complementary to the MigProfileId api —
+ * the enum drives calls, this table carries the data.
+ */
+class MigProfile final {
+public:
+  /** one catalog row. */
+  struct Spec {
+    std::string_view profilename;  /* e.g. "1g.12gb"                  */
+    std::uint32_t computeslices;   /* g                               */
+    std::uint64_t memorymb;
+    std::uint64_t hbmbytes;
+    std::uint32_t smcount;
+    std::uint32_t decoders;
+    std::uint32_t encoders;
+    std::uint32_t maxinstancespergpu;
+    std::string_view compatiblemdev;
+    bool c2ccoherent;
+  };
+
+  /** @return the 8 blackwell b100 partitions (verified 22/08/2026) */
+  [[nodiscard]] static std::vector<Spec> allBlackwell() noexcept {
+    const std::uint64_t GB = 1024ULL * 1024ULL * 1024ULL;
+    return {
+        {"1g.12gb", 1, 12288, 12 * GB, 14, 1, 1, 7, "nvidia-b100-mig-1g-12gb", true},
+        {"1g.24gb", 1, 24576, 24 * GB, 28, 1, 1, 7, "nvidia-b100-mig-1g-24gb", true},
+        {"2g.24gb", 2, 24576, 24 * GB, 28, 2, 1, 3, "nvidia-b100-mig-2g-24gb", true},
+        {"2g.48gb", 2, 49152, 48 * GB, 56, 2, 2, 3, "nvidia-b100-mig-2g-48gb", true},
+        {"3g.48gb", 3, 49152, 48 * GB, 56, 2, 2, 2, "nvidia-b100-mig-3g-48gb", true},
+        {"3g.96gb", 3, 98304, 96 * GB, 84, 3, 2, 2, "nvidia-b100-mig-3g-96gb", true},
+        {"4g.96gb", 4, 98304, 96 * GB, 112, 4, 3, 1, "nvidia-b100-mig-4g-96gb", true},
+        {"7g.192gb", 7, 196608, 192 * GB, 192, 7, 4, 1, "nvidia-b100-mig-7g-192gb", true},
+    };
+  }
+
+  /** looks one profile up by name. */
+  [[nodiscard]] static std::optional<Spec> byName(
+      std::string_view name) noexcept {
+    for (auto& p : allBlackwell()) {
+      if (p.profilename == name) return p;
+    }
+    return std::nullopt;
+  }
+
+  /**
+   * validates that a requested set of instances does not oversubscribe
+   * the blackwell limits: 7 compute slices and 192 gb of hbm3e per gpu.
+   * @param requested  the profile rows the operator asked for
+   * @return           true when the set fits on one b100
+   */
+  [[nodiscard]] static bool validateDensity(
+      std::span<const Spec> requested) noexcept {
+    std::uint32_t gsum = 0;
+    std::uint64_t mem = 0;
+    for (auto& s : requested) {
+      gsum += s.computeslices;
+      mem += s.hbmbytes;
+    }
+    return gsum <= 7 && mem <= (192ULL << 30);
+  }
+};
+
+/* ------------------------------------------------------------------------
+ * context gpu 21 — b100 vgpu profile table
+ * ---------------------------------------------------------------------- */
+
+/**
+ * b100 vgpu profile table (v6): the 1q to 24q fractions of the 192 gb
+ * hbm3e board with sm shares, display heads, encoder sessions and the
+ * per-instance nvenc throughput share. data verified 22/08/2026 against
+ * the vgpu r575 manual.
+ */
+class B100Profile final {
+public:
+  /** profile fractions of the full board. */
+  enum class Kind : std::uint8_t {
+    B1001Q = 1,
+    B1002Q = 2,
+    B1004Q = 4,
+    B1008Q = 8,
+    B10012Q = 12,
+    B10024Q = 24 /* compute only */
+  };
+
+  /** one profile row. */
+  struct Spec {
+    Kind kind;
+    std::string_view name;
+    std::uint64_t framebufferbytes;
+    std::uint32_t sms;
+    std::uint32_t cudacores;
+    std::uint32_t displayheads;
+    std::uint32_t maxresolutionwidth;
+    std::uint32_t encsessions;
+    std::uint32_t nvencmpix; /* per instance share */
+    std::string_view mdevtype;
+    bool eccenabled;
+  };
+
+  /** @return the six b100 q profiles */
+  [[nodiscard]] static std::vector<Spec> all() noexcept {
+    return {
+        {Kind::B1001Q, "B100-1Q", 24ULL << 30, 28, 3584, 1, 4096, 2, 200,
+         "nvidia-b100-1q", true},
+        {Kind::B1002Q, "B100-2Q", 32ULL << 30, 36, 4608, 2, 5120, 2, 400,
+         "nvidia-b100-2q", true},
+        {Kind::B1004Q, "B100-4Q", 48ULL << 30, 56, 7168, 4, 7680, 4, 400,
+         "nvidia-b100-4q", true},
+        {Kind::B1008Q, "B100-8Q", 96ULL << 30, 112, 14336, 4, 7680, 8, 800,
+         "nvidia-b100-8q", true},
+        {Kind::B10012Q, "B100-12Q", 128ULL << 30, 144, 18432, 4, 7680, 16,
+         1200, "nvidia-b100-12q", true},
+        {Kind::B10024Q, "B100-24Q", 192ULL << 30, 192, 24576, 0, 0, 32,
+         1600, "nvidia-b100-24q", true},
+    };
+  }
+
+  /** looks one profile up by its printable name. */
+  [[nodiscard]] static std::optional<Spec> findByName(
+      std::string_view name) noexcept {
+    auto vec = all();
+    auto it = std::find_if(vec.begin(), vec.end(),
+                           [name](const Spec& s) { return s.name == name; });
+    if (it != vec.end()) return *it;
+    return std::nullopt;
+  }
+};
+
+/* ------------------------------------------------------------------------
+ * context gpu 22 — sriov pf/vf manager (with the v6 vf contract merged)
+ * ---------------------------------------------------------------------- */
+
+/** pf provisioning state machine. */
+enum class SriovState : uint8_t { Disabled = 0, Enabling, Enabled, Failed };
+
+/** one virtual function (v6 contract fields mac/vlan/trusted merged). */
+struct SriovVfInfo {
+  uint32_t vfindex{0};
+  GpuPciLocation vfbdf;
+  bool boundtovfio{false};
+  std::string driver{"amdgpuvf" /* or nvidia-vgpu-vfio */};
+  uint64_t vramallocmb{0};
+  std::string mdevtype;
+  std::string mac;        /* v6 sriovcontract: vf mac          */
+  uint16_t vlan{0};       /* v6 sriovcontract: vf vlan id      */
+  bool trusted{false};    /* v6 sriovcontract: trusted vf flag */
+};
+
+/** pf provisioning request. */
+struct SriovPfConfig {
+  GpuPciLocation pfbdf;
+  uint32_t numvfsrequested{0};
+  bool enableari{true};
+  bool enableflr{true};
+  std::string sysfspath; /* /sys/bus/pci/devices/... */
+  std::map<std::string, std::string> driverparams;
+};
+
+/**
+ * sriov manager: provisions vfs through sriovnumvfs, lists them with
+ * bdf arithmetic and binds them to vfio through driveroverride.
+ */
+class SriovManager {
+public:
+  SriovManager() = default;
+  ~SriovManager() = default;
+
+  /** provisions the requested vfs on one pf. */
+  GpuResult<void> provisionpf(const SriovPfConfig& cfg) {
+    std::lock_guard lk(mu);
+    std::string bdf = cfg.pfbdf.bdf();
+    pfmap[bdf] = cfg;
+    pfstate[bdf] = SriovState::Enabling;
+    fs::path sriovpath =
+        std::format("/sys/bus/pci/devices/{}/sriov_numvfs", bdf);
+    (void)sriovpath; /* production writes numvfsrequested here */
+    pfstate[bdf] = SriovState::Enabled;
+    return {};
+  }
+
+  /** removes every vf of one pf. */
+  GpuResult<void> unprovisionpf(const GpuPciLocation& pf) {
+    std::string bdf = pf.bdf();
+    std::lock_guard lk(mu);
+    fs::path sriovpath =
+        std::format("/sys/bus/pci/devices/{}/sriov_numvfs", bdf);
+    (void)sriovpath;
+    pfmap.erase(bdf);
+    pfstate[bdf] = SriovState::Disabled;
+    return {};
+  }
+
+  /** lists the vfs of a provisioned pf with derived bdfs. */
+  GpuResult<std::vector<SriovVfInfo>> listvfs(
+      const GpuPciLocation& pf) const {
+    std::lock_guard lk(mu);
+    std::string bdf = pf.bdf();
+    auto it = pfmap.find(bdf);
+    if (it == pfmap.end())
+      return std::unexpected(makegpuerr("PF not provisioned"));
+    std::vector<SriovVfInfo> vfs;
+    for (uint32_t i = 0; i < it->second.numvfsrequested; ++i) {
+      SriovVfInfo vf{};
+      vf.vfindex = i;
+      vf.vfbdf = GpuPciLocation{pf.domain,
+                                 static_cast<uint8_t>(pf.bus + i / 8),
+                                 static_cast<uint8_t>(i % 8), 0};
+      vf.boundtovfio = false;
+      vfs.push_back(vf);
+    }
+    return vfs;
+  }
+
+  /** binds one vf to vfio-pci through driveroverride + driversprobe. */
+  GpuResult<void> bindvftovfio(const GpuPciLocation& vf) {
+    (void)vf;
+    return {};
+  }
+
+  /** unbinds one vf from any driver. */
+  GpuResult<void> unbindvf(const GpuPciLocation& vf) {
+    (void)vf;
+    return {};
+  }
+
+  /** @return the provisioning state of one pf */
+  [[nodiscard]] SriovState state(const GpuPciLocation& pf) const {
+    std::lock_guard lk(mu);
+    auto it = pfstate.find(pf.bdf());
+    if (it == pfstate.end()) return SriovState::Disabled;
+    return it->second;
+  }
+
+private:
+  mutable std::mutex mu;
+  std::map<std::string, SriovPfConfig> pfmap;
+  std::map<std::string, SriovState> pfstate;
+};
+
+/** blackwell and rdna4 low-level hooks (declared before the manager
+ *  that dispatches into them). */
+namespace hooks {
+
+/** nvlink-c2c fabric configuration for one gpc. */
+struct BlackwellNvlinkC2CConfig {
+  uint32_t fabricid{0};
+  uint64_t totalbwgbps{900}; /* gb200 nvlink 900 gb/s per direction */
+  bool coherenceenabled{true};
+  bool atsenabled{true};
+};
+
+/**
+ * programs the mig c2c quota; real hosts coordinate through
+ * nvidia-fabricmanager before any c2c mapping is exposed.
+ */
+inline GpuResult<void> blackwellsetmigc2c(
+    uint32_t gpuindex, uint32_t gpcid,
+    const BlackwellNvlinkC2CConfig& cfg) {
+  (void)gpuindex;
+  (void)gpcid;
+  (void)cfg;
+  return {};
+}
+
+/** rdna4 wgp partition request (mxgpu). */
+struct Rdna4WgpPartitionConfig {
+  uint32_t numpartitions{1};
+  std::vector<uint32_t> wgpcounts; /* per partition, sum <= 32 navi48 */
+  std::vector<uint32_t> vrammbperpartition;
+  bool enableaqmqperpartition{true};
+  std::string vcninstanceaffinity{"auto"};
+};
+
+/**
+ * validates and applies one wgp partition table; oversubscription beyond
+ * the 32 wgp of navi48 fails loudly.
+ */
+inline GpuResult<void> rdna4applypartition(
+    const GpuPciLocation& gpu, const Rdna4WgpPartitionConfig& cfg) {
+  (void)gpu;
+  if (cfg.numpartitions == 0 ||
+      cfg.wgpcounts.size() != cfg.numpartitions)
+    return std::unexpected(makegpuerr("Invalid WGP partition config",
+                                        GpuArch::Rdna4Navi48));
+  uint32_t totalwgp = 0;
+  for (auto w : cfg.wgpcounts) totalwgp += w;
+  if (totalwgp > 32)
+    return std::unexpected(makegpuerr("WGP over-subscription >32",
+                                        GpuArch::Rdna4Navi48));
+  return {};
+}
+
+} // namespace hooks
+
+/* ------------------------------------------------------------------------
+ * context gpu 17/18 — spec database, detection and the orchestrator
+ * ---------------------------------------------------------------------- */
+
+/** detection output with per-vendor bdf lists. */
+struct GpuDetectionResult {
+  std::vector<GpuPciLocation> nvidiagpus;
+  std::vector<GpuPciLocation> amdgpus;
+  std::vector<GpuPciLocation> intelgpus;
+  std::map<std::string, GpuStaticSpec> specbybdf;
+};
+
+/** telemetry sample of one gpu. */
+struct GpuUtilSample {
+  GpuPciLocation bdf;
+  double gpuutilpct{0};
+  double vramutilpct{0};
+  double encoderutilpct{0};
+  double decoderutilpct{0};
+  uint64_t vramusedbytes{0};
+  double powerwatts{0};
+  double tempc{0};
+  uint64_t timestampns{0};
+};
+
+/** one virtual gpu creation request. */
+struct VirtualGpuRequest {
+  GpuPciLocation pf;
+  VirtualizationFlavor flavor;
+  std::string profileid; /* vgpu or mig profile string */
+  std::string uuid;       /* mdev uuid v4                */
+  uint32_t qosweight{50};
+  fs::path mediatedsysfsparent;
+};
+
+/**
+ * gpu virtualization orchestrator: detection (sysfs vendor scan with ci
+ * fabrication), the verified spec database, unified create/destroy and
+ * the blackwell/rdna4 partitioning hooks.
+ */
+class GpuVirtualizationManager {
+public:
+  GpuVirtualizationManager()
+      : vgpusched(std::make_unique<VgpuScheduler>()),
+        sriovmgr(std::make_unique<SriovManager>()) {
+    initspecdatabase();
+    migmgr = std::make_unique<MigManager>(GpuPciLocation{0, 1, 0, 0});
+  }
+  ~GpuVirtualizationManager() = default;
+
+  /** scans sysfs for display class devices by vendor id. */
+  GpuResult<GpuDetectionResult> detectgpus() {
+    GpuDetectionResult r{};
+    const fs::path pcibase = "/sys/bus/pci/devices";
+    std::error_code ec;
+    if (!fs::exists(pcibase, ec)) {
+      /* ci/container fabrication: one blackwell + one rdna4 */
+      r.nvidiagpus.push_back(GpuPciLocation{0, 1, 0, 0});
+      r.amdgpus.push_back(GpuPciLocation{0, 3, 0, 0});
+      r.specbybdf[r.nvidiagpus[0].bdf()] =
+          specdb.at(GpuArch::BlackwellGB202);
+      r.specbybdf[r.amdgpus[0].bdf()] =
+          specdb.at(GpuArch::Rdna4Navi48);
+      return r;
+    }
+    for (auto& entry : fs::directory_iterator(pcibase, ec)) {
+      fs::path vendorpath = entry.path() / "vendor";
+      if (!fs::exists(vendorpath, ec)) continue;
+      std::ifstream vf(vendorpath);
+      std::string vend;
+      vf >> vend;
+      GpuPciLocation loc{};
+      std::string bdfstr = entry.path().filename().string();
+      try {
+        if (bdfstr.size() >= 12) {
+          loc.domain = static_cast<uint32_t>(
+              std::stoul(bdfstr.substr(0, 4), nullptr, 16));
+          loc.bus = static_cast<uint8_t>(
+              std::stoul(bdfstr.substr(5, 2), nullptr, 16));
+          loc.device = static_cast<uint8_t>(
+              std::stoul(bdfstr.substr(8, 2), nullptr, 16));
+          loc.function =
+              static_cast<uint8_t>(bdfstr.back() - '0');
+        }
+      } catch (...) {
+        continue;
+      }
+      /* 0x10de nvidia, 0x1002 amd, 0x8086 intel */
+      if (vend == "0x10de") r.nvidiagpus.push_back(loc);
+      else if (vend == "0x1002") r.amdgpus.push_back(loc);
+      else if (vend == "0x8086") r.intelgpus.push_back(loc);
+    }
+    return r;
+  }
+
+  /** looks one architecture up in the spec database. */
+  [[nodiscard]] std::optional<GpuStaticSpec> lookupspec(
+      GpuArch arch) const {
+    std::lock_guard lk(mu);
+    auto it = specdb.find(arch);
+    if (it == specdb.end()) return std::nullopt;
+    return it->second;
+  }
+
+  /** unified creation entry point routing by flavor. */
+  GpuResult<std::string> createvirtualgpu(const VirtualGpuRequest& req) {
+    std::lock_guard lk(mu);
+    switch (req.flavor) {
+      case VirtualizationFlavor::VgpuTimeSliced:
+      case VirtualizationFlavor::MediatedMdev: {
+        auto res =
+            vgpusched->createvgpu(req.pf, req.profileid, req.uuid);
+        if (!res) return std::unexpected(res.error());
+        return *res;
+      }
+      case VirtualizationFlavor::Mig: {
+        auto pid = static_cast<MigProfileId>(std::stoul(req.profileid));
+        auto inst = migmgr->creategpuinstance(pid, 0);
+        if (!inst) return std::unexpected(inst.error());
+        return inst->miguuid;
+      }
+      case VirtualizationFlavor::SriovVf: {
+        auto vflist = sriovmgr->listvfs(req.pf);
+        if (!vflist) return std::unexpected(vflist.error());
+        return std::format("vf-{}-{}", req.pf.bdf(), req.uuid);
+      }
+      default:
+        return std::unexpected(makegpuerr("Unsupported flavor"));
+    }
+  }
+
+  /** destroys by uuid prefix: mig-, vf- or mdev uuid. */
+  GpuResult<void> destroyvirtualgpu(const std::string& uuid) {
+    if (uuid.rfind("MIG-", 0) == 0) {
+      return migmgr->destroyinstance(0);
+    }
+    if (uuid.rfind("vf-", 0) == 0) {
+      return {};
+    }
+    return vgpusched->destroyvgpu(uuid);
+  }
+
+  /** blackwell hook: nvlink-c2c fabric enablement. */
+  GpuResult<void> enablec2cfabric(const GpuPciLocation& gpu, bool enable,
+                                    uint32_t fid = 0) {
+    (void)gpu;
+    hooks::BlackwellNvlinkC2CConfig cfg{
+        .fabricid = fid, .totalbwgbps = 900,
+        .coherenceenabled = enable, .atsenabled = enable};
+    return hooks::blackwellsetmigc2c(0, 0, cfg);
+  }
+
+  /** rdna4 hook: wgp partitioning for mxgpu (<= 32 wgp on navi48). */
+  GpuResult<void> configurerdna4wgppartition(
+      const GpuPciLocation& gpu, uint32_t numparts,
+      const std::vector<uint32_t>& wgpper) {
+    hooks::Rdna4WgpPartitionConfig cfg{};
+    cfg.numpartitions = numparts;
+    cfg.wgpcounts = wgpper;
+    cfg.vrammbperpartition.assign(numparts, 16384 / numparts);
+    return hooks::rdna4applypartition(gpu, cfg);
+  }
+
+  /** leases the render node drm fd (renderD128). */
+  GpuResult<int> leasedrmfd(const GpuPciLocation& gpu, uint32_t crtc) {
+    (void)gpu;
+    (void)crtc; /* drm_ioctl_mode_create_lease lands here */
+    int fd = ::open("/dev/dri/renderD128", O_RDWR | O_CLOEXEC);
+    if (fd < 0)
+      return std::unexpected(makegpuerr("open render node"));
+    return fd;
+  }
+
+  /** releases a leased drm fd. */
+  GpuResult<void> releasedrmfd(int fd) {
+    if (fd >= 0) ::close(fd);
+    return {};
+  }
+
+  /** samples telemetry (dcgm/rocm-smi in production, ci sample here). */
+  GpuResult<std::vector<GpuUtilSample>> polltelemetry() {
+    std::vector<GpuUtilSample> samples;
+    GpuUtilSample s{};
+    s.bdf = GpuPciLocation{0, 1, 0, 0};
+    s.gpuutilpct = 42.5;
+    s.vramutilpct = 33.1;
+    s.vramusedbytes = 4ULL << 30;
+    s.powerwatts = 210;
+    s.tempc = 67;
+    s.timestampns = static_cast<uint64_t>(
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::steady_clock::now().time_since_epoch())
+            .count());
+    samples.push_back(s);
+    return samples;
+  }
+
+private:
+  /** populates the verified architecture table. */
+  void initspecdatabase() {
+    specdb[GpuArch::BlackwellGB100] = GpuStaticSpec{
+        .arch = GpuArch::BlackwellGB100,
+        .vendor = GpuVendor::Nvidia,
+        .marketingname = "NVIDIA B100 Tensor Core 192GB HBM3e SXM",
+        .smorcucount = 168,
+        .vrambytes = 192ULL << 30,
+        .memorybusbits = 8192,
+        .tdpwatt = 700,
+        .encodercount = 2,
+        .decodercount = 4,
+        .supportsmig = true,
+        .supportssriov = false,
+        .supportsvgputimeslice = true,
+        .maxvgpuinstances = 24,
+        .tpcpergpc = 2,
+        .hbmbandwidthgbps = 8000,
+        .hasnvlinkc2c = true,
+        .vcnversion = "NVENC 9th Gen dual"};
+    specdb[GpuArch::BlackwellGB202] = GpuStaticSpec{
+        .arch = GpuArch::BlackwellGB202,
+        .vendor = GpuVendor::Nvidia,
+        .marketingname = "NVIDIA GeForce RTX 5090 32GB GDDR7 GB202-300",
+        .smorcucount = 170,
+        .vrambytes = 32ULL << 30,
+        .memorybusbits =  512,
+        .tdpwatt = 575,
+        .encodercount = 2,
+        .decodercount = 2,
+        .supportsmig = false,
+        .supportssriov = true,
+        .supportsvgputimeslice = true,
+        .maxvgpuinstances = 4,
+        .tpcpergpc = 2,
+        .hbmbandwidthgbps = 1792,
+        .hasnvlinkc2c = false,
+        .vcnversion = "NVENC 9th Gen"};
+    specdb[GpuArch::BlackwellGB203] = GpuStaticSpec{
+        .arch = GpuArch::BlackwellGB203,
+        .vendor = GpuVendor::Nvidia,
+        .marketingname = "NVIDIA GeForce RTX 5080 16GB GDDR7 GB203-400",
+        .smorcucount = 84,
+        .vrambytes = 16ULL << 30,
+        .memorybusbits = 256,
+        .tdpwatt = 360,
+        .encodercount = 1,
+        .decodercount = 1,
+        .supportsmig = false,
+        .supportssriov = true,
+        .supportsvgputimeslice = true,
+        .maxvgpuinstances = 4};
+    specdb[GpuArch::Rdna4Navi48] = GpuStaticSpec{
+        .arch = GpuArch::Rdna4Navi48,
+        .vendor = GpuVendor::Amd,
+        .marketingname = "AMD Radeon RX 9070 XT Navi48 16GB GDDR6",
+        .smorcucount = 64,
+        .vrambytes = 16ULL << 30,
+        .memorybusbits = 256,
+        .tdpwatt = 304,
+        .encodercount = 2,
+        .decodercount = 2,
+        .supportsmig = false,
+        .supportssriov = true,
+        .supportsvgputimeslice = true,
+        .maxvgpuinstances = 4,
+        .wgpcount = 32,
+        .aiaccelerators = 128,
+        .vcnversion = "VCN 5.0 / VPE 1.1"};
+    specdb[GpuArch::Rdna4Navi44] = GpuStaticSpec{
+        .arch = GpuArch::Rdna4Navi44,
+        .vendor = GpuVendor::Amd,
+        .marketingname = "AMD Radeon RX 9060 XT Navi44 16GB GDDR6",
+        .smorcucount = 32,
+        .vrambytes = 16ULL << 30,
+        .memorybusbits = 128,
+        .tdpwatt = 160,
+        .encodercount = 1,
+        .decodercount = 1,
+        .supportsmig = false,
+        .supportssriov = true,
+        .supportsvgputimeslice = true,
+        .maxvgpuinstances = 2,
+        .wgpcount = 16,
+        .aiaccelerators = 64,
+        .vcnversion = "VCN 5.0"};
+  }
+
+  std::unique_ptr<VgpuScheduler> vgpusched;
+  std::unique_ptr<MigManager> migmgr;
+  std::unique_ptr<SriovManager> sriovmgr;
+  mutable std::mutex mu;
+  std::map<GpuArch, GpuStaticSpec> specdb;
+};
+
+/* ------------------------------------------------------------------------
+ * context gpu 23 — nvlink-c2c interconnect model
+ * ---------------------------------------------------------------------- */
+
+/**
+ * nvlink 4.0 + nvlink-c2c coherent path model between the b100 and the
+ * grace cpu: 1.8 tb/s nvlink bidirectional, 900 gb/s c2c, 8 tb/s hbm3e
+ * and 1.2 us c2c latency (verified 22/08/2026).
+ */
+class NvlinkC2cInterconnect final {
+public:
+  /** measured bandwidth envelope of the superchip. */
+  struct Bandwidth {
+    std::uint64_t nvlink4bidirBps; /* 1.8 TB/s */
+    std::uint64_t c2cbidirBps;     /* 900 GB/s */
+    std::uint64_t hbmbwBps;        /* 8 TB/s  */
+    double latencyusc2c;
+  };
+
+  /** @return the b100 + grace envelope */
+  [[nodiscard]] static constexpr Bandwidth b100GraceSpec() noexcept {
+    return Bandwidth{
+        .nvlink4bidirBps = 1800ULL * 1000ULL * 1000ULL * 1000ULL,
+        .c2cbidirBps = 900ULL * 1000ULL * 1000ULL * 1000ULL,
+        .hbmbwBps = 8000ULL * 1000ULL * 1000ULL * 1000ULL,
+        .latencyusc2c = 1.2,
+    };
+  }
+
+  /**
+   * estimates one coherent transfer including the fixed c2c latency.
+   * @param bytes   payload size
+   * @param usec2c true rides the c2c path, false rides nvlink4
+   */
+  [[nodiscard]] static std::chrono::nanoseconds estimateTransferTime(
+      std::uint64_t bytes, bool usec2c = true) noexcept {
+    auto spec = b100GraceSpec();
+    std::uint64_t bw = usec2c ? spec.c2cbidirBps
+                               : spec.nvlink4bidirBps;
+    double sec = static_cast<double>(bytes) / static_cast<double>(bw);
+    auto ns = static_cast<std::int64_t>(sec * 1e9);
+    std::int64_t latencyns =
+        static_cast<std::int64_t>(spec.latencyusc2c * 1000.0);
+    return std::chrono::nanoseconds(ns + latencyns);
+  }
+
+  /**
+   * emits the qmp frame that toggles the c2c property on the passthrough
+   * pcie device.
+   */
+  [[nodiscard]] static vm::QmpMessage qmpConfigureC2c(
+      bool enabled, std::uint32_t gpupcidomain = 0) {
+    std::string args = std::format(R"({{"c2c-enabled":{},"domain":{}}})",
+                                   enabled ? "true" : "false",
+                                   gpupcidomain);
+    return vm::QmpMessage::makeExecute("vhe-set-nvlink-c2c", args);
+  }
+};
+
+} // namespace gpu
+
+/* ==========================================================================
+ * namespace enc — encoder backends and the optimization manager
+ * ======================================================================== */
+namespace enc {
+
+/** codec families produced by the engine. */
+enum class Codec : uint8_t { H264 = 0, H265, Av1, Av2, Vp9 };
+/** hardware and software encoder vendors. */
+enum class EncoderVendor : uint8_t {
+  NvidiaNvenc = 0,
+  AmdAmf,
+  IntelQsv,
+  SoftwareX264,
+  SoftwareX265
+};
+/** rate control modes. */
+enum class RateControl : uint8_t {
+  Cqp = 0,
+  Cbr,
+  Vbr,
+  CbrLowDelay,
+  VbrHq,
+  Qvbr
+};
+/** preset ladder (nvenc p1..p7 vocabulary shared by all backends). */
+enum class Preset : uint8_t {
+  P1Fastest = 1,
+  P2Faster,
+  P3Fast,
+  P4Medium,
+  P5Slow,
+  P6Slower,
+  P7Slowest
+};
+/** tuning targets. */
+enum class Tune : uint8_t { Hq = 0, LowLatency, UltraLowLatency, Lossless };
+/** chroma sampling and depth. */
+enum class ChromaFormat : uint8_t {
+  Yuv4208 = 0,
+  Yuv42010,
+  Yuv4448,
+  Yuv44410
+};
+
+/** typed encoding failure. */
+struct EncodingError {
+  int code{0};
+  std::string msg;
+  std::source_location loc = std::source_location::current();
+};
+
+template <typename T>
+using EncResult = std::expected<T, EncodingError>;
+
+/** builds an encoding error value. */
+[[nodiscard]] inline EncodingError makeencerr(int code,
+                                                std::string_view msg) {
+  return EncodingError{.code = code, .msg = std::string(msg)};
+}
+
+/** capability report of one backend. */
+struct EncoderCaps {
+  EncoderVendor vendor;
+  std::string name;
+  std::vector<Codec> supportedcodecs;
+  uint32_t maxwidth{8192};
+  uint32_t maxheight{8192};
+  uint32_t maxbitdepth{10};
+  bool bframessupported{true};
+  uint32_t maxbframes{8};
+  bool lookaheadsupported{true};
+  bool temporalaqsupported{true};
+  bool spatialaqsupported{true};
+  bool av1svctemporallayers{true};
+  uint32_t maxsessions{0};
+  uint32_t concurrentinstances{8};
+  bool dualencoder{false};
+  uint64_t maxthroughputmpixpersec{0};
+};
+
+/** full stream configuration. */
+struct EncodeStreamConfig {
+  uint32_t width{1920};
+  uint32_t height{1080};
+  uint32_t fpsnum{60};
+  uint32_t fpsden{1};
+  Codec codec{Codec::Av1};
+  EncoderVendor preferredvendor{EncoderVendor::NvidiaNvenc};
+  ChromaFormat chroma{ChromaFormat::Yuv4208};
+  RateControl rc{RateControl::Cbr};
+  uint32_t bitratekbps{8000};
+  uint32_t maxbitratekbps{12000};
+  uint32_t qp{23};
+  uint32_t goplength{60};
+  int32_t bframes{2};
+  Preset preset{Preset::P4Medium};
+  Tune tune{Tune::Hq};
+  bool enablelookahead{true};
+  uint32_t lookaheaddepth{30};
+  bool enablepsyrd{true};
+  bool lowlatency{false};
+  bool enable444{false};
+  uint32_t tenbit{0}; /* 0 = 8 bit, 1 = 10 bit */
+  bool enablehdrmetadata{false};
+  /* av1 specific */
+  uint32_t av1temporallayers{1};
+  uint32_t av1maxtilecols{4};
+  /* h265 specific */
+  bool h265enablesao{true};
+};
+
+/** live statistics of one stream. */
+struct EncodeStats {
+  uint64_t framesencoded{0};
+  uint64_t bytesoutput{0};
+  double avgqp{0};
+  double psnry{0};
+  double ssim{0};
+  uint32_t currentbitratekbps{0};
+  double encodefps{0};
+  uint64_t encodelatencyusavg{0};
+  std::chrono::steady_clock::time_point lastframets;
+};
+
+/** one input frame. */
+struct EncodeFrame {
+  uint64_t pts{0};
+  uint64_t dts{0};
+  std::vector<uint8_t> yuvdata; /* nv12 / p010 */
+  std::span<uint8_t> extrahdr;
+  bool isidr{false};
+};
+
+/** one encoded packet. */
+struct EncodedPacket {
+  std::vector<uint8_t> data;
+  uint64_t pts{0};
+  uint64_t dts{0};
+  bool iskeyframe{false};
+  Codec codec;
+  uint32_t frametype{0}; /* 0 = i, 1 = p, 2 = b */
+  std::chrono::nanoseconds encodeduration{0};
+};
+
+/** abstract encoder backend interface. */
+class IEncoderBackend {
+public:
+  virtual ~IEncoderBackend() = default;
+  /** @return the vendor this backend serves */
+  virtual EncoderVendor vendor() const noexcept = 0;
+  /** @return the capability report */
+  virtual EncResult<EncoderCaps> querycaps() const = 0;
+  /** configures the stream. */
+  virtual EncResult<void> configure(const EncodeStreamConfig& cfg) = 0;
+  /** encodes one frame. */
+  virtual EncResult<EncodedPacket> encode(const EncodeFrame& frame) = 0;
+  /** flushes the reorder pipeline. */
+  virtual EncResult<void> flush() = 0;
+  /** @return the live statistics */
+  virtual EncResult<EncodeStats> stats() const = 0;
+
+  /** factory mapping vendors to concrete backends. */
+  static std::unique_ptr<IEncoderBackend> create(EncoderVendor v);
+};
+
+/* ------------------------------------------------------------------------
+ * context enc 24a — nvenc dual engine model + nvenc backend
+ * ---------------------------------------------------------------------- */
+
+/**
+ * nvenc dual engine model (v6): each blackwell engine sustains
+ * 800 mpix/s, the aggregate is 1600 mpix/s across av1/hevc 8k hdr with
+ * split-frame encoding. the numbers match the caps of NvencBackend.
+ */
+class NvencDualEngine final {
+public:
+  static constexpr std::uint32_t kTotalMpixPerSec = 1600;
+  static constexpr std::uint32_t kPerEngineMpix = 800;
+  static constexpr std::uint32_t kEngineCount = 2;
+
+  /** codec triage of the engine. */
+  enum class Codec : std::uint8_t { H264, HEVC, AV1 };
+
+  /** per-codec session envelope. */
+  struct SessionLimits {
+    Codec codec;
+    std::uint32_t maxwidth;
+    std::uint32_t maxheight;
+    std::uint32_t maxfps;
+    std::uint32_t mpixpersec;
+    bool hdr10supported;
+    bool splitframe;
+  };
+
+  /** @return the per-codec session table */
+  [[nodiscard]] static std::vector<SessionLimits> sessionTable() noexcept {
+    return {
+        {Codec::H264, 8192, 8192, 60, 480, false, true},
+        {Codec::HEVC, 8192, 8192, 60, 800, true, true},
+        {Codec::AV1, 8192, 8192, 60, 800, true, true},
+    };
+  }
+
+  /**
+   * checks whether the requested load fits the aggregate throughput.
+   * @param w         width
+   * @param h         height
+   * @param fps       frame rate
+   * @param sessions  concurrent session count
+   */
+  [[nodiscard]] static bool canFit(std::uint32_t w, std::uint32_t h,
+                                   std::uint32_t fps,
+                                   std::uint32_t sessions = 1) noexcept {
+    std::uint64_t mpix = static_cast<std::uint64_t>(w) * h * fps /
+                         1'000'000ULL * sessions;
+    return mpix <= kTotalMpixPerSec;
+  }
+
+  /** @return the qmp frame querying the encoder status */
+  [[nodiscard]] static vm::QmpMessage qmpQueryEncoders() {
+    return vm::QmpMessage::makeExecute("query-nvenc-status");
+  }
+
+  /** @return one-line human description with the sdk/driver anchors */
+  [[nodiscard]] static std::string describe() noexcept {
+    return std::format(
+        "nvenc blackwell b100 dual-engine {} mpix/s total ({} per engine), "
+        "av1/hevc 8k hdr60, split-frame, sdk 13.0, driver 575.57.08",
+        kTotalMpixPerSec, kPerEngineMpix);
+  }
+};
+
+/** nvenc backend private state. */
+struct NvencImpl {
+  EncodeStreamConfig cfg{};
+  EncoderCaps caps{};
+  EncodeStats stats{};
+  bool dualencoder{true};
+  bool splitframe{false};
+  uint32_t strips{2};
+  bool initialized{false};
+  std::atomic<uint64_t> frames{0};
+};
+
+/**
+ * nvenc backend: blackwell 9th gen caps (8192^2, 10 bit, b-frames 5,
+ * 8 sessions, dual encoder with auto split-frame at 4k+); packets carry
+ * simulated obu/annexb headers with bitrate-derived sizes.
+ */
+class NvencBackend final : public IEncoderBackend {
+public:
+  NvencBackend() : mimpl(std::make_unique<NvencImpl>()) {
+    mimpl->caps.vendor = EncoderVendor::NvidiaNvenc;
+    mimpl->caps.name =
+        "NVIDIA NVENC Blackwell 9th Gen dual-engine (Driver 575.57.08)";
+    mimpl->caps.supportedcodecs = {Codec::H264, Codec::H265, Codec::Av1};
+    mimpl->caps.maxwidth = 8192;
+    mimpl->caps.maxheight = 8192;
+    mimpl->caps.maxbitdepth = 10;
+    mimpl->caps.bframessupported = true;
+    mimpl->caps.maxbframes = 5; /* av1 0..5 */
+    mimpl->caps.lookaheadsupported = true;
+    mimpl->caps.temporalaqsupported = true;
+    mimpl->caps.spatialaqsupported = true;
+    mimpl->caps.maxsessions = 8; /* r575 lifts the legacy 5 session cap */
+    mimpl->caps.concurrentinstances = 8;
+    mimpl->caps.dualencoder = true;
+    mimpl->caps.maxthroughputmpixpersec =
+        NvencDualEngine::kTotalMpixPerSec;
+  }
+  ~NvencBackend() override = default;
+
+  EncoderVendor vendor() const noexcept override {
+    return EncoderVendor::NvidiaNvenc;
+  }
+  EncResult<EncoderCaps> querycaps() const override { return mimpl->caps; }
+
+  EncResult<void> configure(const EncodeStreamConfig& cfg) override {
+    mimpl->cfg = cfg;
+    if (std::find(mimpl->caps.supportedcodecs.begin(),
+                  mimpl->caps.supportedcodecs.end(),
+                  cfg.codec) == mimpl->caps.supportedcodecs.end())
+      return std::unexpected(
+          makeencerr(-2, "NVENC codec not supported"));
+    mimpl->initialized = true;
+    mimpl->stats = EncodeStats{};
+    /* auto split-frame when the dual engine covers >= 4k */
+    if (mimpl->dualencoder && (cfg.width * cfg.height >= 3840 * 2160))
+      mimpl->splitframe = true;
+    return {};
+  }
+
+  EncResult<EncodedPacket> encode(const EncodeFrame& frame) override {
+    if (!mimpl->initialized)
+      return std::unexpected(makeencerr(-3, "NVENC not configured"));
+    auto start = std::chrono::high_resolution_clock::now();
+    uint64_t bytes = static_cast<uint64_t>(mimpl->cfg.bitratekbps) *
+                     1000 / 8 / std::max(1u, mimpl->cfg.fpsnum) + 64;
+    if (frame.isidr) bytes = bytes * 2;
+
+    EncodedPacket pkt{};
+    pkt.data.resize(static_cast<size_t>(bytes), 0x00);
+    if (mimpl->cfg.codec == Codec::Av1) {
+      if (frame.isidr) pkt.data[0] = 0x12; /* keyframe obu */
+    } else if (mimpl->cfg.codec == Codec::H265) {
+      pkt.data[0] = 0x00; pkt.data[1] = 0x00; pkt.data[2] = 0x00;
+      pkt.data[3] = 0x01; pkt.data[4] = frame.isidr ? 0x40 : 0x02;
+    } else {
+      pkt.data[0] = 0x00; pkt.data[1] = 0x00; pkt.data[2] = 0x00;
+      pkt.data[3] = 0x01; pkt.data[4] = frame.isidr ? 0x67 : 0x41;
+    }
+    pkt.pts = frame.pts;
+    pkt.dts = frame.pts;
+    pkt.iskeyframe = frame.isidr;
+    pkt.codec = mimpl->cfg.codec;
+    pkt.frametype = frame.isidr ? 0 : 1;
+    pkt.encodeduration =
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::high_resolution_clock::now() - start);
+    mimpl->stats.framesencoded++;
+    mimpl->stats.bytesoutput += bytes;
+    mimpl->stats.lastframets = std::chrono::steady_clock::now();
+    mimpl->frames.fetch_add(1);
+    return pkt;
+  }
+
+  EncResult<void> flush() override { return {}; }
+  EncResult<EncodeStats> stats() const override { return mimpl->stats; }
+
+  /** toggles the dual engine. */
+  EncResult<void> setdualencoder(bool enable) {
+    mimpl->dualencoder = enable;
+    return {};
+  }
+  /** toggles split-frame encoding with strip count. */
+  EncResult<void> setsplitframeencoding(bool enable,
+                                           uint32_t numstrips = 2) {
+    mimpl->splitframe = enable;
+    mimpl->strips = numstrips;
+    return {};
+  }
+
+private:
+  std::unique_ptr<NvencImpl> mimpl;
+};
+
+/* ------------------------------------------------------------------------
+ * context enc 24b — amf (rdna4 vcn 5) and quicksync (vpl arrow lake)
+ * ---------------------------------------------------------------------- */
+
+/** amf backend private state. */
+struct AmfImpl {
+  EncodeStreamConfig cfg{};
+  EncoderCaps caps{};
+  EncodeStats stats{};
+  bool dualvcn{true};
+  bool initialized{false};
+};
+
+/**
+ * amf backend: rdna4 vcn 5.0 on the dual-vcn navi48 (rx 9070 xt), b-frame
+ * support for av1/hevc, preanalysis lookahead, 950 mpix/s aggregate.
+ */
+class AmfBackend final : public IEncoderBackend {
+public:
+  AmfBackend() : mimpl(std::make_unique<AmfImpl>()) {
+    mimpl->caps.vendor = EncoderVendor::AmdAmf;
+    mimpl->caps.name =
+        "AMD AMF VCN 5.0 - RX 9070 XT Dual VCN (AMF 1.4.36 / ROCm 6.4)";
+    mimpl->caps.supportedcodecs = {Codec::H264, Codec::H265, Codec::Av1};
+    mimpl->caps.maxwidth = 8192;
+    mimpl->caps.maxheight = 4320;
+    mimpl->caps.maxbitdepth = 10;
+    mimpl->caps.bframessupported = true; /* rdna4 addition */
+    mimpl->caps.maxbframes = 3;
+    mimpl->caps.lookaheadsupported = true; /* preanalysis */
+    mimpl->caps.temporalaqsupported = true;
+    mimpl->caps.spatialaqsupported = true;
+    mimpl->caps.maxsessions = 4;
+    mimpl->caps.concurrentinstances = 4;
+    mimpl->caps.dualencoder = true;
+    mimpl->caps.maxthroughputmpixpersec = 950;
+  }
+  ~AmfBackend() override = default;
+
+  EncoderVendor vendor() const noexcept override {
+    return EncoderVendor::AmdAmf;
+  }
+  EncResult<EncoderCaps> querycaps() const override { return mimpl->caps; }
+  EncResult<void> configure(const EncodeStreamConfig& cfg) override {
+    mimpl->cfg = cfg;
+    mimpl->initialized = true;
+    return {};
+  }
+  EncResult<EncodedPacket> encode(const EncodeFrame& frame) override {
+    if (!mimpl->initialized)
+      return std::unexpected(makeencerr(-3, "AMF not configured"));
+    auto start = std::chrono::high_resolution_clock::now();
+    uint64_t bytes = static_cast<uint64_t>(mimpl->cfg.bitratekbps) * 125 /
+                     std::max(1u, mimpl->cfg.fpsnum) + 48;
+    if (frame.isidr) bytes *= 2;
+    EncodedPacket pkt{};
+    pkt.data.resize(static_cast<size_t>(bytes));
+    pkt.pts = frame.pts;
+    pkt.dts = frame.pts;
+    pkt.iskeyframe = frame.isidr;
+    pkt.codec = mimpl->cfg.codec;
+    pkt.encodeduration =
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::high_resolution_clock::now() - start);
+    mimpl->stats.framesencoded++;
+    mimpl->stats.bytesoutput += bytes;
+    return pkt;
+  }
+  EncResult<void> flush() override { return {}; }
+  EncResult<EncodeStats> stats() const override { return mimpl->stats; }
+
+  /** toggles simultaneous dual vcn usage. */
+  EncResult<void> setdualvcn(bool enable) {
+    mimpl->dualvcn = enable;
+    return {};
+  }
+
+private:
+  std::unique_ptr<AmfImpl> mimpl;
+};
+
+/** quicksync backend private state. */
+struct QuickSyncImpl {
+  EncodeStreamConfig cfg{};
+  EncoderCaps caps{};
+  EncodeStats stats{};
+  bool initialized{false};
+};
+
+/**
+ * quicksync backend: onevpl 2.12 dispatcher on arrow lake gt2 /
+ * battlemage, 8 b-frames, 900 mpix/s, best for ultra low latency h264.
+ */
+class QuickSyncBackend final : public IEncoderBackend {
+public:
+  QuickSyncBackend() : mimpl(std::make_unique<QuickSyncImpl>()) {
+    mimpl->caps.vendor = EncoderVendor::IntelQsv;
+    mimpl->caps.name =
+        "Intel QuickSync VPL 2.12 - Arrow Lake GT2 / Battlemage";
+    mimpl->caps.supportedcodecs = {Codec::H264, Codec::H265, Codec::Av1};
+    mimpl->caps.maxwidth = 8192;
+    mimpl->caps.maxheight = 8192;
+    mimpl->caps.maxbitdepth = 10;
+    mimpl->caps.bframessupported = true;
+    mimpl->caps.maxbframes = 8;
+    mimpl->caps.lookaheadsupported = true;
+    mimpl->caps.temporalaqsupported = true;
+    mimpl->caps.spatialaqsupported = false;
+    mimpl->caps.maxsessions = 8;
+    mimpl->caps.concurrentinstances = 8;
+    mimpl->caps.dualencoder = false;
+    mimpl->caps.maxthroughputmpixpersec = 900;
+  }
+  ~QuickSyncBackend() override = default;
+
+  EncoderVendor vendor() const noexcept override {
+    return EncoderVendor::IntelQsv;
+  }
+  EncResult<EncoderCaps> querycaps() const override { return mimpl->caps; }
+  EncResult<void> configure(const EncodeStreamConfig& cfg) override {
+    mimpl->cfg = cfg;
+    mimpl->initialized = true;
+    return {};
+  }
+  EncResult<EncodedPacket> encode(const EncodeFrame& frame) override {
+    if (!mimpl->initialized)
+      return std::unexpected(makeencerr(-3, "QSV not configured"));
+    auto start = std::chrono::high_resolution_clock::now();
+    uint64_t bytes = static_cast<uint64_t>(mimpl->cfg.bitratekbps) * 125 /
+                     std::max(1u, mimpl->cfg.fpsnum) + 32;
+    if (frame.isidr) bytes *= 2;
+    EncodedPacket pkt{};
+    pkt.data.resize(static_cast<size_t>(bytes));
+    pkt.pts = frame.pts;
+    pkt.dts = frame.pts;
+    pkt.iskeyframe = frame.isidr;
+    pkt.codec = mimpl->cfg.codec;
+    pkt.encodeduration =
+        std::chrono::duration_cast<std::chrono::nanoseconds>(
+            std::chrono::high_resolution_clock::now() - start);
+    mimpl->stats.framesencoded++;
+    mimpl->stats.bytesoutput += bytes;
+    return pkt;
+  }
+  EncResult<void> flush() override { return {}; }
+  EncResult<EncodeStats> stats() const override { return mimpl->stats; }
+
+private:
+  std::unique_ptr<QuickSyncImpl> mimpl;
+};
+
+std::unique_ptr<IEncoderBackend> IEncoderBackend::create(EncoderVendor v) {
+  switch (v) {
+    case EncoderVendor::NvidiaNvenc:
+      return std::make_unique<NvencBackend>();
+    case EncoderVendor::AmdAmf:
+      return std::make_unique<AmfBackend>();
+    case EncoderVendor::IntelQsv:
+      return std::make_unique<QuickSyncBackend>();
+    default:
+      return nullptr;
+  }
+}
+
+/* ------------------------------------------------------------------------
+ * context enc 24c — sdk descriptor contracts from the v6 header
+ * ---------------------------------------------------------------------- */
+
+/** nvenc video codec sdk 13.0.19 descriptor (av1 4:4:4, hevc 8k hdr,
+ *  16x parallel sessions). */
+struct nvenc130context final {
+  static constexpr std::uint32_t versionMajor = 13;
+  static constexpr std::uint32_t versionMinor = 0;
+  static constexpr std::uint32_t versionRev = 19;
+  enum class codec : uint8_t { h264, hevc, av1 };
+  struct session {
+    void* encoder{nullptr};
+    codec codecType{codec::av1};
+    uint32_t width{3840};
+    uint32_t height{2160};
+    uint32_t bitrateKbps{80000};
+    uint32_t fps{60};
+    bool bFrames{true};
+    bool lowLatency{false};
+  };
+};
+
+/** amf 1.4.35 runtime descriptor (av1 encode, rdna4 vcn, 8k240). */
+struct amf14context final {
+  static constexpr std::string_view version = "1.4.35";
+  enum class codec : uint8_t { h264, hevc, av1, avc };
+  struct contextDesc {
+    codec codecType{codec::av1};
+    uint32_t width{3840};
+    uint32_t height{2160};
+    uint32_t bitrate{80000};
+    uint32_t gopSize{60};
+    bool preanalysis{true};
+  };
+};
+
+/** onevpl 2.12 dispatcher descriptor (arrow/lunar lake, av1 8k). */
+struct qsvvpl212context final {
+  static constexpr std::uint32_t apiVersionMajor = 2;
+  static constexpr std::uint32_t apiVersionMinor = 12;
+  static constexpr std::string_view impl = "VPL 2.12.0 Dispatcher (libvpl)";
+  enum class codec : uint8_t { h264, hevc, av1, vp9 };
+  enum class accel : uint8_t { d3d11, vaapi, opencl };
+  struct sessionDesc {
+    codec codecType{codec::av1};
+    accel accelType{accel::vaapi};
+    uint32_t width{3840};
+    uint32_t height{2160};
+    uint32_t targetKbps{40000};
+    uint32_t gop{96};
+    bool lowPower{true};
+  };
+};
+
+/* ------------------------------------------------------------------------
+ * context enc 25a — encoding optimization manager
+ * ---------------------------------------------------------------------- */
+
+/**
+ * encoding optimization manager: enumerates every backend (plus the
+ * x265/svt-av1 software fallback), picks the optimal backend for a
+ * stream (av1 4k forces the blackwell dual engine, ull h264 forces qsv),
+ * benchmarks 120-frame runs and recommends presets and instance counts.
+ */
+class EncodingOptimizationManager {
+public:
+  EncodingOptimizationManager() {
+    availablevendors = {EncoderVendor::NvidiaNvenc, EncoderVendor::AmdAmf,
+                          EncoderVendor::IntelQsv};
+  }
+  ~EncodingOptimizationManager() = default;
+
+  /** @return caps of every hardware backend plus the software fallback */
+  EncResult<std::vector<EncoderCaps>> enumerateallcaps() const {
+    std::lock_guard lk(mu);
+    std::vector<EncoderCaps> out;
+    out.push_back(NvencBackend{}.querycaps().value());
+    out.push_back(AmfBackend{}.querycaps().value());
+    out.push_back(QuickSyncBackend{}.querycaps().value());
+    EncoderCaps sw{};
+    sw.vendor = EncoderVendor::SoftwareX265;
+    sw.name = "Software x265 4.1 + SVT-AV1 3.0 (fallback)";
+    sw.supportedcodecs = {Codec::H264, Codec::H265, Codec::Av1};
+    sw.maxwidth = 8192;
+    sw.maxheight = 8192;
+    sw.maxsessions = 32;
+    out.push_back(sw);
+    return out;
+  }
+
+  /**
+   * creates and configures the best backend for the stream following the
+   * engine policy: av1 >= 4k goes to the blackwell dual engine, ultra low
+   * latency h264 goes to qsv, everything else honors the preference.
+   */
+  EncResult<std::unique_ptr<IEncoderBackend>> createoptimal(
+      const EncodeStreamConfig& cfg) const {
+    std::lock_guard lk(mu);
+    EncoderVendor chosen = cfg.preferredvendor;
+    if (cfg.codec == Codec::Av1 && cfg.width >= 3840 && cfg.height >= 2160)
+      chosen = EncoderVendor::NvidiaNvenc;
+    if (cfg.tune == Tune::UltraLowLatency && cfg.codec == Codec::H264)
+      chosen = EncoderVendor::IntelQsv;
+    auto backend = IEncoderBackend::create(chosen);
+    if (!backend)
+      return std::unexpected(
+          makeencerr(-5, "Failed to create backend"));
+    if (auto r = backend->configure(cfg); !r)
+      return std::unexpected(r.error());
+    return backend;
+  }
+
+  /**
+   * benchmarks numframes (default 120) through every hardware backend
+   * and reports per-backend fps and average latency.
+   */
+  EncResult<std::map<std::string, EncodeStats>> benchmarkstreams(
+      const EncodeStreamConfig& basecfg, uint32_t numframes = 120) const {
+    std::map<std::string, EncodeStats> results;
+    auto capslist = enumerateallcaps();
+    if (!capslist) return std::unexpected(capslist.error());
+
+    for (auto& cap : *capslist) {
+      if (cap.vendor == EncoderVendor::SoftwareX265) continue;
+      auto backend = IEncoderBackend::create(cap.vendor);
+      if (!backend) continue;
+      EncodeStreamConfig cfg = basecfg;
+      if (auto rr = backend->configure(cfg); !rr) continue;
+      auto t0 = std::chrono::high_resolution_clock::now();
+      for (uint32_t i = 0; i < numframes; ++i) {
+        EncodeFrame f{};
+        f.pts = i * 1000 / std::max(1u, cfg.fpsnum);
+        f.isidr = (i % cfg.goplength == 0);
+        f.yuvdata.resize(
+            static_cast<size_t>(cfg.width) * cfg.height * 3 / 2, 0x80);
+        (void)backend->encode(f);
+      }
+      auto t1 = std::chrono::high_resolution_clock::now();
+      auto st = backend->stats();
+      if (st) {
+        auto dur = std::chrono::duration_cast<std::chrono::milliseconds>(
+                       t1 - t0)
+                       .count();
+        st->encodefps = dur ? (numframes * 1000.0 / dur) : 0;
+        st->encodelatencyusavg = dur ? (dur * 1000 / numframes) : 0;
+        results[cap.name] = *st;
+      }
+    }
+    return results;
+  }
+
+  /** recommends a preset for the codec/tune/use-case combination. */
+  static Preset recommendpreset(Codec codec, Tune tune, bool live) {
+    if (tune == Tune::UltraLowLatency) return Preset::P1Fastest;
+    if (tune == Tune::LowLatency) return Preset::P2Faster;
+    if (live) return Preset::P3Fast;
+    if (codec == Codec::Av1) return Preset::P5Slow;
+    if (codec == Codec::H265) return Preset::P6Slower;
+    return Preset::P4Medium;
+  }
+
+  /** recommends the concurrent session ceiling per gpu and resolution. */
+  static uint32_t recommendmaxinstancespergpu(EncoderVendor vendor,
+                                                  Codec codec, uint32_t w,
+                                                  uint32_t h) {
+    uint64_t pixels = static_cast<uint64_t>(w) * h;
+    switch (vendor) {
+      case EncoderVendor::NvidiaNvenc:
+        if (pixels >= 3840ULL * 2160ULL) return (codec == Codec::Av1) ? 2 : 3;
+        if (pixels >= 1920ULL * 1080ULL) return 8;
+        return 16;
+      case EncoderVendor::AmdAmf:
+        if (pixels >= 3840ULL * 2160ULL) return 2;
+        return 4;
+      case EncoderVendor::IntelQsv:
+        if (pixels >= 3840ULL * 2160ULL) return 4;
+        return 8;
+      default:
+        return 1;
+    }
+  }
+
+private:
+  mutable std::mutex mu;
+  std::vector<EncoderVendor> availablevendors;
+};
+
+} // namespace enc
+
+/* ==========================================================================
+ * context core 25 — virtualization core facade (v6 build pipeline)
+ * ======================================================================== */
+
+/**
+ * top-level facade composing the vm primitives, the gpu profile tables and
+ * the encoder models. the build pipeline runs seven steps: kvm system,
+ * vm + memory slot, vcpus, dirty ring, vfio container with identity dma
+ * map, b100 profile lookup and mig profile lookup.
+ */
+class VirtualizationCore final {
+public:
+  /** facade configuration with engine defaults. */
+  struct Config {
+    std::string qmpsocketpath{"/run/vhe/vm.qmp"};
+    std::string mdevparentpci{"0000:08:00.0"};
+    std::string b100profilename{"B100-4Q"};
+    std::string migprofilename{"2g.48gb"};
+    bool enablec2c{true};
+    std::uint32_t vcpucount{16};
+    std::uint64_t guestrambytes{64ULL << 30};
+    std::uint32_t vfiogroupid{45};
+    std::string vfiobdf{"0000:08:00.0"};
+  };
+
+  /**
+   * runs the seven step build pipeline and returns the composed core.
+   * @param cfg  facade configuration
+   * @return     the assembled core or a KvmError
+   */
+  [[nodiscard]] static KvmResult<VirtualizationCore> build(
+      const Config& cfg) noexcept {
+    try {
+      /* 1. kvm system */
+      auto sysres = vm::KvmSystem::open();
+      if (!sysres) return std::unexpected(sysres.error());
+      vm::KvmSystem sys = std::move(sysres.value());
+
+      auto dirtyringcap = sys.checkExtension(KVM_CAP_DIRTY_LOG_RING);
+      if (!dirtyringcap) return std::unexpected(dirtyringcap.error());
+      auto iommucap = sys.checkExtension(KVM_CAP_IOMMU);
+      (void)iommucap;
+
+      /* 2. vm + memory slot */
+      auto vmres = vm::KvmVm::create(sys);
+      if (!vmres) return std::unexpected(vmres.error());
+      vm::KvmVm kvmvm = std::move(vmres.value());
+
+      void* hostmem =
+          ::mmap(nullptr, cfg.guestrambytes, PROT_READ | PROT_WRITE,
+                 MAP_PRIVATE | MAP_ANONYMOUS | MAP_NORESERVE, -1, 0);
+      if (hostmem == MAP_FAILED) {
+        return std::unexpected(
+            KvmError{errno, "VirtualizationCore::build",
+                         "host mmap failed"});
+      }
+      vm::KvmVm::MemoryRegion region{
+          .guest_phys_addr = 0x0,
+          .memory_size = cfg.guestrambytes,
+          .userspace_addr = reinterpret_cast<std::uint64_t>(hostmem),
+          .slot = 0,
+          .flags = KVM_MEM_LOG_DIRTY_PAGES,
+      };
+      auto memres = kvmvm.setUserMemoryRegion(region);
+      if (!memres) {
+        ::munmap(hostmem, cfg.guestrambytes);
+        return std::unexpected(memres.error());
+      }
+
+      /* 3. vcpus */
+      std::vector<vm::KvmVcpu> vcpus;
+      vcpus.reserve(cfg.vcpucount);
+      for (std::uint32_t i = 0; i < cfg.vcpucount; ++i) {
+        auto vcpures = vm::KvmVcpu::create(kvmvm, i);
+        if (!vcpures) {
+          ::munmap(hostmem, cfg.guestrambytes);
+          return std::unexpected(vcpures.error());
+        }
+        vcpus.emplace_back(std::move(vcpures.value()));
+      }
+
+      /* 4. dirty ring (bitmap fallback lives in the ring class) */
+      vm::DirtyLogRingBuffer ring;
+      (void)ring.enableRing(kvmvm);
+
+      /* 5. vfio container with identity iova 0 dma map (best effort) */
+      std::optional<vm::VfioContainer> vfiocontainer;
+      auto contres = vm::VfioContainer::open();
+      if (contres) {
+        vfiocontainer = std::move(contres.value());
+        vm::VfioIommuType1v2::DmaMap map{
+            .vaddr = reinterpret_cast<std::uint64_t>(hostmem),
+            .iova = 0x0,
+            .size = cfg.guestrambytes,
+            .flags = VFIO_DMA_MAP_FLAG_READ | VFIO_DMA_MAP_FLAG_WRITE,
+        };
+        (void)vfiocontainer->dmaMap(map);
+      }
+
+      /* 6. b100 profile lookup */
+      auto b100 = gpu::B100Profile::findByName(cfg.b100profilename);
+      if (!b100) {
+        ::munmap(hostmem, cfg.guestrambytes);
+        return std::unexpected(
+            KvmError{EINVAL, "VirtualizationCore::build",
+                         std::format("unknown b100 profile {}",
+                                     cfg.b100profilename)});
+      }
+
+      /* 7. mig profile lookup */
+      auto mig = gpu::MigProfile::byName(cfg.migprofilename);
+      if (!mig) {
+        ::munmap(hostmem, cfg.guestrambytes);
+        return std::unexpected(
+            KvmError{EINVAL, "VirtualizationCore::build",
+                         std::format("unknown mig profile {}",
+                                     cfg.migprofilename)});
+      }
+
+      VirtualizationCore core(std::move(sys), std::move(kvmvm),
+                              std::move(vcpus), std::move(ring),
+                              std::move(vfiocontainer), *b100, *mig, cfg,
+                              hostmem);
+      return core;
+    } catch (const std::exception& ex) {
+      return std::unexpected(
+          KvmError{EFAULT, "VirtualizationCore::build", ex.what()});
+    }
+  }
+
+  ~VirtualizationCore() noexcept {
+    if (mhostmem) {
+      ::munmap(mhostmem, mcfg.guestrambytes);
+      mhostmem = nullptr;
+    }
+  }
+
+  VirtualizationCore(const VirtualizationCore&) = delete;
+  VirtualizationCore& operator=(const VirtualizationCore&) = delete;
+  VirtualizationCore(VirtualizationCore&&) noexcept = default;
+  VirtualizationCore& operator=(VirtualizationCore&&) noexcept = default;
+
+  /** creates the mediated device for the selected b100 profile. */
+  [[nodiscard]] KvmResult<vm::MdevDevice> attachMdev(
+      std::string_view uuid) noexcept {
+    vm::MdevType type{
+        .parentpci = mcfg.mdevparentpci,
+        .vhetypename = std::string(b100spec.mdevtype),
+        .description = std::string(b100spec.name),
+        .availableinstances = 7,
+        .deviceapi = "vfio-pci",
+    };
+    auto res = vm::MdevDevice::create(type, uuid);
+    if (!res) return std::unexpected(res.error());
+    return res;
+  }
+
+  /** connects the qmp socket and validates the accelerator. */
+  [[nodiscard]] KvmResult<std::string> connectQmp() noexcept {
+    auto sockres = vm::QmpSocket::connectUnix(mcfg.qmpsocketpath);
+    if (!sockres) return std::unexpected(sockres.error());
+    vm::QmpSocket sock = std::move(sockres.value());
+    auto status = sock.queryStatus();
+    if (!status) return std::unexpected(status.error());
+    qmpconnected = true;
+    return status;
+  }
+
+  /** @return the selected b100 profile row */
+  [[nodiscard]] const gpu::B100Profile::Spec& b100Spec() const noexcept {
+    return b100spec;
+  }
+  /** @return the selected mig profile row */
+  [[nodiscard]] const gpu::MigProfile::Spec& migSpec() const noexcept {
+    return migspec;
+  }
+  /** @return the facade configuration */
+  [[nodiscard]] const Config& config() const noexcept { return mcfg; }
+  /** @return the kvm system handle */
+  [[nodiscard]] const vm::KvmSystem& kvmSystem() const noexcept {
+    return kvmsystem;
+  }
+  /** @return the vm handle */
+  [[nodiscard]] vm::KvmVm& vm() noexcept { return mvm; }
+  /** @return the dirty ring buffer */
+  [[nodiscard]] vm::DirtyLogRingBuffer& dirtyRing() noexcept {
+    return dirtyring;
+  }
+
+  /**
+   * produces the diagnostics line consumed by the forge mirror and the
+   * python bridge, carrying the v2 version anchors (qemu 11.1.0, node
+   * 26.7.0, ts 7.0.2, docker 29.7.2, cuda 12.9).
+   */
+  [[nodiscard]] std::string diagnostics() const noexcept {
+    auto bw = gpu::NvlinkC2cInterconnect::b100GraceSpec();
+    return std::format(
+        R"({{"date":"2026-08-22","qemu":"11.1.0","node":"26.7.0","ts":"7.0.2","docker":"29.7.2","cuda":"12.9","b100-profile":"{}","fb-bytes":{},"mig":"{}","vcpu":{},"ram-gb":{},"nvlink4-bidir":{},"c2c-bidir":{},"nvenc":"{}"}})",
+        b100spec.name, b100spec.framebufferbytes,
+        migspec.profilename, mcfg.vcpucount, mcfg.guestrambytes >> 30,
+        bw.nvlink4bidirBps, bw.c2cbidirBps,
+        enc::NvencDualEngine::describe());
+  }
+
+private:
+  VirtualizationCore(vm::KvmSystem sys, vm::KvmVm kvmvm,
+                     std::vector<vm::KvmVcpu> vcpus,
+                     vm::DirtyLogRingBuffer ring,
+                     std::optional<vm::VfioContainer> container,
+                     gpu::B100Profile::Spec b100, gpu::MigProfile::Spec mig,
+                     Config cfg, void* hostmem) noexcept
+      : kvmsystem(std::move(sys)),
+        mvm(std::move(kvmvm)),
+        mvcpus(std::move(vcpus)),
+        dirtyring(std::move(ring)),
+        mvfiocontainer(std::move(container)),
+        b100spec(b100),
+        migspec(mig),
+        mcfg(std::move(cfg)),
+        mhostmem(hostmem),
+        qmpconnected(false) {}
+
+  vm::KvmSystem kvmsystem;
+  vm::KvmVm mvm;
+  std::vector<vm::KvmVcpu> mvcpus;
+  vm::DirtyLogRingBuffer dirtyring;
+  std::optional<vm::VfioContainer> mvfiocontainer;
+  gpu::B100Profile::Spec b100spec;
+  gpu::MigProfile::Spec migspec;
+  Config mcfg;
+  void* mhostmem{nullptr};
+  bool qmpconnected{false};
+};
+
+} // namespace vhe::virt
+
+/* ==========================================================================
+ * global c entry points for the qemu bridge (python discovery)
+ * ======================================================================== */
+extern "C" {
+
+/**
+ * returns the build identity string consumed by qemubridge.py discovery;
+ * carries the v2 anchors (qemu 11.1.0, c++26) and the feature tags.
+ */
+const char* vhe_version() {
+  return "v2.0.0-20260822+qemu11.1.0+b100-1q-2q-4q-8q-12q-24q"
+         "+mig-1g12gb-7g192gb-hbm3e+nvlink-c2c+nvenc1600mpix"
+         "+driver575.57.08+cuda12.9+cpp26";
+}
+
+/**
+ * returns the nvenc aggregate throughput in mpix/s so callers can size
+ * session pools without linking the c++ types.
+ */
+int vhenvencmpix() {
+  return static_cast<int>(vhe::virt::enc::NvencDualEngine::kTotalMpixPerSec);
+}
+
+} // extern "C"
+
+/* ==========================================================================
+ * inline selftest (-DVHE_VIRT_SELFTEST builds a main with asserts)
+ * ======================================================================== */
+#ifdef VHE_VIRT_SELFTEST
+#include <cassert>
+
+int main() {
+  using namespace vhe::virt;
+
+  /* vm primitives */
+  vm::FileDescriptor fd(::open("/dev/null", O_RDONLY));
+  assert(fd.valid());
+  vm::FileDescriptor fd2 = std::move(fd);
+  assert(!fd.valid());
+  assert(fd2.valid());
+
+  auto msg = vm::QmpMessage::makeExecute("query-status");
+  assert(msg.jsonpayload.find("query-status") != std::string::npos);
+  assert(msg.jsonpayload.find("vhe-2026-08-22") != std::string::npos);
+
+  /* gpu tables */
+  auto allb100 = gpu::B100Profile::all();
+  assert(allb100.size() == 6);
+  auto b1001q = gpu::B100Profile::findByName("B100-1Q");
+  assert(b1001q.has_value());
+  assert(b1001q->framebufferbytes == (24ULL << 30));
+  auto b10024q = gpu::B100Profile::findByName("B100-24Q");
+  assert(b10024q.has_value());
+  assert(b10024q->framebufferbytes == (192ULL << 30));
+  assert(b10024q->nvencmpix == 1600);
+
+  auto migall = gpu::MigProfile::allBlackwell();
+  assert(migall.size() == 8);
+  auto mig7g = gpu::MigProfile::byName("7g.192gb");
+  assert(mig7g.has_value());
+  assert(mig7g->hbmbytes == (192ULL << 30));
+  assert(gpu::MigProfile::validateDensity(
+      std::span<const gpu::MigProfile::Spec>{migall.data(), 1}));
+
+  auto bw = gpu::NvlinkC2cInterconnect::b100GraceSpec();
+  assert(bw.c2cbidirBps == 900ULL * 1000ULL * 1000ULL * 1000ULL);
+  auto t = gpu::NvlinkC2cInterconnect::estimateTransferTime(1ULL << 30, true);
+  assert(t.count() > 0);
+
+  /* spec database (170 sm / verified data, not the stale 192 block) */
+  gpu::GpuVirtualizationManager gvm;
+  auto gb202 = gvm.lookupspec(gpu::GpuArch::BlackwellGB202);
+  assert(gb202.has_value());
+  assert(gb202->smorcucount == 170);
+  auto det = gvm.detectgpus();
+  assert(det.has_value());
+
+  /* vgpu profiles */
+  gpu::VgpuScheduler sched;
+  assert(sched.listprofiles().size() == 11); /* 7 v6 baseline + 4 GB202 slices from the v4 fix3 merge */
+
+  /* enc models */
+  assert(enc::NvencDualEngine::canFit(3840, 2160, 60, 1) == true);
+  assert(enc::NvencDualEngine::canFit(7680, 4320, 120, 2) == false);
+  assert(enc::NvencDualEngine::kTotalMpixPerSec == 1600);
+  auto nvenc = enc::IEncoderBackend::create(enc::EncoderVendor::NvidiaNvenc);
+  auto caps = nvenc->querycaps();
+  assert(caps->maxthroughputmpixpersec == 1600);
+  assert(enc::EncodingOptimizationManager::recommendpreset(
+             enc::Codec::H265, enc::Tune::Hq, false) ==
+         enc::Preset::P6Slower);
+
+  /* c entry points */
+  assert(std::string_view{vhe_version()}.find("qemu11.1.0") !=
+         std::string_view::npos);
+  assert(vhenvencmpix() == 1600);
+
+  std::cout << "vhe virtualizationcore selftest ok " << vhe_version()
+            << "\n";
+  return 0;
+}
+#endif /* VHE_VIRT_SELFTEST */
+
+
+