A new native target, src/native/FrameLedger.NvapiBridge/, is the C ABI the managed side reaches NVAPI through: refcounted FlNvInit/FlNvShutdown, FlNvReadSample into a fixed struct with a present bit per field, FlNvNgxState for one pid, FlNvDriverVersion, and size / ABI-version / build-id queries so a drifted mirror is refused (FL_NV_BAD_SIZE) rather than read. It is the only shipped binary that links nvapi64.lib, read-only by construction, loaded by the Agent into its own process by absolute path (FrameLedger.NvapiBridge.targets) and never into a game. Infrastructure.Telemetry: NativeNvapiBridge (the second P/Invoke facade after the guard's, same absolute-path rule), NvapiTelemetrySource (L3: a clear bit is null, never 0; an Init that does not answer 0 disables the layer with zero faults; two throws disable it for the session; VRAM is not read because the vendored nvapi.h declares no non-deprecated memory-info call, so L1's PDH counter keeps it), and NvapiNgxStateProbe, the INgxDriverProbe in-process. The capture host composes L1 + L2 + L3 under the composite and no longer spawns fl-probe-nvapi.exe; the probe is no longer staged beside it. Infrastructure.Native.BesideThisAssembly is the assembly's one DllImport resolver. The runtime allows one per assembly and the guard's static constructor already set it, which the first real-hardware run of the mirror test found (TypeInitializationException: a resolver is already set). The guard claims its name as required (absent throws); the bridge as optional (absent is a missing layer that reports itself). Tests: ctest fl_nvapi_bridge (every export, BRANCH: line required); NvapiBridgeMirrorTests (both mirrors' sizes against the DLL's answers, fails rather than skips when the DLL is not staged); NvapiTelemetrySourceTests and NvapiNgxStateProbeTests over a scripted bridge. versioninfo-check.ps1 requires the new DLL's version block. Measured on the dev box (RTX 5080, 616.64 r616_41), written into 18_GPU_VENDOR_APIS §L3: core 35 °C, GPU domain 0 %, 2670 / 15001 MHz, throttle mask 0, PCIe x16; memory-temperature and fan bits clear at an idle desktop. Docs: 18_GPU_VENDOR_APIS (§Abstraction, §L3 built note, function table, measured matrix), 12_BUILD (§Targets, the .targets list), 03_METRICS and 20_OPEN_QUESTIONS §H5 (probe in-process), CLAUDE.md (pinned stack, the two facades), legal/THIRD_PARTY_NOTICES (NVAPI row), CHANGELOG. Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
38 KiB
18 — GPU telemetry
Telemetry is layered so that no layer's licence can hold the project hostage, and so that a missing vendor library degrades a few fields instead of the whole feature.
| Layer | Source | Licence | Covers |
|---|---|---|---|
| L1 — baseline | DXGI + Windows performance counters (PDH) | none needed (OS APIs) | GPU utilisation, adapter VRAM, per-process VRAM, driver/adapter identity — all vendors |
| L2 — sensors | LibreHardwareMonitorLib | MPL-2.0 (GPL-compatible) | Temperatures, clocks, power, fan — AMD + Intel + NVIDIA, plus CPU/board when elevated |
| L3 — NVIDIA extras | NVAPI, headers vendored | MIT | Throttle reasons, per-domain utilisation, Reflex / PC latency — things no other layer exposes |
L1 always works. L2 fills in what L1 cannot see. L3 adds NVIDIA-only depth. No AMD or Intel vendor SDK is used or bundled — see §Vendor SDKs we deliberately do not use.
Abstraction
public interface IGpuTelemetrySource : IDisposable
{
TelemetryLayer Layer { get; } // L1 / L2 / L3, for the composite descriptor
GpuCapabilities Capabilities { get; } // which fields are real on this machine
bool TryRead(out GpuSample? sample); // 1 Hz, called by the Agent; false = nothing yet, or disabled
}
Written 2026-09-03 as
FrameLedger.Application.Telemetry, with two additions to what this block used to show:Layer, so the composite can record which layer supplied a value without reflecting on the type, andGpuSample.AdapterName, so a report on a multi-adapter machine can say which one a sample describes.Capabilitiesis value-derived and monotonic: a bit is set the first time its field carries a value and is never cleared by a later null tick; a sensor that exists in the tree and never reports sets nothing. That is the one direction a source must never get wrong — a capability bit over a null field is a zero presented as a measurement.
Implementations compose rather than compete:
BaselineTelemetrySource(L1) — always constructed.LhmTelemetrySource(L2) — constructed when LHM initialises.NvapiTelemetrySource(L3) —constructed only on NVIDIA hardwarealways constructed since 2026-09-10 (P2 PR-E2) and disables itself when the bridge DLL or the NVIDIA driver is absent, so the composite's descriptor simply omitsnvapiand no caller has to know the vendor before composing.CompositeTelemetrySourcemerges them with a fixed precedence per field (L3 > L2 > L1) and records which layer supplied each value.
GpuSample: takenAt, layer, adapterName, tempCoreC, tempHotspotC, tempMemoryC, loadPct, vramAdapterMB, coreClockMhz, memClockMhz, powerW, fanRpm, throttleReasons, pcieGen/Width. Every field nullable — Capabilities says what to trust, and the UI shows N/A rather than zero.
sessions.telemetry_source stores the composite descriptor (e.g. l1+lhm+nvapi), not a single name, so a user can see exactly why a field is missing.
Written 2026-09-09 (P2 PR-E1):
BaselineTelemetrySource(L1),CompositeTelemetrySourceand the 1 Hz thread (TelemetryPoller,fl-telemetry). Three things this block did not say and the code now does. (1) The port gainedIsDisabled: a layer that has fallen toCapabilities.Nonebecause it was disabled and one that has simply not read yet were indistinguishable through the port, and the descriptor lists the layers still standing —TelemetryLayerNames.Describe, lowest first — so a layer disabled mid-session drops out of the string the session is stored under. (2) The composite is not a layer: itsLayerisNone, a merged sample'sLayeris the highest layer that contributed anything, andLayerOf(field)answers per field. It also applies the two-fault rule one level up — a layer whoseTryReadthrows (which the port forbids) is excluded on the second throw, the others untouched. (3) Identity is its own record,GpuAdapterIdentity(name, LUID, ids, memory sizes, user-mode driver version), read once per session from DXGI; the Agent hands the handshake'sadapterLuidtoSelectAdapterso samples describe the adapter the game presented on. Every poller sample is stamped with QPC (TelemetrySample.QpcTicks), the ring's clock, andQpcClockTestspinsStopwatch/TimeProvider.GetTimestampto the real counter.
Per-process VRAM comes from the Overlay (
IDXGIAdapter3::QueryVideoMemoryInfoinside the game), not from here. Adapter-wide VRAM is a separate series with a different label — they answer different questions and users will otherwise think one of them is broken.
L1 — baseline (no licence, all vendors)
-
DXGI:
IDXGIFactory6::EnumAdapterByGpuPreference→ adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes.Measured wrong, 2026-09-09:IDXGIAdapter3::QueryVideoMemoryInfofor adapter-wide usage/budget.DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsageis the calling process's usage by the structure's own definition — which is exactly why the Overlay reads it inside the game forvram_proc— and from the Agent it read 0 bytes beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (DxgiAdapters, the first CsWin32 consumer in the tree). -
PDH performance counters — the same source Task Manager uses, fully documented, vendor-neutral:
\GPU Engine(*)\Utilization Percentage(sum per engine type: 3D, Compute, Copy, VideoDecode)\GPU Adapter Memory(*)\Dedicated Usage\GPU Process Memory(*)\Dedicated Usage(cross-check against the Overlay's figure)- Instance names embed the LUID — parse and filter to our adapter, don't sum blindly across GPUs.
Built 2026-09-09 (PR-E1), one counter of the three:
PdhAdapterMemoryCounterbinds\GPU Adapter Memory(luid_0x<High>_0x<Low>_phys_0)\Dedicated Usageby the selected adapter's LUID — addressed directly, never a wildcard summed — and it is L1's one live field (GpuSample.VramAdapterMb). Measured on the dev box: 1301 MB in use on the RTX 5080 at an idle desktop, moving tick to tick. A machine without the counter set fails the open and the field is N/A with the layer standing — not a fault.Utilization Percentageis deliberately not read (20_OPEN_QUESTIONS§M10, decided):LoadPctis L2's vendor-reported load and is labelled as such.GPU Process Memoryis not read either — the Overlay's in-process figure is the one the pipeline stores, and a cross-check is a diagnostic, not a field. -
Driver version:
SetupAPI/ registry adapter properties.IDXGIAdapter::CheckInterfaceSupport(IDXGIDevice)— its documented second output is the user-mode driver version for that interface, four 16-bit fields of one 64-bit value (32.0.16.1664on the dev box, 2026-09-09; the WARP adapter answers with the OS build). Neither SetupAPI nor the registry is walked: both need a device-instance enumeration nothing else here has a reason to carry. Feeds the hardware snapshot and the trend-chart change markers (06_DATA_MODEL). This is the four-part form the vendor's own tooling shows, not the marketing number (561.09), which only L3 knows. -
Optional probe, P0 evaluation only:
D3DKMTQueryAdapterInfowithKMTQAITYPE_ADAPTERPERFDATAreportedly exposes temperature, power and fan for any vendor. The D3DKMT structures are not fully documented and have changed across Windows builds. Treat as an experiment: if it proves stable on both Win 10 22H2 and Win 11 during P0, keep it as an L1 extra behind a capability flag; if it looks fragile, drop it and let L2 handle temperatures. Never let it be load-bearing.🅓 The two-OS requirement is deferred to Win 11 only — owner decision, 2026-08-05. There is one machine and it is Windows 11 (
spike-notes.md§Environment). Win 10 22H2 is a shipped configuration — CLAUDE.md pinsSupportedOSPlatformVersionto10.0.19045.0and the owner confirmed that floor stays — so this is not the same kind of gap as AMD/Intel, where the hardware simply does not exist to be tested on. It is a gap that could be closed with a VM and is being left open on purpose.What makes that acceptable is the last sentence above, and it is now enforced rather than hoped for: the probe must never be load-bearing. Concretely — every field it would fill (core temp, power, fan) is also reachable through L2, and
CompositeTelemetrySource's precedence must treat a D3DKMT value as an extra behind a capability flag, never as the only source. If that ever stops being true, this deferral stops being valid and the Win 10 measurement becomes a release blocker.Recorded because it was previously invisible. This requirement was written in two documents, satisfiable on neither machine anyone has, and — unlike §R5/§R6 — carried no written deferral at all, which is the state P0 exit criterion 2 exists to forbid.
L1 gives no temperatures on its own (unless the D3DKMT probe pans out). That is what L2 is for.
L2 — LibreHardwareMonitorLib (MPL-2.0, all vendors)
LibreHardwareMonitorLib ≥ 0.9.6, consumed as an unmodified NuGet package. It already implements per-vendor GPU sensor access internally — which means the vendor-interop licensing problem is one LHM has solved upstream, under a licence that works for us. That is the entire reason this layer exists.
Computeropened withIsGpuEnabledalways;IsCpuEnabled+IsMemoryEnabledonly when the Agent is elevated and PawnIO is available.- Poll on a dedicated thread:
computer.Accept(updateVisitor)then read mapped sensors. Never faster than 500 ms; default 1000 ms. - Sensor mapping by
SensorType+ name heuristics per vendor (GPU Core,GPU Hot Spot,GPU Memory,GPU Package Power, …), kept inSensorMap.cswith unit tests against captured sensor-tree fixtures. - P0 verification items: (a) which fields LHM actually returns per vendor on real hardware — fill the capability matrix below — NVIDIA filled 2026-09-03, AMD/Intel deferred (§R5/§R6); (b)
whether GPU-only usage works without elevation and without PawnIO (expected yes, since GPU sensors go through user-mode vendor paths, but confirm — it determines whether the default unelevated Agent has temperatures at all)— confirmed 2026-09-03, §M5 row R1: eight fields unelevated, the same eight elevated, PawnIO never opened; (c)confirm LHM's sources are not marked with MPL-2.0 Exhibit B— done, 2026-08-02: clear. No source file applies the notice; the only repository hit is theLICENSEtemplate itself, and every file we depend on carries the permissive Exhibit A. Method and evidence indocs/spike-notes.md§0. Re-check on every version bump, and check source headers, never the LICENSE file — MPL-2.0's own text contains Exhibit B as a template, so grepping the licence finds it in every MPL project ever published.
CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, and optional.
L3 — NVAPI (MIT, NVIDIA only)
Integration: vendored headers + import library, linked normally. ✅ Vendored 2026-08-05 at src/native/third_party/nvapi/ — nine headers (nvapi.h's include closure plus nvapi_interface.h), License.txt, and amd64/nvapi64.lib; x64 only, x86/nvapi.lib deliberately not taken. Consumed through the fl_nvapi INTERFACE target. NVIDIA publishes the NVAPI SDK — headers, interface definitions, and nvapi64.lib — under the MIT licence (verified 2026-08-02 and re-verified on the vendored copy: amd64/nvapi64.lib is a tracked file in the MIT repo and License.txt names the import libraries as the subject of the grant, so the binary is covered and not only the headers), so the SDK material can live in our GPL-3.0 repository with only the usual MIT attribution obligation. The runtime implementation lives in nvapi64.dll, which ships with the installed NVIDIA driver.
This section claimed the vendoring in the present tense while it had not happened, and CLAUDE.md's pinned stack said the same —
src/native/third_party/heldvulkan-headersand nothing else.legal/THIRD_PARTY_NOTICES.mdhad already caught the identical claim about itself and gained a bidirectional licence gate for it; nothing propagated here. That gate is what turned the vendoring into a two-step with a free canary: adding the material while the notice still read "Not yet vendored" failed the build, in the present-but-marked-absent direction that was structurally invisible before the check was made bidirectional.
This supersedes the earlier design's dynamic-loading-by-ordinal approach. That was a workaround for a licensing constraint that no longer exists; ordinal resolution is fragile across driver versions and should not be reintroduced. Vendored headers are simpler, type-safe, and maintainable.
Still resolve entry points defensively at runtime: nvapi64.dll may be absent (no NVIDIA GPU) or older than our headers. NvAPI_Initialize failing is a normal condition that must disable L3 cleanly, not throw.
Built 2026-09-10 (P2 PR-E2). NVAPI is a C API behind a static import library, so the managed side reaches it through a native DLL of our own:
FrameLedger.NvapiBridge.dll(src/native/FrameLedger.NvapiBridge/, C ABI ininclude/fl_nvapi_bridge.h) — the only shipped binary that linksnvapi64.lib, read-only by construction (every export is a query), loaded by the Agent into its own process by absolute path and never into a game. Its name carries none of the words the guard's §S18 heuristic scans a launcher's ancestors for. The ABI is a fixed struct with apresentbitmask per field (FlNvReadSample), a refcountedFlNvInit/FlNvShutdown, the driver version, the per-pid NGX words (FlNvNgxState), and size / ABI-version / build-id queries so a mirror that drifts is refused (FL_NV_BAD_SIZE) rather than read. On the managed side, all inInfrastructure.Telemetry:NativeNvapiBridge(the second P/Invoke facade after the guard's — same absolute-path rule, through the assembly's oneDllImportresolver,Infrastructure.Native.BesideThisAssembly, because the runtime allows exactly one per assembly and two static constructors setting one is an exception in whichever runs second),NvapiTelemetrySource(a clear bit isnull, never 0; anInitthat does not answer 0 disables the layer with zero faults, because a machine without the driver is a normal condition; two throws disable it for the session), andNvapiNgxStateProbe(INgxDriverProbein-process — the capture host no longer spawnsfl-probe-nvapi.exe, and the probe target is no longer staged beside it). Verified by ctestfl_nvapi_bridge(src/native/tests/nvapi_bridge_test.cpp,BRANCH: AVAILABLE|DEGRADEDrequired the wayfl_nvapi_proberequires it) and byNvapiBridgeMirrorTests, which comparesMarshal.SizeOfof both mirrors against the DLL's own answers and fails rather than skips when the DLL is not staged.Not in this build, stated so nobody infers it from the table below: VRAM (
FlNvSample.vramis reserved and its bit is never set — see the Memory row), power, hotspot temperature, per-domain utilisation beyond the GPU domain, and anything Reflex (§M8: a hook fact, not a poller field).
| Purpose | Function |
|---|---|
| Init / enumerate | NvAPI_Initialize, NvAPI_EnumPhysicalGPUs, NvAPI_GPU_GetFullName |
| Temperatures | NvAPI_GPU_GetThermalSettings (+ extended thermal query for hotspot/memory where available). Bridge (2026-09-10): the public enumeration only — core is the GPU target; memory is the MEMORY target when the driver lists one, and on the RTX 5080 it does not (bit clear → null); hotspot is not read |
| Utilisation | NvAPI_GPU_GetDynamicPstatesInfoEx (GPU / FB / VID / BUS domains). Bridge (2026-09-10): the GPU domain only, as loadPct |
| Clocks | NvAPI_GPU_GetAllClockFrequencies — bridge (2026-09-10): current graphics and memory clocks |
| Memory | NvAPI_GPU_GetMemoryInfoEx — not NvAPI_GPU_GetMemoryInfo, which this table named until 2026-08-05. The vendored headers mark it __nvapi_deprecated_function ("deprecated in release 520"), so under /W4 /WX a call to it fails the native build. Neither is called (2026-09-10): the vendored nvapi.h (cd6918f6) does not declare GetMemoryInfoEx at all — the deprecation message names a function the same header set does not ship — so the bridge's vram field is reserved, its bit is never set, and VRAM stays L1's PDH adapter counter. Taking a newer header set is the way to change that, not a call to the deprecated one |
| Throttle reasons | NvAPI_GPU_GetPerfDecreaseInfo — not available from L1 or L2. Bridge (2026-09-10): the raw reason mask, and 0 is a measurement (no reason), not a clear bit |
| Driver version | NvAPI_SYS_GetDriverAndBranchVersion — bridge (2026-09-10): FlNvDriverVersion, surfaced as 616.64 (r616_41) |
| NGX per-process state | NvAPI_NGX_GetNGXOverrideState (R570+) — the driver's feedback word per DLSS feature for a PID, read OUT OF PROCESS by fl-probe-nvapi --ngx-state and, since 2026-09-06, by the capture host beside each module snapshot — in-process through the bridge since 2026-09-10 (NvapiNgxStateProbe; the spawn is retired and the words, the merge and the printed block are unchanged). Measured: the SR word's CREATED | EVALUATE is set without an NVIDIA-app override; the FG word follows DLSS-G once created (CREATED | EVALUATE at ×4, corrected the same day — the first reading was blind because it was early), the multiplier bits stay clear; scalingRatio is 0 even under an override. Identity only, SR and FG (03_METRICS §Upscaling) |
| Reflex / PC latency | NvAPI_D3D_GetLatency → per-frame sim/render/present/driver/GPU timestamps; hooking NvAPI_D3D_SetSleepMode / SetLatencyMarker in the Overlay tells us the game enabled Reflex (17_HOOK_ENGINE) |
Reflex latency is the single strongest reason L3 exists — it is genuinely unavailable anywhere else.
⚠ Any function not present in the public headers is an optional extra: feature-flagged, guarded, never load-bearing. If a call misbehaves twice, disable L3's affected field for the session rather than retrying in a loop.
Vendor SDKs we deliberately do not use
Recorded so nobody re-adds them later without redoing the analysis.
Intel Graphics Control Library (IGCL) — rejected, licence incompatible. Distributed under the Intel Software License Agreement, not an open-source licence. Three clauses conflict with GPL-3.0 if the headers were vendored into this repository:
- Use and redistribution are permitted "solely for use on Intel platforms" — a field-of-use restriction. GPL-3.0 §10 forbids imposing further restrictions on downstream recipients, and §7's list of permitted additional terms does not cover this.
- A broad indemnification obligation covering any claims arising from use. GPL-3.0 §7(f) permits indemnity terms only in a narrow form tied to contractual assumptions of liability by the conveyor.
- An additional termination trigger on breach, plus a no-reverse-engineering clause on binary components — both extend beyond GPL's own termination and study rights.
Writing our own IGCL declarations to avoid vendoring the headers is not an approved workaround: struct layouts must match byte-for-byte, so an "independent" implementation is indistinguishable from a copy, and the legal position is unsettled. Intel GPU telemetry comes from L1 + L2 instead.
AMD ADLX / ADL — not used. Not evaluated in depth because L2 already covers AMD sensors under MPL-2.0, so there is no need to take on another vendor licence. If someone later proposes adding it, it must pass the checklist below first, and the proposal must explain what it delivers that L2 does not.
NVIDIA NGX / Streamline, AMD FidelityFX, Intel XeSS runtimes — not loaded and not redistributed by us at all. We observe the calls the game makes to the copies it ships (17_HOOK_ENGINE). No vendor code is distributed by FrameLedger.
AMD FidelityFX SDK headers — checklist run 2026-09-04, CLEAR; vendored the same day at
tag v2.3.0, five headers, types only (src/native/third_party/fidelityfx/README.md).
Read off the upstream repository through the GitHub API, not from memory:
- Tag
v1.1.4(the last 1.x): the rootLICENSE.txtis the MIT grant verbatim, and every header of interest carries the same grant inline — theffx-api/include/ffx_api/set and the FSR 3.0 host API undersdk/include/FidelityFX/host/. None of step 2's needles appear. This paragraph said "vendor from this tag", and its own reversal condition fired the same day — see the third bullet.The host API is still only here:Wrong tag, corrected 2026-09-05 when the route was built. Cyberpunk'smaindroppedffx_fsr3.h, so the FSR 3.0 route (Cyberpunk'sffx_fsr3_x64.dll, named exports) vendors fromv1.1.4when it is built, and its closure is ten files, not the nine first listed —ffx_interface.hincludesffx_message.h— with<mutex>/<shared_mutex>reached throughffx_types.h.ffx_fsr3_x64.dllexports twelveffxFsr3*names (vendor-exports.json), which is exactly tagfsr3-v3.0.4's declaration list;v1.1.4declares fifteen and appendsupscaleSize,flagsandframeIDtoFfxFsr3DispatchUpscaleDescriptionafterrenderSize— a detour typed against it would read the wrong bytes off the module the title ships. Atfsr3-v3.0.4the rootLICENSE.txtis MIT verbatim, every header carries the grant inline, andffx_types.hincludes<stdint.h>and nothing else — the<mutex>block exists only from 1.1.x behind#ifndef FFX_MUTEX. The closure is ten files with noffx_message.h(nine host headers plusgpu/fsr3upscaler/ffx_fsr3upscaler_resources.h). Vendored atsrc/native/third_party/fidelityfx-fsr3/in its own directory because the licence shape differs fromv2.3.0's exception list;license-check.ps1§2e asserts it per file. main== tagv2.3.0(60f4ea81, "AMD FSR SDK 2.3.0", 2026-06-24) is a different shape: itsdocs/license.mdis a binary-only, no-reverse-engineering default licence that "applies to all files except as noted below", followed by an MIT exception list of 845 paths. Read off the tree API: the repository at that commit holds exactly 845 blobs, and every one of them is on the list —Kits/FidelityFX/signedbin/*.dllincluded — so the default licence governs no file that is actually in the tree, and the headers carry the grant inline as well. MIT by exception, for the whole tree.license-check.ps1§2d asserts it per vendored file rather than trusting this sentence: every path underfidelityfx/Kits/must be on the list inside the vendoredlicense.md, every.hmust carry the grant, and no binary or source may be present.- Why
v2.3.0and notv1.1.4, decided by the owner 2026-09-04. The reversal condition — "unless a title ships an API version that needs 2.x" — is met on this machine: Hell Is Us shipsamd_fidelityfx_upscaler_dx12.dll4.0.3 andamd_fidelityfx_framegeneration_dx12.dll4.0.0, Expedition 33 and Dying Light: The Beast ship upscaler 4.0.2 with frame generation 3.1.5 (all SDK 2.x effect DLLs), and the SDK's own sample dispatchesffxDispatchDescFrameGenerationPrepareV2(0x0002000c), whichv1.1.4does not declare. Every value and layout the Overlay reads is identical in both tags (UPSCALE 0x00010001,FRAMEGENERATION 0x00020003,PREPARE 0x00020004,ffxApiHeader,FfxApiResource,ffxDispatchDescUpscale, thePrepareprefix throughrenderSize), so the 1.1.x monolith decodes with the 2.3.0 constants. Vendored:Kits/FidelityFX/api/include/{ffx_api.h, ffx_api_types.h},upscalers/include/ffx_upscale.h,framegeneration/include/{ffx_framegeneration.h, ffx_framegeneration_api_types.h}, in upstream's layout because they include each other by relative path. Excluded, each with a reason in the README:signedbin/,ffx_api_loader.h(aGetProcAddresshelper), the twodx12/backend headers (no consumer yet), the.hpphelpers and every source file. - Types-only, never linked, with a consumer in the same commit — the Streamline rules
(
src/native/third_party/streamline/README.md).hookinventory-checkPass C already forbadeamd_fidelityfx*/ffx_*imports — the sentence here that said the list "must gain" them was written before checking, and the self-test at line 242 had covered them since 2026-08-14 — and now reads the built Overlay's export table too, becauseffx_api.hdeclares its entry points__declspec(dllexport)with no import switch and a definition inside the Overlay would announce a vendor API it does not implement.
Intel XeSS SDK — checklist run 2026-09-04, REJECTED; the same class as NGX. The repository
https://github.com/intel/xess ships LICENSE.txt = Intel Simplified Software License
(October 2022): the grant is for the software "provided in binary form only", it forbids
"reverse engineering, decompilation, or disassembly … nor any modification", and it carries
its own termination clause — two of step 2's needles. The headers under inc/ (xess/xess.h,
xess/xess_d3d12.h, xess_fg/xefg_swapchain.h, xess_fg/xefg_swapchain_d3d12.h, xell/*.h)
carry no MIT text; each opens "Intel copyrighted materials … you may not use, modify, copy,
publish, distribute … without Intel's prior written permission." Step 3 therefore binds:
do not vendor, and do not re-declare the API. What remains in policy for Intel is the
census: module presence by name, nothing more. A signature-free call counter — a
register-preserving thunk on a named export that increments and jumps — was considered and
refused the same day (delegated by the owner, decided 2026-09-04). It declares no type and
reads no argument, but installing it inline-patches Intel's code inside the game process, and
the same licence forbids "any modification"; the census is the answer NGX got and Intel gets
the same one. Reversal condition: Intel publishing the headers under a licence that clears the
checklist, at which point this paragraph is re-run, not argued around. Re-run 2026-09-06 against
https://raw.githubusercontent.com/intel/xess/main/LICENSE.txt and inc/xess/xess.h: unchanged —
the same licence, the same three needles, the same header banner. Not fired. Intel's README does
state that XeSS-FG runs on "non-Intel GPUs with SM 6.4 support", so an XeFG session is measurable
on the NVIDIA dev box even though nothing in it may be hooked or declared.
Checklist before adding any vendor SDK
- Is it MIT / BSD / Apache-2.0 / MPL-2.0? → proceed, add the licence copy, done.
- Otherwise, search the licence text for: "solely for", "indemnify", "terminate", "reverse engineer", "Intel platforms"/"AMD products"-style field-of-use wording.
- Any hit ⇒ do not vendor it into this repository, and do not work around it by re-declaring the API. Find an alternative layer, or document the gap honestly.
- Record the decision in this section either way — including rejections, with reasons.
Runtime policy
- Poll at 1 Hz on a dedicated Agent thread. Never from the game process, never from the Overlay.
- Any layer that throws or hangs twice is disabled for the session and its fields report
N/A, rather than being retried in a loop. - Read-only, always. These libraries can also set clocks, fan curves and power limits. FrameLedger never calls a setter — not in v1, not in the backlog. A measurement tool that can modify hardware state is a different product with a different risk profile.
Capability matrix (fill during P0 on real hardware)
Restructured to vendor × layer on 2026-08-05, before anything was filled in, because the note below said in this document's own words that the old single-axis table "cannot currently express" the AMD/Intel deferral and that adding the axis is "a prerequisite of filling it, not a tidy-up afterwards". Filling the NVIDIA half into the old table would have overwritten cells that were simultaneously making an unverified claim about hardware nobody here has.
Legend, and the distinction the restructure exists to preserve:
| Mark | Meaning |
|---|---|
| ✓ / ✗ | Measured on that vendor, available / not available |
arch |
Not available by architecture — no measurement needed or possible |
? |
Not yet measured, and measurable here. A to-do |
untested |
Cannot be measured on this machine. Not a to-do — a deferral (§R5/§R6) |
? and untested are what the old table could not tell apart. The UI consults this before
advertising a capability, and "we have not got to it" and "we cannot, here" must not render
as the same thing.
L1 — DXGI + PDH (vendor-neutral by construction)
| Field | NVIDIA | AMD | Intel |
|---|---|---|---|
| GPU utilisation | deferred by decision (§M10, 2026-09-09) — L2's vendor-reported load is what LoadPct carries, labelled as such; the engine counters are not read |
untested | untested |
| Adapter VRAM | ✓ measured 2026-09-09 — PDH GPU Adapter Memory … Dedicated Usage, 1301 MB at an idle desktop, RTX 5080 (QueryVideoMemoryInfo measured not adapter-wide: 0 bytes from the Agent) |
untested | untested |
| Per-process VRAM | arch for L1 — the Overlay's in-process QueryVideoMemoryInfo is the figure stored; GPU Process Memory is not read |
arch |
arch |
| Driver version | ✓ measured 2026-09-09 — CheckInterfaceSupport(IDXGIDevice) → 32.0.16.1664 |
untested | untested |
| Core temp | ? (D3DKMT probe, Win 11 only — see below) | untested | untested |
| Power | ? (D3DKMT probe) | untested | untested |
| Fan | ? (D3DKMT probe) | untested | untested |
| Hotspot / memory temp, Clocks, Throttle, Reflex, CPU temp | arch |
arch |
arch |
L1 is vendor-neutral by construction — DXGI and PDH expose the same counters whatever
the adapter is — so the AMD/Intel untested cells are expected to match NVIDIA and are
still not claims. One cell genuinely cannot be filled here even on NVIDIA: multi-adapter
LUID instance filtering, because this machine has exactly one adapter and a KF CPU with no
iGPU. It must be written and can only be reasoned about.
L2 — LibreHardwareMonitor
| Field | NVIDIA | AMD | Intel |
|---|---|---|---|
| GPU utilisation, Adapter VRAM | ✓ (GPU Core load; GPU Memory Used, MB) |
untested | untested |
| Driver version | arch — LHM publishes no such sensor; L1 owns it |
arch |
arch |
| Core temp, memory temp | ✓ (GPU Core; GPU Memory Junction) |
untested | untested |
| Hotspot temp | ✗ on this box — no GPU Hot Spot sensor at all (RTX 5080, 616.56, LHM 0.9.6); driver, generation or library unmeasured |
untested | untested |
| Clocks, Power, Fan | ✓ (GPU Core / GPU Memory MHz; GPU Package W; GPU Fan 1..3 rpm) |
untested | untested |
| Per-process VRAM | arch |
arch |
arch |
| Throttle reasons, Reflex / PC latency | arch |
arch |
arch |
| CPU temp | ✓ elevated + PawnIO | ✓ elevated + PawnIO | ✓ elevated + PawnIO |
| GPU sensors unelevated, no PawnIO (§M5) | ✓ — row R1, 2026-09-03. Unelevated and elevated return the identical eight fields; PawnIO never opened (GPU group only) | untested | untested |
§M5 is the row that decides whether the default, unelevated Agent has temperatures at
all. Measured 2026-09-03 — yes, on NVIDIA. The instrument is
FrameLedger.CaptureHost probe-lhm, the raw tree and the elevated control are in
spike-notes §10, and the decision table it was read against was pre-committed in
20_OPEN_QUESTIONS §M5 before the run. The NVIDIA column above is that one machine's
answer; the untested cells are exactly as untested as before.
L3 — NVAPI (NVIDIA only, arch elsewhere)
| Field | NVIDIA | AMD | Intel |
|---|---|---|---|
| Initialises at all | ✓ measured 2026-08-05 | arch |
arch |
| Driver version | ✓ measured — 610.88, branch r610_85; through the bridge 2026-09-10: 616.64, r616_41 |
arch |
arch |
| GPU enumeration + name | ✓ measured — 1 GPU, "NVIDIA GeForce RTX 5080" | arch |
arch |
| Degrades cleanly when absent | ✓ measured — see below | arch |
arch |
| Core / hotspot / memory temp | core ✓ measured 2026-09-10 — 35 °C at an idle desktop; memory: bit clear on this GPU (no MEMORY thermal target enumerated → null, not 0); hotspot not read |
arch |
arch |
| Per-domain utilisation | GPU domain ✓ measured 2026-09-10 — 0 % at an idle desktop, present bit set (a measured zero); FB / VID / BUS not read | arch |
arch |
| Clocks, Power | clocks ✓ measured 2026-09-10 — 2670 MHz graphics, 15001 MHz memory; power not read | arch |
arch |
| Throttle reasons | ✓ measured 2026-09-10 — mask 0 at an idle desktop, present bit set | arch |
arch |
| Fan | bit clear at an idle desktop 2026-09-10 — the tach reading is refused while the fans are stopped, and the bridge reports that as absent rather than 0 RPM; a reading under load is the owner's to take | arch |
arch |
| PCIe width | ✓ measured 2026-09-10 — ×16; generation not read | arch |
arch |
| Reflex / PC latency | not a poller field (§M8) | arch |
arch |
The four measured rows come from ctest fl_nvapi_probe (src/native/tools/fl-probe-nvapi),
which exists because vendoring added 2.4 MB of headers and an import library that nothing
else compiles against yet — an unconsumed vendored dependency is one whose header closure
could be short by a file with every gate still green. The 2026-09-10 rows come from one
FlNvReadSample through FrameLedger.NvapiBridge.dll on the dev box (RTX 5080, driver 616.64),
read from the staged DLL by hand after NvapiBridgeMirrorTests had passed against it; the
bridge is the second consumer of the vendored material and the first that ships.
"Degrades cleanly when absent" — what is observed, and what is inferred. nvapi64.lib
is a static library of stubs that reach nvapi64.dll through nvapi_QueryInterface at
first call, so linking it does not make the DLL a load-time dependency: a machine with
no NVIDIA driver loads the binary and NvAPI_Initialize returns an error instead. The probe
prints BRANCH: AVAILABLE or BRANCH: DEGRADED and exits 0 either way, and ctest
requires one of those two strings — so a probe gutted to return 0 fails, which exit code
alone could never catch.
Stated precisely because the obvious sentence would be an overclaim. Observed on CI: the probe builds, links and passes on a hosted runner in ~0.01 s, against ~1.4 s on the dev box. Inferred, not observed: that the runner took the DEGRADED branch — hosted Windows runners have no NVIDIA driver and the timing matches an immediate
NvAPI_Initializefailure, but ctest prints a passing test's output nowhere, so the CI log shows that a branch was reached and not which one. The load-time-dependency claim is what the run does prove: a load-time dependency on an absentnvapi64.dllwould have failed to start at all.
⚠
NvAPI_GPU_GetMemoryInfowas named in §L3's function table below and must not be used. The vendored headers carry__nvapi_deprecated_function("...deprecated in release 520. Instead, use NvAPI_GPU_GetMemoryInfoEx.")on it, so under/W4 /WXa call fails the native build. Corrected in the table. Recorded because it is the class17_HOOK_ENGINEcalls the highest false-confidence risk in the spike — a name that resolves to nothing degrades to "unknown", which reads as "working, no data" — found by vendoring the material and compiling against it rather than by reading a vendor's web documentation.
🅓 The AMD and Intel results are deferred as
untested— owner decision, 2026-08-05 (20_OPEN_QUESTIONS§R5/§R6). Not deferred for cost: the dev machine has one adapter, an RTX 5080, and aKFCPU with no iGPU (spike-notes.md§Environment), so there is no measurement to take. AFMF is unreachable for the same reason — it is an AMD driver-side feature.The rule that travels with the deferral: an unmeasured cell is
untested, never?and never a checkmark inferred from a vendor's documentation.?reads as "we have not got to it yet";untestedreads as "we cannot, here" — and this table is what the UI consults before advertising a capability to a user.
This table cannot currently express that. Its columns are the three layers, with no vendor axis, so "measured on NVIDIA, untested on AMD/Intel" has nowhere to go — and every?below is therefore ambiguous between the two meanings. Adding the vendor axis is a prerequisite of filling it, not a tidy-up afterwards, because a single-axis table forces whoever fills the NVIDIA half to overwrite cells that are also making a claim about hardware they never had. P0 item 8 owns this.Done 2026-08-05, before anything was filled in, which was the point of calling it a prerequisite. Three tables, one per layer, with a vendor axis and a four-symbol legend that separates
?(a to-do, measurable here) fromuntested(a deferral, not measurable here) fromarch(not available by architecture, so neither).The NVIDIA half is not deferred and
none of it exists in code yet — no PDH, no DXGI telemetry, no LibreHardwareMonitor, no NVAPI— L2 exists as of 2026-09-03 (LhmTelemetrySource,SensorMap, the port inFrameLedger.Application.Telemetry);L1 and L3 are still unwrittenL1 and the composite exist as of 2026-09-09 (BaselineTelemetrySource,DxgiAdapters,PdhAdapterMemoryCounter,CompositeTelemetrySource,TelemetryPoller);L3 is P2's PR-E2L3 exists as of 2026-09-10 (NvapiTelemetrySourceoverFrameLedger.NvapiBridge.dll, §L3). §M5 in particular (do LHM GPU sensors work unelevated, without PawnIO?) decided whether the default unelevated Agent has temperatures at all — it does, on NVIDIA; row R1 above.