diff --git a/CHANGELOG.md b/CHANGELOG.md index ae0cc968..c63acff1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,29 @@ GitHub release body, so a missing section will mean an empty release note. ### Added +- **P2 PR-E2 — the NVAPI bridge: `FrameLedger.NvapiBridge.dll`, L3 `NvapiTelemetrySource`, and the NGX probe + in-process (2026-09-10).** A new native target, `src/native/FrameLedger.NvapiBridge/` — a C ABI + (`fl_nvapi_bridge.h`: 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 rather than read) — 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`, imported by the Agent, the capture host and `Infrastructure.Tests`) + 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 neither a non-deprecated memory-info call — L1's PDH + counter keeps it), and `NvapiNgxStateProbe`, the `INgxDriverProbe` in-process. The capture host composes + L1 + L2 + L3 under the composite (`telemetry_source` can now read `l1+lhm+nvapi`) 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 test run found. ctest `fl_nvapi_bridge` + (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires the `BRANCH:` line; + `NvapiBridgeMirrorTests` checks both mirrors' sizes against the DLL's answers and **fails rather than skips** + when the DLL is not staged; `NvapiTelemetrySourceTests` and `NvapiNgxStateProbeTests` script the bridge. + `tools/versioninfo-check.ps1` requires the new DLL's version block. Measured on the dev box (RTX 5080, + driver 616.64 r616_41) and written into `18_GPU_VENDOR_APIS` §L3: core 35 °C, GPU domain 0 %, 2670 / 15001 + MHz, throttle mask 0, PCIe ×16, memory-temperature and fan bits clear at an idle desktop. + - **P2 PR-D — the session recorder: `.partial`, five-step finalize, exit classification, crash auto-disable, recovery; the first hooked session stored in SQLite (2026-09-10).** `Application.Recording`: `SessionRecorder` owns a session end to end — identity and QPC time base, the `games` and diff --git a/CLAUDE.md b/CLAUDE.md index 1bccf4c2..526c49c2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -39,7 +39,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly | UI | WPF + WPF UI (`WPF-UI` pinned = 4.3.0) + CommunityToolkit.Mvvm — `docs/16_WPFUI_SYNTAX.md` | | App composition | .NET Generic Host + DI in `FrameLedger.App` | | Charts | ScottPlot 5 | -| GPU telemetry | Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 is P2's PR-E2** — `ctest fl_nvapi_probe` is still the only NVAPI consumer, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green | +| GPU telemetry | Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green | | CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — **optional**, elevated only | | Tier-2 fallback | **There is none, and Tier 2 is not a measurement.** Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. ~~ETW-based, no injection~~; ~~Intel PresentMon console binary~~ dropped 2026-08-27 after §S31 retired it. Whether a shipped build ever regains a no-injection measurement is `docs/20_OPEN_QUESTIONS.md` §G | | Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) | @@ -111,7 +111,7 @@ rules/detection-rules.json # engine/platform/capability + anticheat blocklis docs/ legal/ legal/licenses/ ``` -Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. +Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **Two facades since 2026-09-10:** `NativeAntiCheatGuard` (required — absent throws) and `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself), both by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why a third facade claims a name there rather than setting its own. ## Coding conventions diff --git a/FrameLedger.NvapiBridge.targets b/FrameLedger.NvapiBridge.targets new file mode 100644 index 00000000..aab8b13b --- /dev/null +++ b/FrameLedger.NvapiBridge.targets @@ -0,0 +1,40 @@ + + + + + $(MSBuildThisFileDirectory)build\native\x64-release\FrameLedger.NvapiBridge\ + + + + + FrameLedger.NvapiBridge.dll + PreserveNewest + + + + + + + + diff --git a/docs/03_METRICS.md b/docs/03_METRICS.md index f7497f90..6755cdb5 100644 --- a/docs/03_METRICS.md +++ b/docs/03_METRICS.md @@ -491,7 +491,8 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`. > `18_GPU_VENDOR_APIS` L3) returns a feedback word per feature — and **measured 2026-09-06 (driver > 616.64) its `CREATED | EVALUATE` bits are set for a process with NO NVIDIA-app override** on both > no-override titles (`20_OPEN_QUESTIONS` §H5). So the capture host probes it out of process beside -> each module snapshot (`fl-probe-nvapi --ngx-state `, no injection, no consent), and the +> each module snapshot (in-process through `FrameLedger.NvapiBridge.dll` since 2026-09-10, P2 PR-E2; +> `fl-probe-nvapi --ngx-state ` spawned before that — no injection, no consent either way), and the > `upscaler:` line has a rung between the hooks and `N/A`: > > ``` diff --git a/docs/12_BUILD.md b/docs/12_BUILD.md index faf0b61e..9f3b514c 100644 --- a/docs/12_BUILD.md +++ b/docs/12_BUILD.md @@ -23,6 +23,7 @@ Targets: - `FrameLedger.Overlay` → `FrameLedger.Overlay.dll` - `FrameLedger.VkLayer` → `FrameLedger.VkLayer.dll` + `VkLayer_FRAMELEDGER_overlay.json` - `FrameLedger.Injector` → **static lib only.** There is no `FrameLedger.Injector.exe` and none ships (`20_OPEN_QUESTIONS` §S9, decided 2026-08-02). A standalone `LoadLibraryW` injector that users can run is a path into a game process that the guard does not stand in front of — a bypass, and a bad look for a project whose position is "we refuse where we are not welcome". The Agent links the static lib; the guard owns the chokepoint inside it (§S13(b)), so there is no callable entry point that skips the gate. Manual testing uses `hook-harness`, never a real game (§Debugging). +- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other three shipped natives. ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too. - `FrameLedger.Overlay.Tests` → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too - `hook-harness` → the dummy **D3D11 + D3D12** app, WARP + composition swapchain so it runs headless on CI (`17_HOOK_ENGINE` §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. ~~Vulkan and OpenGL modes to follow as those hooks land.~~ **`--vulkan --hold-presenting N` since 2026-09-06 (P1 item 3):** a real swapchain on a hidden window through the real loader, reached by `LoadLibraryW("vulkan-1.dll")` so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. **`--opengl --hold-presenting N` since the same day (P1 item 4):** a real context on a hidden window, `SwapBuffers`'d through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI. - `fl-probe-hookprofile` → build-profile probes for `/guard:cf` and `-D_HAS_EXCEPTIONS=0` (`20_OPEN_QUESTIONS` §H1/§H3) @@ -36,7 +37,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M **MinHook** is fetched by CMake `FetchContent` and built from source, pinned to the **commit** behind tag `v1.3.4` (`c3fcafdc`) rather than to the tag name — a tag can be moved, a commit cannot. FetchContent over a submodule so a fresh clone needs no extra step and CI has nothing to remember. Upstream warnings are not subjected to our `/W4 /WX`: warnings in third-party code are upstream's to fix, and failing our build on them would only tempt someone to patch the fetched copy, which drags it out of "consumed unmodified". The BSD-2-Clause notice ships in `legal/licenses/`, and `tools/license-check.ps1` fails the build if it goes missing while the FetchContent declaration is still present. -**NVAPI SDK** (MIT) **is vendored** at `src/native/third_party/nvapi/` — headers, `amd64/nvapi64.lib`, `License.txt`, consumed through `fl_nvapi` and proven by ctest `fl_nvapi_probe`. `legal/licenses/nvapi-MIT.txt` carries the notice and `license-check.ps1` binds the two bidirectionally. +**NVAPI SDK** (MIT) **is vendored** at `src/native/third_party/nvapi/` — headers, `amd64/nvapi64.lib`, `License.txt`, consumed through `fl_nvapi`, proven by ctest `fl_nvapi_probe`, and **linked by a shipped binary since 2026-09-10** (`FrameLedger.NvapiBridge`, above). `legal/licenses/nvapi-MIT.txt` carries the notice and `license-check.ps1` binds the two bidirectionally. > **This paragraph said "is not vendored yet" until 2026-08-09**, in the present tense, and added that `src/native/third_party/` *"contains `CMakeLists.txt` and `vulkan-headers` only"*. Both were false from #55 (2026-08-05) onward. The sentence was itself a correction — of an earlier claim that NVAPI *was* vendored when it was not — so this file has now been wrong in both directions about the same fact, which is worth more than the fix: **CLAUDE.md's pinned stack and `18_GPU_VENDOR_APIS` §L3 were updated when the vendoring landed and this one was not.** `legal/` is gated bidirectionally and caught its own version; `docs/` is not gated, and this is what that costs. Link it normally; do **not** resolve NVAPI by ordinal (that was a workaround for a licensing constraint that no longer exists, and it breaks across driver versions). Still guard `NvAPI_Initialize` failure as a normal path — plenty of users have no NVIDIA GPU. @@ -54,7 +55,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M > **`RuntimeIdentifier` is NOT set here, and this bullet claimed it was until 2026-08-06.** The props file's own comment explains why: forcing a RID onto class libraries pulls RID-specific assets into their restore for no benefit, so each executable sets it — `FrameLedger.App`, `FrameLedger.Agent` and now `FrameLedger.CaptureHost`, plus its test project, which needs the same RID to reference a RID'd exe. A new project copying this document rather than the props file would have inherited nothing. - Nullable enable, ImplicitUsings enable, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest-all`, deterministic, `ContinuousIntegrationBuild` on CI. - `Directory.Packages.props`: central package management, all versions pinned (including `WPF-UI` = 4.3.0 exactly — `16_WPFUI_SYNTAX` §Version hygiene). -- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22) and `/FrameLedger.Rules.targets` (the blocklist seed). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project. +- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project. > **This bullet was wrong in four ways and is corrected 2026-08-04.** It named a copy of `FrameLedger.Injector.exe`, which §S9 closed and which line 25 above says does not exist, 24 lines earlier in the same document. It attributed the copying to a build target in `FrameLedger.Infrastructure.csproj`, which contains no `` at all. It said the copies happen there, when the guard DLL was deliberately moved out to a `.targets` file so it would stop flowing to every referencing project (§S18 blocker 3). And it credited the solution with an ordering the solution cannot express. - **Struct mirror check — ✅ built 2026-08-05.** `ShmLayoutMirrorTests` runs `tools/fl-layout-dump`, reads its JSON, and asserts size plus every field offset against the C# `[StructLayout]` mirrors in `FrameLedger.Shared` — in **both directions**, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. The `struct-mirror` gate reads the run's `.trx` and fails when that test class did not execute, so deleting the test is red as well as breaking it. Struct drift between the two layers is the most dangerous silent bug in this architecture; the build now genuinely catches it. diff --git a/docs/18_GPU_VENDOR_APIS.md b/docs/18_GPU_VENDOR_APIS.md index 7c5f9c49..72ef74d3 100644 --- a/docs/18_GPU_VENDOR_APIS.md +++ b/docs/18_GPU_VENDOR_APIS.md @@ -34,7 +34,7 @@ Implementations compose rather than compete: - `BaselineTelemetrySource` (L1) — always constructed. - `LhmTelemetrySource` (L2) — constructed when LHM initialises. -- `NvapiTelemetrySource` (L3) — constructed only on NVIDIA hardware. +- `NvapiTelemetrySource` (L3) — ~~constructed only on NVIDIA hardware~~ **always 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 omits `nvapi` and no caller has to know the vendor before composing. - `CompositeTelemetrySource` merges 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. @@ -122,16 +122,41 @@ CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, an 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 in `include/fl_nvapi_bridge.h`) — the **only shipped +> binary that links `nvapi64.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 +> a `present` bitmask per field (`FlNvReadSample`), a refcounted `FlNvInit` / `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 in +> `Infrastructure.Telemetry`: `NativeNvapiBridge` (the second P/Invoke facade after the guard's — same +> absolute-path rule, through the assembly's one `DllImport` resolver, `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 is `null`, never 0; an +> `Init` that 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), and `NvapiNgxStateProbe` +> (`INgxDriverProbe` in-process — the capture host **no longer spawns `fl-probe-nvapi.exe`**, and the +> probe target is no longer staged beside it). Verified by ctest `fl_nvapi_bridge` +> (`src/native/tests/nvapi_bridge_test.cpp`, `BRANCH: AVAILABLE|DEGRADED` required the way +> `fl_nvapi_probe` requires it) and by `NvapiBridgeMirrorTests`, which compares `Marshal.SizeOf` of 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.vram` is +> 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) | -| Utilisation | `NvAPI_GPU_GetDynamicPstatesInfoEx` (GPU / FB / VID / BUS domains) | -| Clocks | `NvAPI_GPU_GetAllClockFrequencies` | -| 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 | -| **Throttle reasons** | `NvAPI_GPU_GetPerfDecreaseInfo` — not available from L1 or L2 | -| Driver version | `NvAPI_SYS_GetDriverAndBranchVersion` | -| **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. 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) | +| 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. @@ -311,19 +336,24 @@ answer; the `untested` cells are exactly as untested as before. | Field | NVIDIA | AMD | Intel | |---|---|---|---| | **Initialises at all** | ✓ **measured 2026-08-05** | `arch` | `arch` | -| **Driver version** | ✓ **measured** — `610.88`, branch `r610_85` | `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 | ? | `arch` | `arch` | -| Per-domain utilisation | ? | `arch` | `arch` | -| Clocks, Power | ? | `arch` | `arch` | -| Throttle reasons | ? | `arch` | `arch` | -| Reflex / PC latency | ? | `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. +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 @@ -378,6 +408,7 @@ alone could never catch. > (`LhmTelemetrySource`, `SensorMap`, the port in `FrameLedger.Application.Telemetry`); > ~~L1 and L3 are still unwritten~~ **L1 and the composite exist as of 2026-09-09** > (`BaselineTelemetrySource`, `DxgiAdapters`, `PdhAdapterMemoryCounter`, -> `CompositeTelemetrySource`, `TelemetryPoller`); L3 is P2's PR-E2. §M5 in particular (do LHM GPU +> `CompositeTelemetrySource`, `TelemetryPoller`); ~~L3 is P2's PR-E2~~ **L3 exists as of 2026-09-10** +> (`NvapiTelemetrySource` over `FrameLedger.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.** diff --git a/docs/20_OPEN_QUESTIONS.md b/docs/20_OPEN_QUESTIONS.md index 39777938..4c70915c 100644 --- a/docs/20_OPEN_QUESTIONS.md +++ b/docs/20_OPEN_QUESTIONS.md @@ -3589,6 +3589,12 @@ probe never showed a deadlock. > beside each module snapshot (out of process, no consent needed) or, if it goes in-process, through > `Infrastructure` only (CLAUDE.md: no P/Invoke elsewhere). > +> **In-process since 2026-09-10 (P2 PR-E2):** the same words through `FrameLedger.NvapiBridge.dll` +> (`Infrastructure.Telemetry.NvapiNgxStateProbe`, the `INgxDriverProbe` the Agent will take from DI); +> the spawn below is retired and `fl-probe-nvapi.exe` is no longer staged beside the host. The readings, +> the merge and the printed block are unchanged, and `NvapiNgxStateProbeTests` maps the bridge's three +> answers to the three outcomes the machine line used to carry. +> > **BUILT 2026-09-06, on the owner's decision ("nối probe để bắt đầu").** The capture host spawns > `fl-probe-nvapi --ngx-state ` beside every module snapshot (the probe prints one machine line, > `NGXSTATE status=… sr=0x… …`, and is staged beside the host by the project file), merges the readings diff --git a/legal/THIRD_PARTY_NOTICES.md b/legal/THIRD_PARTY_NOTICES.md index 83e78a33..5c87878b 100644 --- a/legal/THIRD_PARTY_NOTICES.md +++ b/legal/THIRD_PARTY_NOTICES.md @@ -51,7 +51,7 @@ Telemetry is layered so no proprietary vendor licence is ever required (`docs/18 | Component | How we use it | Licence | Bundled? | |---|---|---|---| -| **NVIDIA NVAPI SDK** (headers, interface definitions, `nvapi64.lib`) | Planned: NVIDIA-only telemetry, throttle reasons, Reflex/PC latency. **No code links it yet** — the `fl_nvapi` target exists and nothing consumes it | **MIT** — @ `cd6918f6` (2026-06-24) | **Vendored 2026-08-05** at `src/native/third_party/nvapi/`: nine headers (`nvapi.h` and its include closure, plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib` — **x64 only**, `x86/nvapi.lib` deliberately not taken. **Verified 2026-08-02 and re-verified on the vendored copy:** `License.txt` opens "nvapi.lib and nvapi64.lib are licensed under the following terms" + `SPDX-License-Identifier: MIT`, so the grant names the import libraries explicitly and the binary is covered rather than only the headers. Every vendored header retains its own SPDX MIT block, which `license-check.ps1` asserts file by file | +| **NVIDIA NVAPI SDK** (headers, interface definitions, `nvapi64.lib`) | NVIDIA-only telemetry — temperatures, GPU-domain utilisation, clocks, fan, throttle reasons, PCIe width, driver version, and the driver's per-process NGX words. ~~**No code links it yet** — the `fl_nvapi` target exists and nothing consumes it~~ **Linked by `FrameLedger.NvapiBridge.dll` since 2026-09-10** (P2 PR-E2): the only shipped binary that links `nvapi64.lib`, loaded by the Agent into its own process and never into a game; the unshipped `fl-probe-nvapi` links it too. Reflex/PC latency is a hook fact, not an NVAPI query (`docs/20_OPEN_QUESTIONS` §M8) | **MIT** — @ `cd6918f6` (2026-06-24) | **Vendored 2026-08-05** at `src/native/third_party/nvapi/`: nine headers (`nvapi.h` and its include closure, plus `nvapi_interface.h`), `License.txt`, and `amd64/nvapi64.lib` — **x64 only**, `x86/nvapi.lib` deliberately not taken. **Verified 2026-08-02 and re-verified on the vendored copy:** `License.txt` opens "nvapi.lib and nvapi64.lib are licensed under the following terms" + `SPDX-License-Identifier: MIT`, so the grant names the import libraries explicitly and the binary is covered rather than only the headers. Every vendored header retains its own SPDX MIT block, which `license-check.ps1` asserts file by file | | `nvapi64.dll` (runtime implementation) | Loaded at runtime from the user's system | Part of the NVIDIA graphics driver | No — never redistributed by us | | **LibreHardwareMonitorLib** | GPU sensors for **all vendors** (AMD, Intel, NVIDIA) + CPU/board sensors when elevated | **MPL-2.0** | Yes, as an unmodified NuGet package | | **DXGI + Windows performance counters (PDH)** | Vendor-neutral baseline: utilisation, VRAM, adapter identity | Windows OS APIs | n/a | diff --git a/src/FrameLedger.Agent/FrameLedger.Agent.csproj b/src/FrameLedger.Agent/FrameLedger.Agent.csproj index dd10b6f8..54b447be 100644 --- a/src/FrameLedger.Agent/FrameLedger.Agent.csproj +++ b/src/FrameLedger.Agent/FrameLedger.Agent.csproj @@ -35,6 +35,7 @@ not import this. --> + diff --git a/src/FrameLedger.CaptureHost/Capture/HostRecorder.cs b/src/FrameLedger.CaptureHost/Capture/HostRecorder.cs index b552bd1f..7b5a0a6d 100644 --- a/src/FrameLedger.CaptureHost/Capture/HostRecorder.cs +++ b/src/FrameLedger.CaptureHost/Capture/HostRecorder.cs @@ -28,9 +28,9 @@ internal static class HostRecorder public static string PartialDirectory => Path.Combine(AppContext.BaseDirectory, "tmp"); - public static SessionRecorder Build(LedgerDatabase db, IGameConsentStore store, int seconds, IProcessLauncher? launcher = null) => + public static SessionRecorder Build(LedgerDatabase db, HostSessionFactory sessions) => new( - new HostSessionFactory(store, seconds, launcher), + sessions, new SqliteGameRepository(db), new SqliteHardwareSnapshotRepository(db), new HardwareSnapshotSource(new DxgiAdapters()), @@ -45,7 +45,7 @@ internal static class HostRecorder public static PartialRecovery Recovery(LedgerDatabase db) => new(new PartialSessionStore(PartialDirectory), Finalizer(db), HostMinimumSessionLength); - /// L1 + L2 under the composite, one poller per session; the poller owns and disposes the layers. + /// L1 + L2 + L3 under the composite, one poller per session; the poller owns and disposes the layers. private static TelemetryPoller Poller() { // Ownership walks up one step at a time and each local is nulled at its hand-off, so a throw @@ -53,6 +53,7 @@ internal static class HostRecorder PdhAdapterMemoryCounter? pdh = null; BaselineTelemetrySource? l1 = null; LhmTelemetrySource? l2 = null; + NvapiTelemetrySource? l3 = null; CompositeTelemetrySource? composite = null; try { @@ -60,11 +61,14 @@ internal static class HostRecorder l1 = new BaselineTelemetrySource(new DxgiAdapters(), pdh, TimeProvider.System); pdh = null; l2 = new LhmTelemetrySource(new LhmComputerAdapter(enableCpuAndMemory: false), new LhmTelemetryOptions(), TimeProvider.System); + l3 = new NvapiTelemetrySource(TimeProvider.System); l1.Start(); l2.Start(); - composite = new CompositeTelemetrySource([l1, l2]); + l3.Start(); + composite = new CompositeTelemetrySource([l1, l2, l3]); l1 = null; l2 = null; + l3 = null; var poller = new TelemetryPoller(composite, new TelemetryPollerOptions(), TimeProvider.System, ownsSource: true); composite = null; return poller; @@ -74,6 +78,7 @@ internal static class HostRecorder pdh?.Dispose(); l1?.Dispose(); l2?.Dispose(); + l3?.Dispose(); composite?.Dispose(); } } diff --git a/src/FrameLedger.CaptureHost/Capture/HostSessionFactory.cs b/src/FrameLedger.CaptureHost/Capture/HostSessionFactory.cs index 1495b0a3..63931ea3 100644 --- a/src/FrameLedger.CaptureHost/Capture/HostSessionFactory.cs +++ b/src/FrameLedger.CaptureHost/Capture/HostSessionFactory.cs @@ -4,12 +4,21 @@ using FrameLedger.Application.Consent; using FrameLedger.Application.Recording; using FrameLedger.Infrastructure.AntiCheat; using FrameLedger.Infrastructure.Capture; +using FrameLedger.Infrastructure.Telemetry; namespace FrameLedger.CaptureHost.Capture; -/// The session and its collaborators, wired the only way this host allows; the recorder supplies the observer. -internal sealed class HostSessionFactory(IGameConsentStore store, int seconds, IProcessLauncher? launcher = null) : ICaptureSessionFactory +/// +/// The session and its collaborators, wired the only way this host allows; the recorder supplies the observer. +/// Owns the one NGX probe (P2 PR-E2: in-process through the bridge, where fl-probe-nvapi.exe used to be +/// spawned) for as long as the verb runs: one NvAPI_Initialize per host, not per session. +/// +internal sealed class HostSessionFactory(IGameConsentStore store, int seconds, IProcessLauncher? launcher = null) : ICaptureSessionFactory, IDisposable { + private readonly NvapiNgxStateProbe _ngx = new(); + + public void Dispose() => _ngx.Dispose(); + public CaptureSession Create(ICaptureObserver observer) { var guard = new NativeAntiCheatGuard(); @@ -30,7 +39,7 @@ internal sealed class HostSessionFactory(IGameConsentStore store, int seconds, I MaxDuration = seconds > 0 ? TimeSpan.FromSeconds(seconds) : TimeSpan.Zero, }, new RuntimeModuleSnapshot(CensusNames.ModuleFileNames), - new NgxDriverProbe(), + _ngx, launcher ?? new ProcessLauncher(), observer); } diff --git a/src/FrameLedger.CaptureHost/Capture/NgxDriverProbe.cs b/src/FrameLedger.CaptureHost/Capture/NgxDriverProbe.cs deleted file mode 100644 index 0b17f10d..00000000 --- a/src/FrameLedger.CaptureHost/Capture/NgxDriverProbe.cs +++ /dev/null @@ -1,69 +0,0 @@ -using System.ComponentModel; -using System.Diagnostics; -using FrameLedger.Application.Capture; - -namespace FrameLedger.CaptureHost.Capture; - -/// -/// Runs fl-probe-nvapi --ngx-state <pid> beside this host and parses its machine line. -/// -/// -/// -/// Out of process, on purpose. The probe links nvapi64.lib (MIT, vendored) and asks the driver about -/// a pid; nothing is injected, nothing in the target is touched, no consent is involved. Spawning the tool this -/// repo already builds keeps the native layer reachable only through what is already there (CLAUDE.md: no -/// P/Invoke outside Infrastructure) — the day the shipped Agent wants this fact, it goes through -/// Infrastructure as a native call, not through a child process. -/// -/// -/// The probe is staged beside the host by the project file the way the Overlay payload is; a missing binary is -/// an outcome the report prints, never an exception the loop sees. -/// -/// -internal sealed class NgxDriverProbe : INgxDriverProbe -{ - private const string _probeFileName = "fl-probe-nvapi.exe"; - - private static readonly TimeSpan _budget = TimeSpan.FromSeconds(5); - - public static string ProbePath => Path.Combine(AppContext.BaseDirectory, _probeFileName); - - /// - NgxDriverState INgxDriverProbe.Run(int pid) => Run(pid); - - public static NgxDriverState Run(int pid) => Run(pid, ProbePath); - - public static NgxDriverState Run(int pid, string probePath) - { - if (!File.Exists(probePath)) - { - return NgxDriverState.Of(NgxProbeOutcome.ProbeMissing, probePath); - } - - try - { - using var probe = new Process(); - probe.StartInfo = new ProcessStartInfo(probePath) - { - UseShellExecute = false, - RedirectStandardOutput = true, - CreateNoWindow = true, - }; - probe.StartInfo.ArgumentList.Add("--ngx-state"); - probe.StartInfo.ArgumentList.Add(pid.ToString(System.Globalization.CultureInfo.InvariantCulture)); - probe.Start(); - string output = probe.StandardOutput.ReadToEnd(); - if (!probe.WaitForExit((int)_budget.TotalMilliseconds)) - { - probe.Kill(); - return NgxDriverState.Of(NgxProbeOutcome.ProbeFailed, "the probe did not exit within " + _budget.TotalSeconds + " s"); - } - - return NgxDriverState.Parse(output); - } - catch (Exception e) when (e is Win32Exception or InvalidOperationException or IOException) - { - return NgxDriverState.Of(NgxProbeOutcome.ProbeFailed, e.Message); - } - } -} diff --git a/src/FrameLedger.CaptureHost/FrameLedger.CaptureHost.csproj b/src/FrameLedger.CaptureHost/FrameLedger.CaptureHost.csproj index 2eb99d49..03bc7a98 100644 --- a/src/FrameLedger.CaptureHost/FrameLedger.CaptureHost.csproj +++ b/src/FrameLedger.CaptureHost/FrameLedger.CaptureHost.csproj @@ -82,26 +82,10 @@ staging it beside a host binary is how a host acquires a target of its own. --> + - - - $(MSBuildThisFileDirectory)..\..\build\native\x64-release\tools\fl-probe-nvapi\ - - - - fl-probe-nvapi.exe - PreserveNewest - - - +