docs: "Advanced metrics" planned - the owner's decisions D101-D108, the inventory of what NVAPI, LibreHardwareMonitor, Streamline and FidelityFX make available, and the catalog every later pull request reads (Advanced PR-1) (#387)

The owner asked for a setting, "Thông số nâng cao", with a navigation item
of its own that shows as much as the NVAPI and Streamline headers and PawnIO
make available, each value under what it belongs to: one game session, or
the PC. Planned 2026-11-11 with the owner's decisions asked while planning;
four trains, A (0.1.0-beta.39, the Agent's reads only) to D. This is the
first pull request of train A and changes no behaviour.

- FrameLedger.Application.Advanced: AdvancedMetricCatalog, 137 entries -
  86 the Agent will read (60 NVAPI, 10 LibreHardwareMonitor unelevated, 16
  through PawnIO as administrator) and 51 that are not read, each with its
  reason: a call already hooked, a hook not built, a route a spike decides,
  an identifier (D104), the player's own state (rule 4), a licence, a
  function the public headers do not declare. One list for the reader, the
  recorder, the page and the documents.
- docs/18_GPU_VENDOR_APIS.md section Advanced metrics: the decisions, what
  belongs to what, the four trains, what is left out by name, and the
  inventory as a table. AdvancedMetricCatalogTests fails when the table and
  the catalog differ in either direction (proven red on one changed row).
- docs/18: the Memory row said the vendored NVAPI headers do not declare
  NvAPI_GPU_GetMemoryInfoEx. They do (nvapi_lite_common.h:600, included by
  nvapi.h); the search had looked in nvapi.h alone. Corrected.
- docs/HANDOFF.md: the plan's order and the owner's four answers, D101-D108
  in the decisions index, and 0.1.0-beta.38's release facts, which its own
  release could not carry.
- docs/20_OPEN_QUESTIONS.md: M12-M15, each with its outcome written before
  the measurement - the NVAPI rows on real hardware, LibreHardwareMonitor's
  other groups elevated, a route to Reflex latency, the refused
  slGetFeatureFunction route re-examined.
- docs/02_SPEC.md: FR-5.6, and NFR-2's limits stated to hold with the
  option on (unmeasured). CLAUDE.md: the Application layer's new folder.

Gate on the dev box: all passed in 300 s.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Fable 5.2 authored and GitHub committed 2026-11-11 07:42:39 +00:00
1 parent b7d655078c
commit 3e810d1aa6
14 files changed
+1105 -7

No files matched your search

+22
View File
@@ -35,6 +35,28 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
### Added
- **"Advanced metrics" is planned, and its inventory is written — nothing reads it yet.** The owner asked for a
setting, *Thông số nâng cao*, with a navigation item of its own that shows as much as the NVAPI and Streamline
headers and PawnIO make available, each value under what it belongs to: one game session, or the PC. This pull
request is the first of that train and changes nothing you can see or record. It adds the list everything else in
the train reads — `AdvancedMetricCatalog`, 137 entries: what the Agent will read from NVAPI and
LibreHardwareMonitor (the card's firmware, architecture and cores; its memory with evictions and promotions; its
utilisation by domain; what a display can do with HDR and variable refresh; the driver's profile; and, as
administrator with PawnIO, the processor per core, the motherboard, the memory modules and the drives'
temperatures), what can only be read inside a game and waits for a later release, **and what is never read with the
reason** — a serial number, a display's EDID, the list of programs that are encoding, the camera's position, what
a vendor's licence closes. `docs/18_GPU_VENDOR_APIS.md` §Advanced metrics holds the design, the owner's decisions
D101–D108 and the same list as a table; a test fails when the table and the catalog differ in either direction.
### Fixed
- **A sentence in the documents that kept a function from being called.** `docs/18_GPU_VENDOR_APIS.md` said the
vendored NVAPI headers do not declare `NvAPI_GPU_GetMemoryInfoEx`. They do — in `nvapi_lite_common.h`, which
`nvapi.h` includes; the search that found nothing had looked in `nvapi.h` alone. The row is corrected, and the
bridge will call it for the advanced memory rows. Nothing about the memory figures FrameLedger shows today changes.
## Releases
Newest first. Each file holds that release's section exactly as it stood here.
+4 -1
View File
@@ -103,7 +103,10 @@ src/
# composes it from, SessionEndReason, the census/NGX/marker facts;
# and Recording/ since 2026-09-10 (PR-D): SessionRecorder,
# SessionAggregator + FgLadder, SessionFinalizer, the .partial
# writer and PartialRecovery, ExitStatusMapper, the crash policy
# writer and PartialRecovery, ExitStatusMapper, the crash policy;
# and Advanced/ since 2026-11-11 (D101): AdvancedMetricCatalog, the one
# list "Advanced metrics" reads - what is read, and what is not with the
# reason (18_GPU_VENDOR_APIS §Advanced metrics). Nothing reads it yet.
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
+2 -1
View File
@@ -53,6 +53,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-5.3 Charts handle ≥ 500k points via min/max decimation; zoom/pan; PNG export.
- FR-5.4 Native/Displayed toggle wherever FG data exists.
- FR-5.5 Stutter markers annotated with cause when known (`PSO compile`, `VRAM budget exceeded`).
- FR-5.6 *(owner decision D101, 2026-11-11)* **Advanced metrics**: an option, off by default, and a page of its own that shows what the vendor interfaces make available — NVAPI, LibreHardwareMonitor through PawnIO, and in later releases Streamline and FidelityFX inside the game — each value under what it belongs to, the PC or one session, and each value that is not read listed with the reason. Off means nothing more is read or stored. `18_GPU_VENDOR_APIS` §Advanced metrics is the design and the inventory. *(Not built: the catalog exists, nothing reads it yet.)*
### FR-6 History & comparison
- FR-6.1 Sessions table per game: date, duration, tier badge, Native, Displayed, FG×, lows, resolution + upscaler, RT/PT/RR chips, crash badge, tags.
@@ -104,7 +105,7 @@ Draw live FPS/frametime/upscaler info inside the game. Only for games already ho
## Non-functional requirements
- **NFR-1 Game-side overhead:** ≤ 1 µs per present, ≤ 8 MB resident, measured game FPS impact ≤ 0.5% vs uninstrumented.
- **NFR-2 Agent overhead:** ≤ 1% of one core during capture, ≤ 150 MB working set, ~0% idle.
- **NFR-2 Agent overhead:** ≤ 1% of one core during capture, ≤ 150 MB working set, ~0% idle. *(D101, 2026-11-11: the limits hold with Advanced metrics on — FR-5.6. Its reads run on a thread of their own, the slow ones seldom, and with no game running only while its page is open (D107), so "~0% idle" is not spent on it. **Unmeasured** until the owner's run with the option on and off, `HANDOFF` §Owner-only.)*
- **NFR-3 Stability:** faults **originating in our own hook bodies** are contained by `FL_HOOK_GUARD`, counted, and self-disable the Overlay after 3 occurrences; the safety-unhook path completes within one frame. The Overlay adds no allocation, lock, syscall or logging to the present path.
> This deliberately does **not** say "must never crash a game" (`20_OPEN_QUESTIONS` §H8). SEH containment cannot reliably catch stack overflow, cannot intercept `__fastfail` — and `-D_HAS_EXCEPTIONS=0` converts a would-be STL throw into exactly that (`spike-notes.md` §H3) — and does not help when the game installs a vectored exception handler that runs first. An absolute promise the mechanism cannot support does not belong in a requirement, and must stay out of user-facing text: the Disclaimer already says injection carries risk, and that wording is the honest one.
+298 -1
View File
@@ -234,7 +234,7 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
| 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 |
| 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~~ **Corrected 2026-11-11: the vendored set does declare it** — `nvapi_lite_common.h:600`, which `nvapi.h` includes, with `NV_GPU_MEMORY_INFO_EX_V1` above it and its id in `nvapi_interface.h`; the search that found nothing looked in `nvapi.h` alone. It was not called because of that sentence, from 2026-09-10 until now. The bridge calls it from ABI 3 for the advanced memory rows (§Advanced metrics); `FlNvSample.vram` stays reserved, so which layer fills the base `vram_adapter` series does not change |
| **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) — and, since beta.24 (D63), the mode an NVIDIA App override set where the word says it applied; its `performanceMode` is in NGX's own numbering (Silent Hill 2, 2026-10-13: the App's Ultra Performance, profile value 5, reported as 3). *(Beta.27: never read after the game has gone — that reading, the last, had cleared `CREATED \| EVALUATE` on every stored session — and the two bits stand once a reading carried them: `03_METRICS` §The driver-reported rung.)* |
@@ -493,3 +493,300 @@ alone could never catch.
> (`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.**
## Advanced metrics (owner decisions D101–D108, 2026-11-11)
The owner asked for a setting, *"Thông số nâng cao"* (Advanced metrics), with a navigation item of its own, that shows
as much as the Streamline and NVAPI headers and PawnIO make available — numbers, tables, charts — **with each value
assigned to what it belongs to: one game session, or the PC**. Asked while planning, the owner chose: everything
that can be reached inside a game as well, in stages, the route refused on 2026-08-09 re-examined; stored in full with
the session; off by default, and off means nothing more is read; and the page never asks for administrator rights
itself. This section is the design those answers gave, the decisions taken with it, and the inventory.
**Nothing here is built by the pull request that wrote it** except the catalog
(`FrameLedger.Application.Advanced.AdvancedMetricCatalog`) and this section. Each later pull request of the train
states here what it built.
### The decisions
- **D101 — the option.** `telemetry.advanced`, off by default, read by the Agent at each session's start. **Off means
not read**: no additional call to NVAPI or LibreHardwareMonitor, nothing more stored, and the navigation item is
hidden. A session recorded while it was off shows N/A for everything here — it is not filled in afterwards.
- **D102 — where it is stored.** In two tables of their own (schema 0023), not in new columns of `sessions`: every
read of a `sessions` row, the JSON export and the bug bundle carry the whole row, and a driver profile does not
belong in a bug bundle. `machine_profiles` holds the facts of the PC, one row per distinct set, and a session points
to the row that was true when it ran — the trend's hardware-change markers and `hardware_snapshots` are untouched.
`session_advanced` holds one session's facts, its series' statistics and their directory. The series themselves go
to `sensor_blobs` under names that start with `adv.`, **with NaN for a tick that has no reading**: the fixed series
store −1 there and their readers drop every negative value, which would silently eat a −12 V rail.
- **D103 — LibreHardwareMonitor's other groups.** CPU, memory, motherboard (its sensor chip and embedded controller)
and storage are opened **only when the Agent already runs as administrator and PawnIO is installed** — the existing
admin mode (D34); the page says what is missing and links to that setting. Storage is temperature only, internal
drives only, and no more than once a minute. **Refused**: the power-supply and fan-controller groups, which make
the library search every USB HID device. **Deferred**: the battery group. This amends §L2's "nothing else, ever"
from the pull request that opens them.
- **D104 — identifiers are never read.** The card's board serial number and unique id, a display's EDID, and the list
of programs that are encoding. They are named in the inventory so the page can say so; a test holds that no stored
JSON has their keys. This is the only part of "everything" left out on purpose.
- **D105 — the navigation item** is the last of the pane's items; Ctrl+1 to Ctrl+5 keep their pages and **Ctrl+6**
opens it only while the option is on.
- **D106 — the `.partial` file skips what it does not know.** A chunk of an unknown type whose checksum is right is
passed over; until now it ended the read, so a build one release older lost everything after the first new chunk.
- **D107 — with no game running**, the Agent reads sensors only while the page is open, through one reader shared
with the sessions, closed again some seconds after the last use. A PC idling with FrameLedger in the tray reads
nothing (NFR-2's "~0% idle").
- **D108 — read-only, by a gate.** §Runtime policy's "never call a setter" becomes a build check: every `NvAPI_*`
call in the bridge's source is compared with a committed list, and the entry points that both read and write are
allowed with their read command only.
### What belongs to what
| Scope | What it is | Stored | Shown |
|---|---|---|---|
| `MachineFact` | true of the PC whatever is running: the card's firmware and architecture, the driver's package, what a display can do | `machine_profiles`, once per distinct set; a session points to its row | This PC |
| `SessionFact` | true of one session: the game's display state, the settings the driver's profile for that game sets | `session_advanced.facts_json` | Session |
| `Series`, during a session | a sensor of the PC sampled while the game ran | `sensor_blobs` (`adv.*`), statistics in `session_advanced.stats_json` | Session |
| `Series`, with no session | the same sensor, read because the page is open | nowhere | This PC |
A third tab, **Sources**, lists every row of the inventory with its state on this PC — read, or N/A with the reason:
not an NVIDIA card, the Agent is not administrator, PawnIO is not installed, the option was off when the session was
recorded, the hook is not built, the route is refused, a vendor's licence. A PC without an NVIDIA card shows N/A for
every `nvapi.` row; nothing is estimated in its place (FR-4.9).
### The trains
| Train | Release | What | Its gate |
|---|---|---|---|
| A | 0.1.0-beta.39 | read by the Agent only — NVAPI and LibreHardwareMonitor — storage, the page. **Nothing changes in code loaded into a game** | this section |
| B | 0.1.0-beta.40 | inside the game: more fields of the Streamline and FidelityFX calls already hooked, and new hooks on functions `sl.interposer.dll` **exports** (`17_HOOK_ENGINE` §Hook inventory's ⏳ rows); shared-memory layout 5 | a plan of its own; overhead measured |
| C | 0.1.0-beta.41 | Reflex latency per frame | a spike, then the owner's go or no |
| D | 0.1.0-beta.42 | the Streamline feature state behind `slGetFeatureFunction` — DLSS frame generation's, DLSS's, Reflex's | a spike, then the owner's go or no |
Rules 4 and 5, the hook inventory, the measured overhead and the anti-cheat guard bind B, C and D exactly as they bind
every hook. `sl::Constants` is read without its camera position, axes and matrices: where the camera is, is where the
player is (rule 4). NGX stays closed by its licence (`17_HOOK_ENGINE` §NGX).
**Train D re-examines a refusal; it does not lift it.** `handoff/history/p0-queue-1-6.md` refused, on five grounds,
hooking `slGetFeatureFunction` and patching the function it returns. The route to try is a different one:
`slGetFeatureFunction` is itself an export (`vendor-exports.json`), so its hook is an ordinary inventory row, and
what it hands back could be a wrapper for a fixed list of names instead of a patch at an address learned at run time
— which would answer grounds 1 to 4, and turn ground 5 into "measured only when injected at launch". Two things it
raises are the owner's: replacing the pointer the game receives is a **write**, which rule 4 forbids as written; and
a wrapper must outlive the Overlay's own unhook. If the spike cannot answer all of it, the route stays refused and
the page says so.
### Left out, by name
Present in the vendored `nvapi.h`, readable from the Agent, and not in the inventory — each is either not a
measurement of how a game runs or exists on professional cards only: ECC status and errors, NVLINK, illumination
(the card's lighting zones), licensable features, virtualization and GSP information, Quadro status, VR-ready data,
the IRQ and bus slot numbers, logical GPUs and SLI state, HDCP support, scan-out configuration, the colour and
info-frame controls. `NvAPI_DISP_GetTiming` calculates a timing from an input and reads nothing.
`NV_GET_ADAPTIVE_SYNC_DATA`'s last-flip count and timestamp mean nothing sampled once a second.
`NvAPI_GPU_ClientRegisterForUtilizationSampleUpdates` registers a callback, which is not a read.
### The inventory
One row per entry of `AdvancedMetricCatalog`, in its order; `AdvancedMetricCatalogTests` fails when this table and
the catalog differ in either direction. **Reach** is where a value can be read from, or why it is not read: `Agent`
(the Agent's own process), `AgentElevated` (the same, as administrator with PawnIO), `HookedCall` (an argument of a
call the Overlay already hooks — Train B), `NewHook` (a hook that is not built — Train B), `Spike` (Trains C and D),
`Refused`, `Deferred`, `Identifier` (D104), `PlayerState` (rule 4), `Licence`, `NotInHeaders`. Only the first two are
read by a build of Train A.
**NVAPI, the graphics card: facts**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.gpu.type` | Integrated or discrete graphics | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.system_type` | Laptop or desktop, as the driver sees the PC | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.external` | The card is an external one | MachineFact | Nvapi | Agent | Flag |
| `nvapi.gpu.bus_type` | The bus the card sits on | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.pci_ids` | PCI device, subsystem and revision ids - the model, not the unit | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.vbios_version` | Video BIOS version | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.architecture` | Chip architecture, implementation and revision | MachineFact | Nvapi | Agent | Text |
| `nvapi.gpu.core_count` | Graphics cores | MachineFact | Nvapi | Agent | Count |
| `nvapi.gpu.rt_cores` | Ray-tracing cores | MachineFact | Nvapi | Agent | Count |
| `nvapi.gpu.tensor_cores` | Tensor cores | MachineFact | Nvapi | Agent | Count |
| `nvapi.gpu.ram_bus_width` | Width of the card's memory bus | MachineFact | Nvapi | Agent | Bits |
| `nvapi.gpu.clock_base_core` | Base core clock | MachineFact | Nvapi | Agent | Megahertz |
| `nvapi.gpu.clock_base_memory` | Base memory clock | MachineFact | Nvapi | Agent | Megahertz |
| `nvapi.gpu.clock_boost_core` | Boost core clock | MachineFact | Nvapi | Agent | Megahertz |
| `nvapi.gpu.clock_boost_memory` | Boost memory clock | MachineFact | Nvapi | Agent | Megahertz |
| `nvapi.gpu.temp_default_max` | The core sensor's default maximum temperature | MachineFact | Nvapi | Agent | Celsius |
**NVAPI, the card's memory**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.vram.dedicated` | Dedicated video memory on the card | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.dedicated_available` | Dedicated video memory available for surfaces | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.system` | System memory the driver reserved at load | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.shared` | Shared system memory the driver may commit | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.framebuffer_physical` | Physical frame buffer size | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.framebuffer_virtual` | Virtual frame buffer size | MachineFact | Nvapi | Agent | Mebibytes |
| `nvapi.vram.available` | Dedicated video memory available now, all programs | Series | Nvapi | Agent | Mebibytes |
| `nvapi.vram.in_use` | Dedicated video memory in use now, all programs: available for surfaces less available now | Series | Nvapi | Agent | Mebibytes |
| `nvapi.vram.evictions_size` | Memory released by evictions since the driver loaded | Series | Nvapi | Agent | Mebibytes |
| `nvapi.vram.eviction_count` | Evictions from dedicated video memory since the driver loaded | Series | Nvapi | Agent | Count |
| `nvapi.vram.promotions_size` | Memory moved in by promotions since the driver loaded | Series | Nvapi | Agent | Mebibytes |
| `nvapi.vram.promotion_count` | Promotions into dedicated video memory since the driver loaded | Series | Nvapi | Agent | Count |
**NVAPI, the card over time**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.load.framebuffer` | Frame-buffer (memory controller) utilisation | Series | Nvapi | Agent | Percent |
| `nvapi.load.video` | Video-engine utilisation | Series | Nvapi | Agent | Percent |
| `nvapi.load.bus` | Bus-interface utilisation | Series | Nvapi | Agent | Percent |
| `nvapi.clock.video` | Video clock | Series | Nvapi | Agent | Megahertz |
| `nvapi.pstate` | The card's current performance state (P-state id) | Series | Nvapi | Agent | Count |
| `nvapi.temp.board` | Board ambient temperature, where the card has the sensor | Series | Nvapi | Agent | Celsius |
| `nvapi.temp.power_supply` | The card's power-supply temperature, where it has the sensor | Series | Nvapi | Agent | Celsius |
| `nvapi.limit.ac_battery` | Held back by a switch to battery on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
| `nvapi.limit.api` | Held back at a program's request on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
| `nvapi.limit.insufficient_power` | Held back by a missing power connector on the tick: 100 or 0 | Series | Nvapi | Agent | Percent |
| `nvapi.encoder.sessions` | Active hardware-encoder sessions, all programs | Series | Nvapi | Agent | Count |
| `nvapi.encoder.fps` | Average encoding rate of the active sessions | Series | Nvapi | Agent | FramesPerSecond |
| `nvapi.encoder.latency` | Average encoding latency | Series | Nvapi | Agent | Microseconds |
**NVAPI, the driver**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.driver.package` | Game Ready, Studio or an RTX enterprise branch | MachineFact | Nvapi | Agent | Text |
| `nvapi.driver.dch` | The driver is a DCH package | MachineFact | Nvapi | Agent | Flag |
| `nvapi.driver.base_branch` | The driver's base branch | MachineFact | Nvapi | Agent | Text |
| `nvapi.driver.interface_version` | NVAPI's own interface version | MachineFact | Nvapi | Agent | Text |
| `nvapi.driver.chipset` | Chipset vendor and name, as the driver reports them | MachineFact | Nvapi | Agent | Text |
| `nvapi.driver.global_profile` | Every setting of the driver's global profile, read-only | MachineFact | Nvapi | Agent | Table |
| `nvapi.session.driver_profile` | The settings the driver's profile for this game sets itself, read-only | SessionFact | Nvapi | Agent | Table |
**NVAPI, displays**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.display.hdr_formats` | HDR formats a display accepts: HDR10, HDR10+, HDR10+ Gaming, Dolby Vision, EDR | MachineFact, one per device | Nvapi | Agent | Text |
| `nvapi.display.luminance_max` | A display's maximum luminance for HDR content | MachineFact, one per device | Nvapi | Agent | Nits |
| `nvapi.display.luminance_min` | Its minimum luminance | MachineFact, one per device | Nvapi | Agent | Nits |
| `nvapi.display.luminance_max_frame_average` | Its maximum frame-average light level | MachineFact, one per device | Nvapi | Agent | Nits |
| `nvapi.display.vrr_support` | Variable refresh: supported, G-SYNC module or adaptive sync, ULMB, usable at the current mode | MachineFact, one per device | Nvapi | Agent | Text |
| `nvapi.display.adaptive_sync_off` | Adaptive sync is switched off on the display | MachineFact, one per device | Nvapi | Agent | Flag |
| `nvapi.display.max_frame_interval` | The longest frame interval adaptive sync is set to hold | MachineFact, one per device | Nvapi | Agent | Microseconds |
| `nvapi.session.vrr_enabled` | Variable refresh was active on the game's display | SessionFact | Nvapi | Agent | Flag |
| `nvapi.session.vrr_requested` | Variable refresh was requested for it | SessionFact | Nvapi | Agent | Flag |
| `nvapi.session.vrr_possible` | Variable refresh was possible on it | SessionFact | Nvapi | Agent | Flag |
| `nvapi.session.vrr_display_mode` | The display itself was in variable-refresh mode | SessionFact | Nvapi | Agent | Flag |
| `nvapi.session.source_colorspace` | The colour space the game presented in, as the driver reports it for the process | SessionFact | Nvapi | Agent | Text |
**LibreHardwareMonitor, the graphics card (every vendor, unelevated)**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `lhm.gpu.temperature` | Every temperature sensor of the card | Series, one per device | Lhm | Agent | Celsius |
| `lhm.gpu.load` | Every load of the card: its engines, its bus, its memory controller | Series, one per device | Lhm | Agent | Percent |
| `lhm.gpu.memory` | The card's memory counters: total, free, used, Direct3D dedicated and shared | Series, one per device | Lhm | Agent | Mebibytes |
| `lhm.gpu.clock` | Every clock of the card | Series, one per device | Lhm | Agent | Megahertz |
| `lhm.gpu.power` | Every power reading of the card | Series, one per device | Lhm | Agent | Watts |
| `lhm.gpu.fan` | Every fan of the card | Series, one per device | Lhm | Agent | Rpm |
| `lhm.gpu.fan_control` | Each fan's duty | Series, one per device | Lhm | Agent | Percent |
| `lhm.gpu.voltage` | Every voltage of the card | Series, one per device | Lhm | Agent | Volts |
| `lhm.gpu.current` | Every current of the card | Series, one per device | Lhm | Agent | Amperes |
| `lhm.gpu.throughput` | PCI Express traffic to and from the card | Series, one per device | Lhm | Agent | BytesPerSecond |
**LibreHardwareMonitor through PawnIO (the Agent as administrator, D103)**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `lhm.cpu.temperature` | Processor temperatures: the package and each core | Series, one per device | Lhm | AgentElevated | Celsius |
| `lhm.cpu.load` | Processor load: the total and each core | Series, one per device | Lhm | AgentElevated | Percent |
| `lhm.cpu.clock` | Each core's clock, and the bus clock | Series, one per device | Lhm | AgentElevated | Megahertz |
| `lhm.cpu.power` | Processor power: the package, the cores | Series, one per device | Lhm | AgentElevated | Watts |
| `lhm.cpu.voltage` | Processor voltages | Series, one per device | Lhm | AgentElevated | Volts |
| `lhm.board.model` | The motherboard's maker and model | MachineFact | Lhm | AgentElevated | Text |
| `lhm.board.sensor_chip` | The board's sensor chip | MachineFact | Lhm | AgentElevated | Text |
| `lhm.board.temperature` | The board's temperature sensors | Series, one per device | Lhm | AgentElevated | Celsius |
| `lhm.board.fan` | Each fan header's speed | Series, one per device | Lhm | AgentElevated | Rpm |
| `lhm.board.fan_control` | Each fan header's duty | Series, one per device | Lhm | AgentElevated | Percent |
| `lhm.board.voltage` | The board's voltage rails | Series, one per device | Lhm | AgentElevated | Volts |
| `lhm.memory.modules` | The memory modules: size, speed, maker's part name - never a serial number | MachineFact | Lhm | AgentElevated | Table |
| `lhm.memory.load` | Memory in use: physical and virtual | Series, one per device | Lhm | AgentElevated | Percent |
| `lhm.memory.temperature` | Each memory module's temperature, where it has a sensor | Series, one per device | Lhm | AgentElevated | Celsius |
| `lhm.storage.models` | The internal drives' model names - never a serial number | MachineFact | Lhm | AgentElevated | Table |
| `lhm.storage.temperature` | Each internal drive's temperature, read no more than once a minute | Series, one per device | Lhm | AgentElevated | Celsius |
**What the Agent could reach and does not**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `lhm.psu` | Power-supply sensors: reading them makes the library search every USB device | MachineFact | Lhm | Refused | Table |
| `lhm.controller` | Fan-controller sensors: the same search of USB devices | MachineFact | Lhm | Refused | Table |
| `lhm.battery` | Battery sensors | MachineFact | Lhm | Deferred | Table |
| `nvapi.gpu.board_serial` | The card's board serial number | MachineFact | Nvapi | Identifier | Text |
| `nvapi.gpu.uuid` | The card's unique id | MachineFact | Nvapi | Identifier | Text |
| `nvapi.display.edid` | A display's EDID block, which carries its serial number | MachineFact, one per device | Nvapi | Identifier | Text |
| `nvapi.encoder.session_processes` | Which programs are encoding | Series | Nvapi | Identifier | Table |
| `nvapi.gpu.power` | Card power through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Watts |
| `nvapi.gpu.fan_duty` | Fan duty through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Percent |
| `nvapi.gpu.voltage` | Card voltage through NVAPI (LibreHardwareMonitor reads it) | Series | Nvapi | NotInHeaders | Volts |
| `nvapi.gpu.ram_type` | The card's memory type | MachineFact | Nvapi | NotInHeaders | Text |
**Inside the game: calls the Overlay already hooks**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `sl.dlss.output_size` | The output size the game gave DLSS | SessionFact | Streamline | HookedCall | Text |
| `sl.dlss.presets` | The DLSS model preset per quality mode | SessionFact | Streamline | HookedCall | Text |
| `sl.dlss.hdr_input` | The game told DLSS its colour buffers are HDR | SessionFact | Streamline | HookedCall | Flag |
| `sl.dlss.auto_exposure` | DLSS auto-exposure | SessionFact | Streamline | HookedCall | Flag |
| `sl.dlss.alpha_upscaling` | DLSS upscales the alpha channel | SessionFact | Streamline | HookedCall | Flag |
| `sl.dlss.exposure` | Pre-exposure and exposure scale given to DLSS | SessionFact | Streamline | HookedCall | Text |
| `ffx.upscale.sharpening` | FSR sharpening: on or off, and its strength | SessionFact | FidelityFx | HookedCall | Text |
| `ffx.upscale.jitter` | The jitter offsets the game gave FSR | SessionFact | FidelityFx | HookedCall | Text |
| `ffx.upscale.exposure` | Pre-exposure given to FSR | SessionFact | FidelityFx | HookedCall | Text |
| `ffx.upscale.depth` | Near and far planes and field of view given to FSR | SessionFact | FidelityFx | HookedCall | Text |
| `ffx.upscale.flags` | The flags of the game's FSR dispatch | SessionFact | FidelityFx | HookedCall | Text |
| `ffx.upscale.frame_time_delta` | The frame time the game reported to FSR | Series | FidelityFx | HookedCall | Milliseconds |
| `ffx.memory_usage` | FSR's own video memory, when the game asks it | Series | FidelityFx | HookedCall | Mebibytes |
**Inside the game: hooks that are not built**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `sl.constants.jitter` | The jitter offsets the game gave Streamline | SessionFact | Streamline | NewHook | Text |
| `sl.constants.motion_vectors` | Motion-vector scale, and whether they are 3D, dilated, jittered | SessionFact | Streamline | NewHook | Text |
| `sl.constants.depth` | Near and far planes, and whether depth is inverted | SessionFact | Streamline | NewHook | Text |
| `sl.constants.projection` | Field of view, aspect ratio, orthographic or not | SessionFact | Streamline | NewHook | Text |
| `sl.constants.resets` | How often the game reset the upscaler's history | SessionFact | Streamline | NewHook | Count |
| `sl.feature.versions` | Each Streamline feature's version and its NGX model version | SessionFact | Streamline | NewHook | Table |
| `sl.feature.requirements` | What each Streamline feature requires: operating system, driver, buffers | SessionFact | Streamline | NewHook | Table |
| `sl.init.preferences` | The preferences the game started Streamline with | SessionFact | Streamline | NewHook | Text |
| `ffx.framegen.config` | The game's FSR frame-generation configuration | SessionFact | FidelityFx | NewHook | Text |
| `sl.constants.camera` | Camera position, axes and matrices | SessionFact | Streamline | PlayerState | Text |
**Inside the game: routes a spike decides**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.reflex.mode` | Reflex: low-latency mode, boost, the frame-rate limit | SessionFact | Nvapi | Spike | Text |
| `nvapi.reflex.sleep_status` | What the driver's low-latency state is | SessionFact | Nvapi | Spike | Text |
| `nvapi.reflex.frame_report` | Latency per frame: simulation, render submit, present, driver, OS queue, GPU render | Series, one per device | Nvapi | Spike | Microseconds |
| `sl.dlss.optimal_settings` | The render size and sharpness DLSS recommends | SessionFact | Streamline | Spike | Text |
| `sl.dlss.vram_estimate` | DLSS's own estimate of its video memory | Series | Streamline | Spike | Mebibytes |
| `sl.dlssg.options` | DLSS frame generation: mode, frames to generate | SessionFact | Streamline | Spike | Text |
| `sl.dlssg.state` | DLSS frame generation: status, the most frames it can generate | SessionFact | Streamline | Spike | Text |
| `sl.dlssg.frames_presented` | Frames DLSS frame generation presented, by its own count | Series | Streamline | Spike | Count |
| `sl.dlssg.vram_estimate` | DLSS frame generation's estimate of its video memory | Series | Streamline | Spike | Mebibytes |
| `sl.dlssd.options` | Ray reconstruction's options | SessionFact | Streamline | Spike | Text |
| `sl.nis.options` | NVIDIA Image Scaling's options | SessionFact | Streamline | Spike | Text |
| `sl.deepdvc.options` | RTX Dynamic Vibrance's options | SessionFact | Streamline | Spike | Text |
| `sl.reflex.state` | Reflex through Streamline: availability and its frame reports | SessionFact | Streamline | Spike | Table |
| `sl.pcl.markers` | PC-latency markers the game sets | Series | Streamline | Spike | Count |
**Closed by a licence**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `ngx.parameters` | NGX parameters: the quality value, the DLSS hints | SessionFact | Ngx | Licence | Table |
| `xess.options` | XeSS's options | SessionFact | Xess | Licence | Table |
| `sl.nvperf` | Streamline's performance counters (NSight Perf SDK licence) | Series | Streamline | Licence | Table |
+4
View File
@@ -1860,6 +1860,10 @@ Moved verbatim, in this order.
| M9 ✅ | **Closed 2026-08-02 by a decision.** The old file/module detection does not exist in this repository and the owner confirmed there is no copy elsewhere, so **"build a minimal static-hint detector as the measurement baseline" is now P0 item 3** (`15_ROADMAP`). It needs no guard and no injection. Until it exists, ADR-7's headline claim stays out of the README rather than being asserted unmeasured |
| M10 ❓ | **§CPU — is the CPU temperature this build reads the right sensor, and does it read at all on the owner's machine?** `LhmCpuTemperatureReader` (2026-09-21) opens a CPU-only LibreHardwareMonitor `Computer` when the Agent is elevated AND `PawnIo.IsInstalled`, takes the package sensor (`CPU Package` / `Core (Tctl/Tdie)`) and falls back to the hottest core. It was written against LHM's sensor names and a fake `ILhmComputer`; **no elevated run with PawnIO has been taken.** | **The measurement is one session:** Agent elevated, PawnIO installed, a five-minute capture with HWiNFO or Ryzen Master open beside it. Pre-committed: `max_cpu_temp` within 3 °C of the reference's package peak → keep; a core sensor picked where a package sensor exists, or a reading tens of degrees off (a distance-to-TjMax sensor mistaken for a temperature) → fix `Pick` and re-run; nothing read at all → `cpu_temp` stays N/A and `legal/ACCURACY.md` says processor temperature is not measured. CPU **load** and memory are not in question: `TheRealCountersAnswerOnThisMachine` reads them on every gate run. |
| M11 🅓 | **The game's VRAM budget and `budget_exceeded_pct` (FR-4.5's second half), 2026-10-03.** D43 reads the game's usage from outside (the `GPU Process Memory` counters); the budget the OS grants the process is what DXGI's `QueryVideoMemoryInfo` returns to the *calling* process (§M7), so only an in-process call — the Overlay's background thread, which today only checks for a stop — or `D3DKMTQueryStatistics`' `PROCESS_SEGMENT_GROUP` query (documented "Reserved for system use") could read it. **Deferred by decision:** neither is built; `vram_budget_exceeded_pct` stays NULL and the budget N/A, and the in-process route would change what the Disclaimer says the Overlay's thread does. Reopening it needs that decision, not a measurement. | — |
| M12 ❓ | **Advanced metrics — which NVAPI rows answer on real hardware (D101, 2026-11-11).** `18_GPU_VENDOR_APIS` §The inventory lists sixty `nvapi.` rows whose reach is `Agent`. They are declared in the vendored headers; **none has been called on a GPU**, and CI has no driver, so it never takes that branch. Unknown per row: whether the RTX 5080 on the current driver answers or returns `NVAPI_NOT_SUPPORTED` (the memory-temperature target already does not exist on that card). | **The measurement is the bridge's probe on the owner's PC**, then the page itself (the release's owner-only item). Pre-committed: a call that does not answer → that row is N/A with NVAPI's own status as the reason, and nothing is put in its place; a call that hangs or faults twice → the row is off for the session (§Runtime policy); a value that contradicts the vendor's own tool → the row is withheld until it is explained. |
| M13 ❓ | **Advanced metrics — LibreHardwareMonitor's CPU, memory, motherboard and storage groups, elevated, with PawnIO (D103, 2026-11-11).** Never opened by any build: §M10's elevated run has not been taken either, and this is a larger surface — a sensor chip on the LPC bus, the embedded controller, SPD over SMBus, SMART. Unknown: whether each group opens on the owner's board, what a refresh costs, whether opening the storage group touches removable drives (this PC once had a failing USB drive), and whether any group enables a privilege (`PrivilegeFootprintTests`). | **One elevated run with the probe verb, before the option exists.** Pre-committed: the storage group cannot be opened without touching removable drives → `lhm.storage.*` stays N/A in beta.39 and its reach reads `Deferred`; a node that throws twice → skipped for the session; the Agent above 1% of one core or 150 MB with the option on (NFR-2) → the slow groups are read less often or dropped before the release; a privilege enabled by a group → that group is not opened, and the owner is asked. |
| M14 ❓ | **Reflex latency per frame — is there a route within rules 4 and 5? (Train C, 2026-11-11.)** `17_HOOK_ENGINE` §Memory / latency names hooks on `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` and a call to `NvAPI_D3D_GetLatency`. NVAPI resolves all three through `nvapi_QueryInterface` by id — they are not exports, so a hook on them is a patch at an address learned at run time, the class refused on 2026-08-09. The route to try first needs no hook: the Overlay's own background thread **calls** `GetLatency` with the device of the swap chain it already hooks, once a second (the call returns the last 64 frames' reports). Unknown: whether calling into the driver from that thread is safe on every device kind, what it costs, what it returns when the game never enabled Reflex, and what it means for the Disclaimer's sentence about that thread. | **A spike on `hook-harness` and a stub first, then one real title.** Pre-committed: no route without a patch at a run-time address or a loader-lock call on the game's thread → Reflex stays N/A and the page says why; overhead above NFR-1 → the same. The owner says go or no on the spike's result. |
| M15 ❓ | **The Streamline state behind `slGetFeatureFunction` — re-examined, not reopened (Train D, 2026-11-11).** The owner asked for the refusal in `handoff/history/p0-queue-1-6.md` to be looked at again. `18_GPU_VENDOR_APIS` §The trains states the route to try (hook the export, hand back a wrapper for a fixed list of names) and what it raises: the wrapper is a write to what the game receives, which rule 4 forbids as written; a wrapper must outlive the Overlay's unhook; a game that fetched its functions before the hook existed is never seen. | **A written design against each of the five grounds, then a spike.** Pre-committed: any ground unanswered → the route stays refused, and `sl.dlssg.*`, `sl.reflex.*` and the rest of that block read N/A with "refused" as the reason. Proceeding needs the owner's amendment of rule 4, asked with the rule quoted. |
| M10 ✅ | ~~PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly~~ **Decided 2026-09-09 (PR-E1): L1 does not read the engine counters at all.** `LoadPct` is L2's vendor-reported `GPU Core` load (measured ✓ on NVIDIA, §M5 row R1) and is labelled *GPU load (vendor)* wherever it is shown; on a machine without L2 the field is N/A, never a sum that is not the number the user expects. What L1 does read from PDH is one counter, `\GPU Adapter Memory(luid_…_phys_0)\Dedicated Usage`, bound by LUID — the figure Task Manager labels "Dedicated GPU memory", measured 1301 MB at an idle desktop on the RTX 5080. Reopening this needs a measurement of `max(engine)` against Task Manager's own number, not a decision |
#### §M5 — the decision table, pre-committed 2026-09-03 BEFORE the first run
+50 -4
View File
@@ -124,15 +124,53 @@ the owner's decisions asked while planning. What follows is this session's readi
- **What a new page owes**: strings in `en`, `vi`, `ja`; `ACCESSIBILITY.md` §For contributors for the page and each
chart; `LIMITATIONS.md` and the guide; `08_UI`.
#### Planned 2026-11-11, and approved by the owner — four trains, the first begun
The plan was made the same day, the owner's decisions asked while planning. **The design, the decisions D101–D108 and
the inventory are [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics**; what follows is only what that
section does not carry — the order, and what was asked.
- **The owner's four answers.** (1) Inside the game: **everything, in stages — and the refusal of 2026-08-09 is
re-examined**, not taken as final. (2) **Stored in full with the session.** (3) **Off by default, and off means
nothing more is read or stored**; the navigation item is hidden. (4) PawnIO: **the page says what is missing and
links to the admin mode's setting** (D34); it never asks for the rights itself.
- **Four trains, one release each, in this order**: **A** (0.1.0-beta.39) what the Agent can read — NVAPI,
LibreHardwareMonitor — with storage and the page, **and nothing changed in code loaded into a game**; **B**
(beta.40) inside the game, on calls already hooked and on functions Streamline exports, shared-memory layout 5;
**C** (beta.41) Reflex latency, after a spike; **D** (beta.42) the Streamline state behind `slGetFeatureFunction`,
after a spike. **Why this order**: A needs no hook, so it ships the page, the storage and the option first and
every later train only fills rows; B is hooks of a kind already built; C and D are routes nobody has proven safe,
and each ends in the owner's go or no.
- **The approval covers train A whole** — its eight pull requests through the release. **B, C and D each begin with a
plan of their own**, their decisions asked then. For D the owner will be asked one thing nothing else has needed:
handing the game a wrapper in place of the function it asked for is a write, and rule 4 as written forbids it.
- **Train A's pull requests**: (1) decisions, inventory, the catalog; (2) the NVAPI bridge's ABI 3 and the read-only
gate; (3) LibreHardwareMonitor's groups and the shared reader, not yet composed; (4) the `.partial` chunks and
schema 0023, produced by nobody yet; (5) the option goes live, with Privacy 2.15; (6) the pipe request and the
App's feed; (7) the page, the navigation item, Ctrl+6; (8) the release. A setting and its guide text, a navigation
item and its guide text, a schema script and its writer each land in ONE pull request — the guide tests, the
viewer-mode test and the registry test are red otherwise.
- **What the owner will be asked to run** (the release's owner-only item): the NVAPI rows on the RTX 5080 — CI has no
driver and never takes that branch; one run as administrator with PawnIO, which is also the first there has ever
been (`20_OPEN_QUESTIONS` §M10); the Agent's processor time and memory with the option on and off (NFR-2).
- **A trap already paid for**: LibreHardwareMonitor's storage group may touch every drive when it opens, and this
PC once had a failing USB drive. If the group cannot be opened without touching removable drives, storage stays
N/A in beta.39 — decided before the first run, not after it.
### Left open by this session
- **`LogNoteW`** (`src/native/FrameLedger.Overlay/src/dllmain.cpp`): a function nothing calls, found by the native
report and **not removed** — D100 changes code loaded into a game for a defect only, and dead code is not one. The
owner says whether it goes (owner-only item 36 (d)); `.editorconfig` has a section, naming it, that goes with it.
- **This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request, as beta.37's and alpha.4's were in #384. What is known
before the tag: the rehearsal on the release branch (run 42944533749) made a delta from beta.37 of 727,036
bytes — "Delta processed 0452 files. 0022 patched, 0430 unchanged, 0000 new, 0000 removed".
- ~~**This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request, as beta.37's and alpha.4's were in #384.~~ **Recorded
2026-11-11, in the first pull request of the Advanced-metrics train: 0.1.0-beta.38 was released
2026-11-11T02:56:51Z** from the signed tag on `b7d6550`, by run 42947853293 — one run for the one tag push, where
alpha.4's push had started two. Eight assets; the seven digests of `SHA256SUMS.txt` equal the ones GitHub computed;
the shipped natives carry `FL_BUILD_ID v0.1.0-beta.38`. The delta from beta.37 is 699,201 bytes beside a full
package of 110,325,438 — "Delta processed 0452 files. 0022 patched, 0430 unchanged". The wiki was published by run
42949461191. The rehearsal on the release branch (run 42944533749) had made a delta of 727,036 bytes with the same
file counts.
- **The Qodana licence** is read from the job's log (*Qodana license plan: Ultimate*, and the day the subscription is
active until). When it lapses both jobs are red and advisory; `qodana.yaml`'s first comment is the way back.
- **C# 15's constructs** wait for a ReSharper engine that reads them (`20_OPEN_QUESTIONS` §G, the row added with
@@ -537,6 +575,14 @@ Where each owner decision is recorded — the file and its section, and a label
| D98 | [`12_BUILD.md`](12_BUILD.md) §The alpha line | alpha.4 is beta.37's source on .NET 11.0.0, and then the alpha line rests until a newer .NET has a preview; a resting alpha tells its user to install the beta |
| D99 | [`13_CI_CD.md`](13_CI_CD.md) §Qodana | Qodana for .NET on the Ultimate licence, in two reports from the start: the managed code to the Qodana Cloud project `frameledger`, the C++ to `frameledger-cpp` |
| D100 | [`13_CI_CD.md`](13_CI_CD.md) §Qodana | an inspection is switched off where the engine that raised it reads — ReSharper's in `.editorconfig`, the rest in `qodana.yaml` (amends D93); hints are off as a severity; in code loaded into a game only defects are fixed |
| D101 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | "Thông số nâng cao" — Advanced metrics: the option `telemetry.advanced`, off by default, and off means nothing more is read or stored and the navigation item is hidden; everything reachable inside a game follows in stages, four trains A–D |
| D102 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | stored in full with the session, in tables of their own (`machine_profiles`, `session_advanced`, schema 0023) and not in columns of `sessions`; series under `adv.` names with NaN, not −1, for a tick with no reading |
| D103 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | LibreHardwareMonitor's CPU, memory, motherboard and storage groups only when the Agent already runs as administrator with PawnIO — the page links to that setting and never asks; power-supply and fan-controller groups refused, battery deferred |
| D104 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | identifiers are never read: the card's serial number and unique id, a display's EDID, the list of programs that are encoding |
| D105 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | the navigation item is the pane's last; Ctrl+1–5 keep their pages and Ctrl+6 opens it only while the option is on |
| D106 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | a `.partial` chunk of an unknown type with a right checksum is skipped, where it ended the read |
| D107 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | with no game running the Agent reads sensors only while the page is open |
| D108 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Advanced metrics | "never call a setter" is a build gate: every `NvAPI_*` call of the bridge is held to a committed list |
---
@@ -0,0 +1,23 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>The heading an advanced metric is shown under.</summary>
public enum AdvancedGroup
{
/// <summary>Not stated. No entry of the catalog carries it.</summary>
None = 0,
Gpu = 1,
GpuMemory = 2,
Driver = 3,
Display = 4,
Cpu = 5,
Board = 6,
Memory = 7,
Storage = 8,
Upscaling = 9,
FrameGeneration = 10,
Latency = 11,
}
@@ -0,0 +1,47 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>
/// One row of <see cref="AdvancedMetricCatalog"/>: a number, a fact or a family of sensors that a vendor interface
/// makes available, with the scope it belongs to and where it can be read from.
/// </summary>
/// <param name="Id">Lower case, dotted, starting with the source's prefix. It is on disk once a release stores it, and then never changes.</param>
/// <param name="Scope">The machine or one session.</param>
/// <param name="Source">The vendor interface.</param>
/// <param name="Reach">Where it can be read from, or why it is not read.</param>
/// <param name="Unit">What its value is.</param>
/// <param name="Group">The heading it is shown under.</param>
/// <param name="Summary">
/// What it is, in English, for <c>docs/18_GPU_VENDOR_APIS.md</c> §The inventory — the table there is held to this
/// text by a test. The App shows the translated string under <see cref="LabelKey"/>, never this.
/// </param>
public sealed record AdvancedMetric(
string Id,
AdvancedScope Scope,
AdvancedSource Source,
AdvancedReach Reach,
AdvancedUnit Unit,
AdvancedGroup Group,
string Summary)
{
/// <summary>The prefix of every advanced series in <c>sensor_blobs</c> (D102): a reader tells them from the fixed series by it.</summary>
public const string SeriesPrefix = "adv.";
/// <summary>
/// True when the entry is not one value but as many as the hardware has — a temperature per core, a fan per
/// header, a set of facts per display. Each instance is named by <see cref="AdvancedMetricCatalog.InstanceName"/>
/// and labelled by what the hardware calls it.
/// </summary>
public bool IsFamily { get; init; }
/// <summary>True when a build with the option on reads it: every other reach is a reason it reads N/A.</summary>
public bool IsRead => Reach is AdvancedReach.Agent or AdvancedReach.AgentElevated;
/// <summary>The name of its series in <c>sensor_blobs</c> — for a family, the stem of its instances' names; null when it is not a series.</summary>
public string? SeriesName => Scope == AdvancedScope.Series ? SeriesPrefix + Id : null;
/// <summary>The key of its translated label in the App's resources.</summary>
public string LabelKey => "Adv_" + Id.Replace('.', '_');
}
@@ -0,0 +1,267 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Collections.Frozen;
using static FrameLedger.Application.Advanced.AdvancedGroup;
using static FrameLedger.Application.Advanced.AdvancedReach;
using static FrameLedger.Application.Advanced.AdvancedSource;
using static FrameLedger.Application.Advanced.AdvancedUnit;
namespace FrameLedger.Application.Advanced;
/// <summary>
/// Everything "Advanced metrics" (owner decision D101) knows of: what the vendored NVAPI and Streamline headers, the
/// FidelityFX headers and LibreHardwareMonitor make available — what is read, and what is not with the reason.
/// </summary>
/// <remarks>
/// ONE LIST FOR EVERY CONSUMER. Before it, a metric's name, unit and label were repeated in three to five places
/// (the trend's enum, its unit switch, its label list, Compare's rows, the summary's cards). The reader that
/// collects, the recorder that stores, the page that shows and the table in
/// <c>docs/18_GPU_VENDOR_APIS.md</c> §The inventory all read this list, and a test holds that table to it — so an
/// entry cannot be stored without being shown, or documented as read while it is not.
/// <para>
/// AN ENTRY THAT IS NOT READ IS STILL AN ENTRY. The owner asked for everything the headers give; what stays out
/// stays out for a reason — a hook that is not built, a route nobody has proven safe, a licence, an identifier,
/// the player's own state — and the page's Sources tab says which.
/// </para>
/// </remarks>
public static class AdvancedMetricCatalog
{
/// <summary>
/// The entries, in the order the page lists them. An id is on disk from the first release that stores it and
/// never changes after; an entry is added at the end of its block.
/// </summary>
public static IReadOnlyList<AdvancedMetric> All { get; } =
[
// ---- NVAPI, the graphics card: facts -------------------------------------------------------------------
Machine("nvapi.gpu.type", Nvapi, Agent, Text, Gpu, "Integrated or discrete graphics"),
Machine("nvapi.gpu.system_type", Nvapi, Agent, Text, Gpu, "Laptop or desktop, as the driver sees the PC"),
Machine("nvapi.gpu.external", Nvapi, Agent, Flag, Gpu, "The card is an external one"),
Machine("nvapi.gpu.bus_type", Nvapi, Agent, Text, Gpu, "The bus the card sits on"),
Machine("nvapi.gpu.pci_ids", Nvapi, Agent, Text, Gpu, "PCI device, subsystem and revision ids - the model, not the unit"),
Machine("nvapi.gpu.vbios_version", Nvapi, Agent, Text, Gpu, "Video BIOS version"),
Machine("nvapi.gpu.architecture", Nvapi, Agent, Text, Gpu, "Chip architecture, implementation and revision"),
Machine("nvapi.gpu.core_count", Nvapi, Agent, Count, Gpu, "Graphics cores"),
Machine("nvapi.gpu.rt_cores", Nvapi, Agent, Count, Gpu, "Ray-tracing cores"),
Machine("nvapi.gpu.tensor_cores", Nvapi, Agent, Count, Gpu, "Tensor cores"),
Machine("nvapi.gpu.ram_bus_width", Nvapi, Agent, Bits, Gpu, "Width of the card's memory bus"),
Machine("nvapi.gpu.clock_base_core", Nvapi, Agent, Megahertz, Gpu, "Base core clock"),
Machine("nvapi.gpu.clock_base_memory", Nvapi, Agent, Megahertz, Gpu, "Base memory clock"),
Machine("nvapi.gpu.clock_boost_core", Nvapi, Agent, Megahertz, Gpu, "Boost core clock"),
Machine("nvapi.gpu.clock_boost_memory", Nvapi, Agent, Megahertz, Gpu, "Boost memory clock"),
Machine("nvapi.gpu.temp_default_max", Nvapi, Agent, Celsius, Gpu, "The core sensor's default maximum temperature"),
// ---- NVAPI, the card's memory --------------------------------------------------------------------------
Machine("nvapi.vram.dedicated", Nvapi, Agent, Mebibytes, GpuMemory, "Dedicated video memory on the card"),
Machine("nvapi.vram.dedicated_available", Nvapi, Agent, Mebibytes, GpuMemory, "Dedicated video memory available for surfaces"),
Machine("nvapi.vram.system", Nvapi, Agent, Mebibytes, GpuMemory, "System memory the driver reserved at load"),
Machine("nvapi.vram.shared", Nvapi, Agent, Mebibytes, GpuMemory, "Shared system memory the driver may commit"),
Machine("nvapi.vram.framebuffer_physical", Nvapi, Agent, Mebibytes, GpuMemory, "Physical frame buffer size"),
Machine("nvapi.vram.framebuffer_virtual", Nvapi, Agent, Mebibytes, GpuMemory, "Virtual frame buffer size"),
Sampled("nvapi.vram.available", Nvapi, Agent, Mebibytes, GpuMemory, "Dedicated video memory available now, all programs"),
Sampled("nvapi.vram.in_use", Nvapi, Agent, Mebibytes, GpuMemory, "Dedicated video memory in use now, all programs: available for surfaces less available now"),
Sampled("nvapi.vram.evictions_size", Nvapi, Agent, Mebibytes, GpuMemory, "Memory released by evictions since the driver loaded"),
Sampled("nvapi.vram.eviction_count", Nvapi, Agent, Count, GpuMemory, "Evictions from dedicated video memory since the driver loaded"),
Sampled("nvapi.vram.promotions_size", Nvapi, Agent, Mebibytes, GpuMemory, "Memory moved in by promotions since the driver loaded"),
Sampled("nvapi.vram.promotion_count", Nvapi, Agent, Count, GpuMemory, "Promotions into dedicated video memory since the driver loaded"),
// ---- NVAPI, the card over time -------------------------------------------------------------------------
Sampled("nvapi.load.framebuffer", Nvapi, Agent, Percent, Gpu, "Frame-buffer (memory controller) utilisation"),
Sampled("nvapi.load.video", Nvapi, Agent, Percent, Gpu, "Video-engine utilisation"),
Sampled("nvapi.load.bus", Nvapi, Agent, Percent, Gpu, "Bus-interface utilisation"),
Sampled("nvapi.clock.video", Nvapi, Agent, Megahertz, Gpu, "Video clock"),
Sampled("nvapi.pstate", Nvapi, Agent, Count, Gpu, "The card's current performance state (P-state id)"),
Sampled("nvapi.temp.board", Nvapi, Agent, Celsius, Gpu, "Board ambient temperature, where the card has the sensor"),
Sampled("nvapi.temp.power_supply", Nvapi, Agent, Celsius, Gpu, "The card's power-supply temperature, where it has the sensor"),
Sampled("nvapi.limit.ac_battery", Nvapi, Agent, Percent, Gpu, "Held back by a switch to battery on the tick: 100 or 0"),
Sampled("nvapi.limit.api", Nvapi, Agent, Percent, Gpu, "Held back at a program's request on the tick: 100 or 0"),
Sampled("nvapi.limit.insufficient_power", Nvapi, Agent, Percent, Gpu, "Held back by a missing power connector on the tick: 100 or 0"),
Sampled("nvapi.encoder.sessions", Nvapi, Agent, Count, Gpu, "Active hardware-encoder sessions, all programs"),
Sampled("nvapi.encoder.fps", Nvapi, Agent, FramesPerSecond, Gpu, "Average encoding rate of the active sessions"),
Sampled("nvapi.encoder.latency", Nvapi, Agent, Microseconds, Gpu, "Average encoding latency"),
// ---- NVAPI, the driver ---------------------------------------------------------------------------------
Machine("nvapi.driver.package", Nvapi, Agent, Text, Driver, "Game Ready, Studio or an RTX enterprise branch"),
Machine("nvapi.driver.dch", Nvapi, Agent, Flag, Driver, "The driver is a DCH package"),
Machine("nvapi.driver.base_branch", Nvapi, Agent, Text, Driver, "The driver's base branch"),
Machine("nvapi.driver.interface_version", Nvapi, Agent, Text, Driver, "NVAPI's own interface version"),
Machine("nvapi.driver.chipset", Nvapi, Agent, Text, Driver, "Chipset vendor and name, as the driver reports them"),
Machine("nvapi.driver.global_profile", Nvapi, Agent, Table, Driver, "Every setting of the driver's global profile, read-only"),
Session("nvapi.session.driver_profile", Nvapi, Agent, Table, Driver, "The settings the driver's profile for this game sets itself, read-only"),
// ---- NVAPI, displays -----------------------------------------------------------------------------------
MachineFamily("nvapi.display.hdr_formats", Nvapi, Agent, Text, Display, "HDR formats a display accepts: HDR10, HDR10+, HDR10+ Gaming, Dolby Vision, EDR"),
MachineFamily("nvapi.display.luminance_max", Nvapi, Agent, Nits, Display, "A display's maximum luminance for HDR content"),
MachineFamily("nvapi.display.luminance_min", Nvapi, Agent, Nits, Display, "Its minimum luminance"),
MachineFamily("nvapi.display.luminance_max_frame_average", Nvapi, Agent, Nits, Display, "Its maximum frame-average light level"),
MachineFamily("nvapi.display.vrr_support", Nvapi, Agent, Text, Display, "Variable refresh: supported, G-SYNC module or adaptive sync, ULMB, usable at the current mode"),
MachineFamily("nvapi.display.adaptive_sync_off", Nvapi, Agent, Flag, Display, "Adaptive sync is switched off on the display"),
MachineFamily("nvapi.display.max_frame_interval", Nvapi, Agent, Microseconds, Display, "The longest frame interval adaptive sync is set to hold"),
Session("nvapi.session.vrr_enabled", Nvapi, Agent, Flag, Display, "Variable refresh was active on the game's display"),
Session("nvapi.session.vrr_requested", Nvapi, Agent, Flag, Display, "Variable refresh was requested for it"),
Session("nvapi.session.vrr_possible", Nvapi, Agent, Flag, Display, "Variable refresh was possible on it"),
Session("nvapi.session.vrr_display_mode", Nvapi, Agent, Flag, Display, "The display itself was in variable-refresh mode"),
Session("nvapi.session.source_colorspace", Nvapi, Agent, Text, Display, "The colour space the game presented in, as the driver reports it for the process"),
// ---- LibreHardwareMonitor, the graphics card (every vendor, unelevated) ---------------------------------
SampledFamily("lhm.gpu.temperature", Lhm, Agent, Celsius, Gpu, "Every temperature sensor of the card"),
SampledFamily("lhm.gpu.load", Lhm, Agent, Percent, Gpu, "Every load of the card: its engines, its bus, its memory controller"),
SampledFamily("lhm.gpu.memory", Lhm, Agent, Mebibytes, GpuMemory, "The card's memory counters: total, free, used, Direct3D dedicated and shared"),
SampledFamily("lhm.gpu.clock", Lhm, Agent, Megahertz, Gpu, "Every clock of the card"),
SampledFamily("lhm.gpu.power", Lhm, Agent, Watts, Gpu, "Every power reading of the card"),
SampledFamily("lhm.gpu.fan", Lhm, Agent, Rpm, Gpu, "Every fan of the card"),
SampledFamily("lhm.gpu.fan_control", Lhm, Agent, Percent, Gpu, "Each fan's duty"),
SampledFamily("lhm.gpu.voltage", Lhm, Agent, Volts, Gpu, "Every voltage of the card"),
SampledFamily("lhm.gpu.current", Lhm, Agent, Amperes, Gpu, "Every current of the card"),
SampledFamily("lhm.gpu.throughput", Lhm, Agent, BytesPerSecond, Gpu, "PCI Express traffic to and from the card"),
// ---- LibreHardwareMonitor through PawnIO (the Agent as administrator, D103) -----------------------------
SampledFamily("lhm.cpu.temperature", Lhm, AgentElevated, Celsius, Cpu, "Processor temperatures: the package and each core"),
SampledFamily("lhm.cpu.load", Lhm, AgentElevated, Percent, Cpu, "Processor load: the total and each core"),
SampledFamily("lhm.cpu.clock", Lhm, AgentElevated, Megahertz, Cpu, "Each core's clock, and the bus clock"),
SampledFamily("lhm.cpu.power", Lhm, AgentElevated, Watts, Cpu, "Processor power: the package, the cores"),
SampledFamily("lhm.cpu.voltage", Lhm, AgentElevated, Volts, Cpu, "Processor voltages"),
Machine("lhm.board.model", Lhm, AgentElevated, Text, Board, "The motherboard's maker and model"),
Machine("lhm.board.sensor_chip", Lhm, AgentElevated, Text, Board, "The board's sensor chip"),
SampledFamily("lhm.board.temperature", Lhm, AgentElevated, Celsius, Board, "The board's temperature sensors"),
SampledFamily("lhm.board.fan", Lhm, AgentElevated, Rpm, Board, "Each fan header's speed"),
SampledFamily("lhm.board.fan_control", Lhm, AgentElevated, Percent, Board, "Each fan header's duty"),
SampledFamily("lhm.board.voltage", Lhm, AgentElevated, Volts, Board, "The board's voltage rails"),
Machine("lhm.memory.modules", Lhm, AgentElevated, Table, Memory, "The memory modules: size, speed, maker's part name - never a serial number"),
SampledFamily("lhm.memory.load", Lhm, AgentElevated, Percent, Memory, "Memory in use: physical and virtual"),
SampledFamily("lhm.memory.temperature", Lhm, AgentElevated, Celsius, Memory, "Each memory module's temperature, where it has a sensor"),
Machine("lhm.storage.models", Lhm, AgentElevated, Table, Storage, "The internal drives' model names - never a serial number"),
SampledFamily("lhm.storage.temperature", Lhm, AgentElevated, Celsius, Storage, "Each internal drive's temperature, read no more than once a minute"),
// ---- What the Agent could reach and does not ------------------------------------------------------------
Machine("lhm.psu", Lhm, Refused, Table, Board, "Power-supply sensors: reading them makes the library search every USB device"),
Machine("lhm.controller", Lhm, Refused, Table, Board, "Fan-controller sensors: the same search of USB devices"),
Machine("lhm.battery", Lhm, Deferred, Table, Board, "Battery sensors"),
Machine("nvapi.gpu.board_serial", Nvapi, Identifier, Text, Gpu, "The card's board serial number"),
Machine("nvapi.gpu.uuid", Nvapi, Identifier, Text, Gpu, "The card's unique id"),
MachineFamily("nvapi.display.edid", Nvapi, Identifier, Text, Display, "A display's EDID block, which carries its serial number"),
Sampled("nvapi.encoder.session_processes", Nvapi, Identifier, Table, Gpu, "Which programs are encoding"),
Sampled("nvapi.gpu.power", Nvapi, NotInHeaders, Watts, Gpu, "Card power through NVAPI (LibreHardwareMonitor reads it)"),
Sampled("nvapi.gpu.fan_duty", Nvapi, NotInHeaders, Percent, Gpu, "Fan duty through NVAPI (LibreHardwareMonitor reads it)"),
Sampled("nvapi.gpu.voltage", Nvapi, NotInHeaders, Volts, Gpu, "Card voltage through NVAPI (LibreHardwareMonitor reads it)"),
Machine("nvapi.gpu.ram_type", Nvapi, NotInHeaders, Text, GpuMemory, "The card's memory type"),
// ---- Inside the game: calls the Overlay already hooks ---------------------------------------------------
Session("sl.dlss.output_size", Streamline, HookedCall, Text, Upscaling, "The output size the game gave DLSS"),
Session("sl.dlss.presets", Streamline, HookedCall, Text, Upscaling, "The DLSS model preset per quality mode"),
Session("sl.dlss.hdr_input", Streamline, HookedCall, Flag, Upscaling, "The game told DLSS its colour buffers are HDR"),
Session("sl.dlss.auto_exposure", Streamline, HookedCall, Flag, Upscaling, "DLSS auto-exposure"),
Session("sl.dlss.alpha_upscaling", Streamline, HookedCall, Flag, Upscaling, "DLSS upscales the alpha channel"),
Session("sl.dlss.exposure", Streamline, HookedCall, Text, Upscaling, "Pre-exposure and exposure scale given to DLSS"),
Session("ffx.upscale.sharpening", FidelityFx, HookedCall, Text, Upscaling, "FSR sharpening: on or off, and its strength"),
Session("ffx.upscale.jitter", FidelityFx, HookedCall, Text, Upscaling, "The jitter offsets the game gave FSR"),
Session("ffx.upscale.exposure", FidelityFx, HookedCall, Text, Upscaling, "Pre-exposure given to FSR"),
Session("ffx.upscale.depth", FidelityFx, HookedCall, Text, Upscaling, "Near and far planes and field of view given to FSR"),
Session("ffx.upscale.flags", FidelityFx, HookedCall, Text, Upscaling, "The flags of the game's FSR dispatch"),
Sampled("ffx.upscale.frame_time_delta", FidelityFx, HookedCall, Milliseconds, Upscaling, "The frame time the game reported to FSR"),
Sampled("ffx.memory_usage", FidelityFx, HookedCall, Mebibytes, Upscaling, "FSR's own video memory, when the game asks it"),
// ---- Inside the game: hooks that are not built ----------------------------------------------------------
Session("sl.constants.jitter", Streamline, NewHook, Text, Upscaling, "The jitter offsets the game gave Streamline"),
Session("sl.constants.motion_vectors", Streamline, NewHook, Text, Upscaling, "Motion-vector scale, and whether they are 3D, dilated, jittered"),
Session("sl.constants.depth", Streamline, NewHook, Text, Upscaling, "Near and far planes, and whether depth is inverted"),
Session("sl.constants.projection", Streamline, NewHook, Text, Upscaling, "Field of view, aspect ratio, orthographic or not"),
Session("sl.constants.resets", Streamline, NewHook, Count, Upscaling, "How often the game reset the upscaler's history"),
Session("sl.feature.versions", Streamline, NewHook, Table, Upscaling, "Each Streamline feature's version and its NGX model version"),
Session("sl.feature.requirements", Streamline, NewHook, Table, Upscaling, "What each Streamline feature requires: operating system, driver, buffers"),
Session("sl.init.preferences", Streamline, NewHook, Text, Upscaling, "The preferences the game started Streamline with"),
Session("ffx.framegen.config", FidelityFx, NewHook, Text, FrameGeneration, "The game's FSR frame-generation configuration"),
Session("sl.constants.camera", Streamline, PlayerState, Text, Upscaling, "Camera position, axes and matrices"),
// ---- Inside the game: routes a spike decides ------------------------------------------------------------
Session("nvapi.reflex.mode", Nvapi, Spike, Text, Latency, "Reflex: low-latency mode, boost, the frame-rate limit"),
Session("nvapi.reflex.sleep_status", Nvapi, Spike, Text, Latency, "What the driver's low-latency state is"),
SampledFamily("nvapi.reflex.frame_report", Nvapi, Spike, Microseconds, Latency, "Latency per frame: simulation, render submit, present, driver, OS queue, GPU render"),
Session("sl.dlss.optimal_settings", Streamline, Spike, Text, Upscaling, "The render size and sharpness DLSS recommends"),
Sampled("sl.dlss.vram_estimate", Streamline, Spike, Mebibytes, Upscaling, "DLSS's own estimate of its video memory"),
Session("sl.dlssg.options", Streamline, Spike, Text, FrameGeneration, "DLSS frame generation: mode, frames to generate"),
Session("sl.dlssg.state", Streamline, Spike, Text, FrameGeneration, "DLSS frame generation: status, the most frames it can generate"),
Sampled("sl.dlssg.frames_presented", Streamline, Spike, Count, FrameGeneration, "Frames DLSS frame generation presented, by its own count"),
Sampled("sl.dlssg.vram_estimate", Streamline, Spike, Mebibytes, FrameGeneration, "DLSS frame generation's estimate of its video memory"),
Session("sl.dlssd.options", Streamline, Spike, Text, Upscaling, "Ray reconstruction's options"),
Session("sl.nis.options", Streamline, Spike, Text, Upscaling, "NVIDIA Image Scaling's options"),
Session("sl.deepdvc.options", Streamline, Spike, Text, Upscaling, "RTX Dynamic Vibrance's options"),
Session("sl.reflex.state", Streamline, Spike, Table, Latency, "Reflex through Streamline: availability and its frame reports"),
Sampled("sl.pcl.markers", Streamline, Spike, Count, Latency, "PC-latency markers the game sets"),
// ---- Closed by a licence --------------------------------------------------------------------------------
Session("ngx.parameters", Ngx, Licence, Table, Upscaling, "NGX parameters: the quality value, the DLSS hints"),
Session("xess.options", Xess, Licence, Table, Upscaling, "XeSS's options"),
Sampled("sl.nvperf", Streamline, Licence, Table, Gpu, "Streamline's performance counters (NSight Perf SDK licence)"),
];
private static readonly FrozenDictionary<string, AdvancedMetric> _byId = All.ToFrozenDictionary(static m => m.Id, StringComparer.Ordinal);
/// <summary>The entry with this id, or null.</summary>
public static AdvancedMetric? Find(string id)
{
ArgumentNullException.ThrowIfNull(id);
return _byId.GetValueOrDefault(id);
}
/// <summary>The longest key <see cref="InstanceName"/> accepts.</summary>
public const int MaxInstanceKeyLength = 48;
/// <summary>
/// The series name of one member of a family: the family's <see cref="AdvancedMetric.SeriesName"/>, a dot, and a
/// key made of lower-case letters, digits and underscores that names the sensor on this PC.
/// </summary>
/// <exception cref="ArgumentException">The entry is not a family of series, or the key is not such a key.</exception>
public static string InstanceName(AdvancedMetric family, string key)
{
ArgumentNullException.ThrowIfNull(family);
ArgumentNullException.ThrowIfNull(key);
if (!family.IsFamily || family.SeriesName is not string stem)
{
throw new ArgumentException($"{family.Id} is not a family of series", nameof(family));
}
if (!IsInstanceKey(key))
{
throw new ArgumentException($"'{key}' is not an instance key: 1 to {MaxInstanceKeyLength} of a-z, 0-9 and _", nameof(key));
}
return stem + "." + key;
}
/// <summary>True for 1 to <see cref="MaxInstanceKeyLength"/> characters of <c>a-z</c>, <c>0-9</c> and <c>_</c>.</summary>
public static bool IsInstanceKey(string key)
{
ArgumentNullException.ThrowIfNull(key);
if (key.Length is 0 or > MaxInstanceKeyLength)
{
return false;
}
foreach (char c in key)
{
if (c is not ((>= 'a' and <= 'z') or (>= '0' and <= '9') or '_'))
{
return false;
}
}
return true;
}
private static AdvancedMetric Machine(string id, AdvancedSource source, AdvancedReach reach, AdvancedUnit unit, AdvancedGroup group, string summary)
=> new(id, AdvancedScope.MachineFact, source, reach, unit, group, summary);
private static AdvancedMetric MachineFamily(string id, AdvancedSource source, AdvancedReach reach, AdvancedUnit unit, AdvancedGroup group, string summary)
=> new(id, AdvancedScope.MachineFact, source, reach, unit, group, summary) { IsFamily = true };
private static AdvancedMetric Session(string id, AdvancedSource source, AdvancedReach reach, AdvancedUnit unit, AdvancedGroup group, string summary)
=> new(id, AdvancedScope.SessionFact, source, reach, unit, group, summary);
private static AdvancedMetric Sampled(string id, AdvancedSource source, AdvancedReach reach, AdvancedUnit unit, AdvancedGroup group, string summary)
=> new(id, AdvancedScope.Series, source, reach, unit, group, summary);
private static AdvancedMetric SampledFamily(string id, AdvancedSource source, AdvancedReach reach, AdvancedUnit unit, AdvancedGroup group, string summary)
=> new(id, AdvancedScope.Series, source, reach, unit, group, summary) { IsFamily = true };
}
@@ -0,0 +1,48 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>
/// Where an advanced metric can be read from — or why it is not read. The catalog names what is NOT read beside what
/// is, so the page can say so with the reason instead of leaving a gap (<c>docs/18_GPU_VENDOR_APIS.md</c> §Advanced
/// metrics; rule 7's "N/A, never a guess" applied to a whole source).
/// </summary>
public enum AdvancedReach
{
/// <summary>Not stated. No entry of the catalog carries it.</summary>
None = 0,
/// <summary>The Agent reads it in its own process, unelevated.</summary>
Agent = 1,
/// <summary>The Agent reads it only when it already runs as administrator and PawnIO is installed (D103).</summary>
AgentElevated = 2,
/// <summary>An argument of a call the Overlay already hooks; not read yet.</summary>
HookedCall = 3,
/// <summary>Needs a hook on a function its module exports; the hook is not built.</summary>
NewHook = 4,
/// <summary>A route nobody has proven safe: a spike decides, and the owner says go or no.</summary>
Spike = 5,
/// <summary>A source the project decided not to open (D103).</summary>
Refused = 6,
/// <summary>A source left for later, with no decision against it.</summary>
Deferred = 7,
/// <summary>It identifies a device, a person or another program. Never read (D104).</summary>
Identifier = 8,
/// <summary>It is the game's own state — where the player is, where the camera looks. Never read (CLAUDE.md rule 4).</summary>
PlayerState = 9,
/// <summary>The vendor's licence forbids vendoring and re-declaring what reading it needs.</summary>
Licence = 10,
/// <summary>The vendor's public headers do not declare it.</summary>
NotInHeaders = 11,
}
@@ -0,0 +1,26 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>
/// What an advanced metric belongs to (owner decision D101, <c>docs/18_GPU_VENDOR_APIS.md</c> §Advanced metrics): the
/// machine, or one game session. It decides where the value is stored and on which tab it is shown.
/// </summary>
public enum AdvancedScope
{
/// <summary>Not stated. No entry of the catalog carries it.</summary>
None = 0,
/// <summary>A fact about the PC that no session changes: stored once in <c>machine_profiles</c>, which a session points to.</summary>
MachineFact = 1,
/// <summary>A fact about one session — the game's display, the game's driver profile: <c>session_advanced.facts_json</c>.</summary>
SessionFact = 2,
/// <summary>
/// A value sampled over time. During a session it is stored with that session (<c>sensor_blobs</c>, under
/// <see cref="AdvancedMetric.SeriesName"/>); with no session it is shown while the page is open and stored nowhere.
/// </summary>
Series = 3,
}
@@ -0,0 +1,29 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>The vendor interface an advanced metric comes from. An entry's id starts with the source's prefix.</summary>
public enum AdvancedSource
{
/// <summary>Not stated. No entry of the catalog carries it.</summary>
None = 0,
/// <summary>NVAPI (MIT, NVIDIA only) — <c>nvapi.</c></summary>
Nvapi = 1,
/// <summary>LibreHardwareMonitorLib (MPL-2.0, every vendor; its CPU, board, memory and storage groups through PawnIO) — <c>lhm.</c></summary>
Lhm = 2,
/// <summary>NVIDIA Streamline (MIT headers), read inside the game only — <c>sl.</c></summary>
Streamline = 3,
/// <summary>AMD FidelityFX (MIT headers), read inside the game only — <c>ffx.</c></summary>
FidelityFx = 4,
/// <summary>NVIDIA NGX, whose SDK licence forbids vendoring and re-declaring — <c>ngx.</c></summary>
Ngx = 5,
/// <summary>Intel XeSS, whose SDK licence forbids the same — <c>xess.</c></summary>
Xess = 6,
}
@@ -0,0 +1,38 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>What an advanced metric's value is, so one formatter can print it.</summary>
public enum AdvancedUnit
{
/// <summary>Not stated. No entry of the catalog carries it.</summary>
None = 0,
/// <summary>Words — a name, a version, a list of flags.</summary>
Text = 1,
/// <summary>Several rows, each a name and a value — a driver profile, the memory modules.</summary>
Table = 2,
/// <summary>Yes or no.</summary>
Flag = 3,
/// <summary>A whole number with no unit.</summary>
Count = 4,
Celsius = 5,
Percent = 6,
Megahertz = 7,
Mebibytes = 8,
Watts = 9,
Volts = 10,
Amperes = 11,
Rpm = 12,
Microseconds = 13,
Milliseconds = 14,
Nits = 15,
FramesPerSecond = 16,
BytesPerSecond = 17,
Bits = 18,
}
@@ -0,0 +1,247 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Text.RegularExpressions;
using FluentAssertions;
using FrameLedger.Application.Advanced;
using FrameLedger.Application.Recording;
namespace FrameLedger.Application.Tests.Advanced;
/// <summary>
/// The catalog is the one list every consumer of "Advanced metrics" reads (D101), so what it may hold is held here:
/// ids that can go on disk, a scope and a reason on every entry, and the table in
/// <c>docs/18_GPU_VENDOR_APIS.md</c> §The inventory equal to it row for row.
/// </summary>
public sealed partial class AdvancedMetricCatalogTests
{
private static readonly IReadOnlyList<AdvancedMetric> _all = AdvancedMetricCatalog.All;
[Fact]
public void EveryIdIsUniqueLowerCaseDottedAndStartsWithItsSourcesPrefix()
{
_all.Select(static m => m.Id).Should().OnlyHaveUniqueItems();
foreach (AdvancedMetric m in _all)
{
IdShape().IsMatch(m.Id).Should().BeTrue("'{0}' goes on disk as a series name or a JSON key", m.Id);
m.Id.Should().StartWith(PrefixOf(m.Source), "an id says where its value comes from");
}
}
[Fact]
public void NoEntryLeavesAnEnumAtItsZeroOrItsSummaryEmpty()
{
foreach (AdvancedMetric m in _all)
{
m.Scope.Should().NotBe(AdvancedScope.None, m.Id);
m.Source.Should().NotBe(AdvancedSource.None, m.Id);
m.Reach.Should().NotBe(AdvancedReach.None, m.Id);
m.Unit.Should().NotBe(AdvancedUnit.None, m.Id);
m.Group.Should().NotBe(AdvancedGroup.None, m.Id);
m.Summary.Should().NotBeNullOrWhiteSpace(m.Id);
m.Summary.Should().NotContain("|", "{0}'s summary is a cell of a Markdown table", m.Id);
m.Summary.Should().NotEndWith(".", "{0}'s summary is a label, not a sentence", m.Id);
}
}
[Fact]
public void ASeriesIsNamedByThePrefixAndItsIdAndNothingElseHasASeriesName()
{
foreach (AdvancedMetric m in _all)
{
if (m.Scope == AdvancedScope.Series)
{
m.SeriesName.Should().Be("adv." + m.Id);
}
else
{
m.SeriesName.Should().BeNull(m.Id);
}
}
}
[Fact]
public void NoAdvancedSeriesCanBeTakenForAFixedOne()
{
// The fixed series store a missing tick as -1 and their readers drop every negative value; an advanced series
// may be negative (a -12 V rail) and stores NaN (D102). The prefix is how a reader tells which rule applies.
string[] fixedNames = [.. SensorSeriesCatalog.All.Select(static s => s.Name), "t_ms"];
fixedNames.Should().NotContain(static n => n.StartsWith(AdvancedMetric.SeriesPrefix, StringComparison.Ordinal));
_all.Where(static m => m.SeriesName is not null).Should().OnlyContain(static m => m.SeriesName!.StartsWith(AdvancedMetric.SeriesPrefix, StringComparison.Ordinal));
}
[Fact]
public void TheLabelKeyIsAnIdentifierTheResourceAccessorCanCarry()
{
foreach (AdvancedMetric m in _all)
{
LabelKeyShape().IsMatch(m.LabelKey).Should().BeTrue(m.LabelKey);
}
_all.Select(static m => m.LabelKey).Should().OnlyHaveUniqueItems("two ids that differ only by '.' and '_' would share a label");
}
[Fact]
public void OnlyWhatTheAgentReadsCountsAsRead()
{
_all.Where(static m => m.IsRead).Should().OnlyContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated);
_all.Where(static m => !m.IsRead).Should().NotContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated);
_all.Should().Contain(static m => m.IsRead);
_all.Should().Contain(static m => !m.IsRead);
}
[Fact]
public void TheElevatedReachIsLibreHardwareMonitorsAlone()
{
// D103: the administrator's rights buy the PawnIO groups and nothing else. NVAPI needs none, and nothing read
// inside a game is ever a matter of the Agent's rights.
_all.Where(static m => m.Reach == AdvancedReach.AgentElevated).Should().OnlyContain(static m => m.Source == AdvancedSource.Lhm);
_all.Where(static m => m.Reach == AdvancedReach.AgentElevated).Should().NotBeEmpty();
}
[Fact]
public void WhatIsReadInsideAGameIsNeverReadByThisBuild()
{
// Train A changes nothing in code loaded into a game: Streamline and FidelityFX entries are named, not read.
_all.Where(static m => m.Source is AdvancedSource.Streamline or AdvancedSource.FidelityFx or AdvancedSource.Ngx or AdvancedSource.Xess)
.Should().OnlyContain(static m => !m.IsRead);
}
[Theory]
[InlineData("nvapi.gpu.board_serial")]
[InlineData("nvapi.gpu.uuid")]
[InlineData("nvapi.display.edid")]
[InlineData("nvapi.encoder.session_processes")]
public void AnIdentifierIsNamedAndNeverRead(string id)
{
// D104. The entry exists so the page can say "never read, and why"; a reach that reads it would be the defect.
AdvancedMetric? m = AdvancedMetricCatalog.Find(id);
m.Should().NotBeNull();
m!.Reach.Should().Be(AdvancedReach.Identifier);
m.IsRead.Should().BeFalse();
}
[Fact]
public void TheCameraIsPlayerStateAndTheOnlyEntryOfThatReach()
{
// CLAUDE.md rule 4: where the camera is, is where the player is.
_all.Where(static m => m.Reach == AdvancedReach.PlayerState).Select(static m => m.Id).Should().Equal("sl.constants.camera");
}
[Fact]
public void FindReturnsTheEntryOrNull()
{
AdvancedMetricCatalog.Find("nvapi.gpu.vbios_version").Should().BeSameAs(_all.Single(static m => string.Equals(m.Id, "nvapi.gpu.vbios_version", StringComparison.Ordinal)));
AdvancedMetricCatalog.Find("nvapi.gpu.VBIOS_VERSION").Should().BeNull("ids are compared exactly");
AdvancedMetricCatalog.Find("no.such.metric").Should().BeNull();
FluentActions.Invoking(static () => AdvancedMetricCatalog.Find(null!)).Should().Throw<ArgumentNullException>();
}
[Fact]
public void AnInstanceOfAFamilyIsNamedByItsStemAndItsKey()
{
AdvancedMetric cores = AdvancedMetricCatalog.Find("lhm.cpu.temperature")!;
cores.IsFamily.Should().BeTrue();
AdvancedMetricCatalog.InstanceName(cores, "amdcpu_0_3").Should().Be("adv.lhm.cpu.temperature.amdcpu_0_3");
}
[Theory]
[InlineData("")]
[InlineData("Core 3")]
[InlineData("core.3")]
[InlineData("core-3")]
[InlineData("CORE3")]
public void AnInstanceKeyIsLowerCaseLettersDigitsAndUnderscores(string key)
{
AdvancedMetric cores = AdvancedMetricCatalog.Find("lhm.cpu.temperature")!;
AdvancedMetricCatalog.IsInstanceKey(key).Should().BeFalse();
FluentActions.Invoking(() => AdvancedMetricCatalog.InstanceName(cores, key)).Should().Throw<ArgumentException>();
}
[Fact]
public void AnInstanceKeyHasALongestLength()
{
AdvancedMetricCatalog.IsInstanceKey(new string('a', AdvancedMetricCatalog.MaxInstanceKeyLength)).Should().BeTrue();
AdvancedMetricCatalog.IsInstanceKey(new string('a', AdvancedMetricCatalog.MaxInstanceKeyLength + 1)).Should().BeFalse();
FluentActions.Invoking(static () => AdvancedMetricCatalog.IsInstanceKey(null!)).Should().Throw<ArgumentNullException>();
}
[Fact]
public void OnlyAFamilyOfSeriesHasInstances()
{
AdvancedMetric single = AdvancedMetricCatalog.Find("nvapi.pstate")!;
AdvancedMetric factFamily = AdvancedMetricCatalog.Find("nvapi.display.hdr_formats")!;
single.IsFamily.Should().BeFalse();
factFamily.IsFamily.Should().BeTrue();
FluentActions.Invoking(() => AdvancedMetricCatalog.InstanceName(single, "a")).Should().Throw<ArgumentException>();
FluentActions.Invoking(() => AdvancedMetricCatalog.InstanceName(factFamily, "a")).Should().Throw<ArgumentException>("a family of facts is stored as JSON, not as series");
FluentActions.Invoking(static () => AdvancedMetricCatalog.InstanceName(null!, "a")).Should().Throw<ArgumentNullException>();
FluentActions.Invoking(() => AdvancedMetricCatalog.InstanceName(single, null!)).Should().Throw<ArgumentNullException>();
}
[Fact]
public void TheInventoryTableOfDoc18IsTheCatalogRowForRow()
{
// The document is where a person reads what is read and what is not; the catalog is what the code does. A row
// on one side alone is a claim nobody checks - the defect this repository's documents keep being corrected for.
string doc = File.ReadAllText(Path.Combine(RepoRoot(), "docs", "18_GPU_VENDOR_APIS.md"));
int start = doc.IndexOf("### The inventory", StringComparison.Ordinal);
start.Should().BeGreaterThan(0, "docs/18_GPU_VENDOR_APIS.md has a section '### The inventory'");
int end = doc.IndexOf("\n## ", start, StringComparison.Ordinal);
string section = end < 0 ? doc[start..] : doc[start..end];
string[] documented = [.. InventoryRow().Matches(section).Select(static r => r.Value.Trim())];
string[] expected = [.. _all.Select(RowOf)];
// Row by row, so a failure names the one row that differs instead of printing both tables.
for (int i = 0; i < Math.Min(documented.Length, expected.Length); i++)
{
documented[i].Should().Be(expected[i], "row {0} of the inventory is the catalog's entry {0}", i);
}
documented.Should().HaveCount(expected.Length, "the table has a row for every entry of the catalog and no other");
}
/// <summary>The row of the inventory table an entry is documented by.</summary>
private static string RowOf(AdvancedMetric m)
=> $"| `{m.Id}` | {m.Summary} | {m.Scope}{(m.IsFamily ? ", one per device" : string.Empty)} | {m.Source} | {m.Reach} | {m.Unit} |";
private static string PrefixOf(AdvancedSource source) => source switch
{
AdvancedSource.Nvapi => "nvapi.",
AdvancedSource.Lhm => "lhm.",
AdvancedSource.Streamline => "sl.",
AdvancedSource.FidelityFx => "ffx.",
AdvancedSource.Ngx => "ngx.",
AdvancedSource.Xess => "xess.",
_ => throw new InvalidOperationException($"no prefix for {source}"),
};
private static string RepoRoot()
{
for (DirectoryInfo? dir = new(AppContext.BaseDirectory); dir is not null; dir = dir.Parent)
{
if (File.Exists(Path.Combine(dir.FullName, "FrameLedger.slnx")))
{
return dir.FullName;
}
}
throw new InvalidOperationException("the repository root (FrameLedger.slnx) is not above " + AppContext.BaseDirectory);
}
[GeneratedRegex(@"^[a-z][a-z0-9]*(\.[a-z][a-z0-9_]*)+$", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant, 1000)]
private static partial Regex IdShape();
[GeneratedRegex("^Adv_[a-z][a-z0-9_]*$", RegexOptions.CultureInvariant, 1000)]
private static partial Regex LabelKeyShape();
[GeneratedRegex(@"^\| `[a-z0-9_.]+` \|.*\|\s*$", RegexOptions.Multiline | RegexOptions.CultureInvariant, 1000)]
private static partial Regex InventoryRow();
}