feat(input): the Agent records what a session was played with - the switch, the terms, Privacy Policy 2.22 and Disclaimer 2.18 (D155, D156, D160, D161) (#468)

* feat(input): the arithmetic of controller statistics - classes, batteries, makers, one pad seen twice (D155-D163)

Nothing reads a device yet. Domain.Input says whether an XInput state or a DualSense report is a pad in use and what
its battery is, adds a battery's readings up, counts switches and decides when two entries are one pad;
Application.Input holds one session's slices and turns them into a reading a second; InputSessionBuilder turns a
session's readings into its totals, its controllers as JSON and its timeline. TelemetrySample can carry a reading.

Every byte and reading under test was written by hand: no report from a real controller has passed through this code.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(input): a session can store what it was played with - schema 0024, the .partial file's chunk 11, both tiers (D160)

Nine columns on sessions (the time in front and its four classes, the switches of method, the sources that answered,
the controllers as JSON) and three on games (what a store lists of controller support), ADD COLUMN only. The .partial
file gains chunk 11, so a session recovered after the Agent died keeps its readings. SessionFinalizer.Build stores
them before the tier branch: hooked, unhooked and recovered sessions alike. The input series are sensor_blobs rows
named input.*, which the sensors' read now leaves out and FindInputSensorsAsync returns.

Nothing produces a reading yet. A ledger this build has opened cannot be opened by 0.1.0-beta.49 or earlier.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(input): the input reader, which the Agent does not start yet - raw input for controllers, XInput, the time of the last input (D155, D158, D159)

Application.Input.InputReader takes a slice about ten times a second from Infrastructure.Input.Win32InputBackend, on
the thread of InputDeviceHub, which exists only while a session has a view of it. It opens no device, sends nothing
to one and registers for no keyboard or mouse. tools/input-readonly-check.ps1 holds its Windows calls to a list.

With no controller at hand, what the reader does with one connected is not established.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(input): an arm of XInputPad.Battery's switch said what the default says (Qodana, on #464 after it merged)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* test(input): no using that makes the file's own qualified names redundant (InspectCode)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* test(input): what InspectCode reported in the reader's tests - redundant casts, a hub disposed twice, a suppression not needed

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* wip(input): the Agent records what a session was played with - the switch, the terms, the legal texts

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* style(input): import order in the Agent's composition; no redundant qualifier in a test (InspectCode)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

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-14 21:53:04 +00:00
1 parent e3dab94834
commit a6bebc4adf
41 files changed
+732 -58

No files matched your search

+14
View File
@@ -37,6 +37,20 @@ numeric core and does not move; the heading is the full version — corrected 20
### Added
- **A session records what it was played with — a controller, the keyboard and mouse, both, or neither** (D155–D163,
the owner's decisions of 2026-11-14; *Settings ▸ Controllers and input*, on unless you switch it off). While a game
is recorded, FrameLedger's agent notes — from Windows, never from the game — which game controllers are connected
and in use, their battery level, and whether the keyboard or mouse is in use, and the session stores how the time
the game was in front divides between them, how often each controller connected and dropped, and its battery. It
works for a game FrameLedger does not measure too. **No button, stick, key or text is kept; nothing is sent to a
controller; and nothing is read until you have accepted the Privacy Policy that describes it** — after this
update, sessions recorded before FrameLedger has been opened once have no such figures. The screens that show the
figures come with the same release. Xbox-compatible controllers and the DualSense are read for use; another
controller is listed and never counted as in use. **None of this had been read from a real controller when it was
written** — it was checked against data written by hand (`LIMITATIONS.md` §Controllers and input).
- **The terms are shown once: Privacy Policy 2.22 and Disclaimer 2.18.** Both said FrameLedger never reads input.
They now say what is read — that a controller, or the keyboard or mouse, is in use — what is kept, and what never
is (`docs/legal-drift-history.md`).
- **For developers: the arithmetic of controller statistics, with nothing reading a device yet** (D155–D163, the
owner's decisions of 2026-11-14; `docs/21_INPUT_DEVICES.md`, `docs/03_METRICS.md` §Input). `FrameLedger.Domain.Input`
says whether an XInput state or a DualSense report is a pad in use and what its battery is, adds a battery's readings
+23 -1
View File
@@ -6,7 +6,7 @@ Read this file first, then the reading order at the bottom. **`docs/19_SAFETY_AN
## Architecture in one paragraph
A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly enabled. It hooks the presentation path (DXGI for D3D11/D3D12, plus OpenGL) and the upscaler/RT APIs, writes fixed-size frame records into a lock-free shared-memory ring, and never blocks. A C# Agent drains that ring at ~10 Hz, enriches with GPU telemetry from vendor APIs, and writes sessions to SQLite. A WPF UI reads SQLite. Vulkan uses an implicit **layer** instead of hooking. If injection is refused or fails there is **no measurement**: the session records duration, hardware telemetry and the reason, and every measured field reads `N/A` (Tier 2, owner decision 2026-08-28).
A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly enabled. It hooks the presentation path (DXGI for D3D11/D3D12, plus OpenGL) and the upscaler/RT APIs, writes fixed-size frame records into a lock-free shared-memory ring, and never blocks. A C# Agent drains that ring at ~10 Hz, enriches with GPU telemetry from vendor APIs, and writes sessions to SQLite. A WPF UI reads SQLite. Vulkan uses an implicit **layer** instead of hooking. If injection is refused or fails there is **no measurement**: the session records duration, hardware telemetry and the reason, and every measured field reads `N/A` (Tier 2, owner decision 2026-08-28) — **and, since owner decision D161 (2026-11-14), what the Agent reads from outside the game**: the game process's memory (beta.12, D43) and which controllers, or the keyboard and mouse, the session was played with (`docs/21_INPUT_DEVICES.md`). Nothing measured inside the game is among them.
## Non-negotiable rules
@@ -147,6 +147,28 @@ src/
# (LATENCY_FRAMES, a batch per state of the sleep status; nothing published or
# stored); its watchdog's periodic tick is on a grid (fl_watchdog_tick.h), and
# Recording/PendingInGameReadings keeps the reading that waits for a sample.
# Controllers and input (0.1.0-beta.50, owner decisions D155-D163, docs/21_INPUT_DEVICES):
# Input/ - InputReader (a slice ten times a second over the port IInputBackend),
# InputTickAccumulator (one session's slices into a reading a tick), InputTerms (the
# reading waits for Privacy Policy 2.22, D156), the ports IInputDevices /
# IInputActivitySource; Recording/InputSessionBuilder (totals, the controllers as JSON,
# the input.* series; schema 0024). Domain/Input holds the arithmetic and the two
# parsers (an XInput state, a DualSense report). Infrastructure/Input is the Windows
# side: Win32InputBackend (raw input for joysticks and gamepads, three XInput getters,
# GetLastInputInfo - it opens no device and sends nothing to one) and InputDeviceHub
# (one thread for the Agent, only while a session has a view). Read from OUTSIDE the
# game, both tiers; `capture.input_devices`, on by default.
# Controllers and input (0.1.0-beta.50, owner decisions D155-D163, docs/21_INPUT_DEVICES):
# Input/ - InputReader (a slice ten times a second over the port IInputBackend),
# InputTickAccumulator (one session's slices into a reading a tick), InputTerms (the
# reading waits for Privacy Policy 2.22, D156), the ports IInputDevices /
# IInputActivitySource; Recording/InputSessionBuilder (totals, the controllers as JSON,
# the input.* series; schema 0024). Domain/Input holds the arithmetic and the two
# parsers (an XInput state, a DualSense report). Infrastructure/Input is the Windows
# side: Win32InputBackend (raw input for joysticks and gamepads, three XInput getters,
# GetLastInputInfo - it opens no device and sends nothing to one) and InputDeviceHub
# (one thread for the Agent, only while a session has a view). Read from OUTSIDE the
# game, both tiers; `capture.input_devices`, on by default.
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
+31 -1
View File
@@ -36,7 +36,8 @@ page lists them in plain words; each item links to the document that has the det
When a game is not measured — any of the reasons above — its session still records **how long it ran, the
machine's sensors (GPU temperature, load, power; CPU load; memory), how much memory the game itself used (read from
Windows, outside the game) and why nothing was measured.** Every
Windows, outside the game), what it was played with ([Controllers and input](#controllers-and-input)) and why nothing
was measured.** Every
frame-rate, upscaler, frame-generation and ray-tracing value reads **N/A**, never 0. How the game's window was
shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
@@ -149,6 +150,35 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
N/A for video memory. AMD and Intel graphics cards have not been tested.
([Metrics](docs/03_METRICS.md))
## Controllers and input
Since 0.1.0-beta.50 a session records what it was played with. All of it is read from Windows, from outside the
game — so it is there for a game FrameLedger does not measure as well.
- **It says a controller was in use while the game was in front — not what the game did with it.** A controller
held while a game ignores it reads as a controller in use.
- **Keyboard and mouse are one figure.** FrameLedger reads only the time of the last keyboard or mouse input; it
cannot tell the two apart, and never reads a key.
- **Input a program makes counts as keyboard and mouse**: Steam Input mapping a controller to keys, a macro tool, a
remapper. A controller mapped that way reads as *both*.
- **Only the time the game is in front counts.** A game whose window belongs to another process than the one
FrameLedger follows reads as never in front, and has no shares.
- **Xbox-compatible controllers and the DualSense are read for use.** Any other controller — a DualShock 4, a
Switch Pro controller — is listed with its connections and disconnections and is never counted as in use.
- **A controller that Windows presents as an Xbox pad is "Xbox"**, whoever made it. Its model is named only when it
cannot be mistaken for another one that is connected.
- **Battery.** An Xbox controller on a cable reads "wired"; on Bluetooth it may report nothing. A DualSense on
Bluetooth reports its battery only where Steam or the game has switched it to its long report — FrameLedger never
asks a controller for anything. An Xbox controller's level is four words, a DualSense's is in steps of ten per
cent.
- **Steam Input shows a controller twice** — the one you hold and an Xbox pad Steam presents for it. FrameLedger
folds the two into one when they move together; with another remapper it may list two.
- **Nothing is read until you have accepted the Privacy Policy that describes it.** After an update, sessions
recorded before FrameLedger has been opened once have no such figures, and say so in their notes.
- **None of this had been read from a real controller when 0.1.0-beta.50 was written.** It was checked against data
written by hand; what real controllers do is in the developer's notes once the owner has tried them.
([Input devices](docs/21_INPUT_DEVICES.md))
## Display mode (full-screen, borderless, windowed)
- **Exclusive full-screen is known only for a measured Direct3D (DXGI) game** — the game's own swap chain
+11 -1
View File
@@ -107,6 +107,16 @@ app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and
> temperature in every session, and, on NVIDIA cards only, how much of the time its power limit or its temperature held
> it back, read once a second; and frames per watt — the game's own frames per second for each watt the graphics card
> drew, never counting generated frames, `N/A` where the game's own frame rate is not known.
> - **Controllers and input (since beta.50; on unless you switch it off in Settings, and only once you have accepted
> the Privacy Policy that describes it):** how much of the time a game was in front it was played with a
> controller, with the keyboard or mouse, with both or with neither; each controller's connections and drops; its
> battery. All of it is read from Windows, from outside the game: it says a controller was in use while the game
> was in front, not what the game did with it. Keyboard and mouse are one figure — only the time of the last input
> is read — and input a program injects (Steam Input mapping a controller to keys, a macro tool) counts as keyboard
> and mouse. An Xbox-compatible controller and a DualSense are read for use; another maker's controller is listed
> and never counted as in use. A DualSense on Bluetooth reports its battery only where Steam or the game has
> switched it to its long report, and an Xbox controller on Bluetooth may report none. **None of this had been
> read from a real controller when it was written (2026-11-14)**: it was checked against data written by hand.
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
@@ -188,7 +198,7 @@ FrameLedger is built to keep that risk small and to be honest about it:
| **Off by default** | Injection is disabled for every game until you enable it individually, after a consent prompt |
| **Hard refusal** | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or stops capturing at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. For Direct3D/OpenGL that means hooks are removed; for Vulkan it means the layer goes passthrough, because a layer cannot leave the loader chain of a running game. **There is no override — not in settings, not in a config file, not on the command line**<br><br>**One narrow exception since beta.9 (owner decisions D33, D38):** per game, after its own disclosure and only while a Settings option (off by default) is on, a game whose only finding is one anti-cheat that runs entirely in user mode — no driver file in its folder, on no title list — may be hooked under a user-mode exception. ~~and that FrameLedger has measured successfully at least twice~~ *(corrected 2026-10-03: since beta.11, D38, a grant needs no earlier session; its first two hooked sessions are a trial, and one that does not go well ends it for good.)* The guard still runs every check under it, refuses anything else it finds, and ends it on anything new; a ban remains possible (`legal/DISCLAIMER.md` §2A).<br><br>✅ **Both halves run since 2026-09-10.** The *pre-injection* refusal runs every documented check, and during every capture the Agent re-runs them every 30 s: the component inside the game removes its hooks within one frame of being told to, and within 65 s if it stops hearing from the scanner. *(Until 2026-09-15 this cell said the in-session re-scan did not run at all, which stopped being true when the Agent's capture loop landed.)* For a Vulkan title the stop is the layer's own: it checks the scanner's counter on every present and goes passthrough within one present of the stop flag, or after 65 s without a scan — a title that has stopped presenting is not stopped by that deadline, and presents nothing to be observed either. |
| **No evasion, ever** | FrameLedger does not hide, rename, obfuscate, or disguise itself. It keeps its real name, real exports, and version info. It is meant to be plainly visible to any security software that looks. This is an architectural rule, not a setting |
| **Read-only** | It never reads or writes game memory, never modifies game behavior, never touches saves or input, and never changes GPU clocks, fans, or power limits |
| **Read-only** | It never reads or writes game memory, never modifies game behavior, never touches saves, never reads what you type or which buttons you press — from outside the game it notes only whether a controller, or the keyboard or mouse, is in use — and never changes GPU clocks, fans, or power limits |
| **Always a way out** | FrameLedger refuses rather than pushes through. When the guard finds anti-cheat, or the hook fails, or you have not enabled a game, it **stops** — and records the session anyway: start, end, duration, whatever hardware sensors your machine provides, and the reason there is nothing else. Every measured value reads `N/A`; it never estimates one.<br><br>**The way out is that it does not inject, not that it measures another way.** An earlier version of this row promised a no-injection measurement mode. It was designed around Intel PresentMon, that was dropped on 2026-08-27 after measurement, and no replacement was chosen — so **frame times require hooking**. Said in this row rather than a footnote because the row is in the SAFETY table, and a reader deciding whether to enable a game needs the real alternative, not a comfortable one |
**FrameLedger is for offline and single-player games.** If you enable it for anything with an online or competitive component, that is your call and your responsibility. The developer cannot reverse a ban. Please read [`legal/DISCLAIMER.md`](legal/DISCLAIMER.md) and [`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) before enabling it for anything.
+20
View File
@@ -102,6 +102,26 @@ Tray icon states (idle / capturing T1 / capturing T2 / paused); menu; toasts for
### FR-15 In-game overlay *(v1.1, opt-in, off by default)*
Draw live FPS/frametime/upscaler info inside the game. Only for games already hooked; a separate toggle; never on by default. Deferred until the data path is stable (`15_ROADMAP` P5).
### FR-16 Controllers and input *(owner decisions D155–D163, 2026-11-14)*
What a session was played with, read by the Agent from outside the game — so for hooked and unhooked sessions alike (`21_INPUT_DEVICES`, `03_METRICS` §Input).
- FR-16.1 The share of the time the game was in front that it was played with a controller, with the keyboard or mouse (one class), with both, with neither; the number of switches between a controller and the keyboard and mouse.
- FR-16.2 Each controller: its maker and model by its USB ids, how it is connected, its connections and disconnections during the session, the time it was in use.
- FR-16.3 Each controller's battery: the time at each level, the level that lasted longest, the first and the last, a rate where one can be worked out.
- FR-16.4 Each maker's share of the time controllers were in use, and the number of switches between makers. A pad that is one controller seen twice (Steam Input) counts once.
- FR-16.5 Whether a game supports controllers, as evidence and never a verdict: what the store's own file on the disk says, which input libraries the game loaded, how it was played (D163).
- FR-16.6 An option, **on unless switched off**, that reads nothing until the Privacy Policy describing it has been accepted on the PC (D156). Off means nothing is read or stored.
- FR-16.7 Never read or stored: which button, stick, trigger or key; text; the mouse's position; a serial number, a Bluetooth address, a device path. Nothing is ever sent to a controller (D159). Held by `tools/input-readonly-check.ps1`.
### FR-16 Controllers and input *(owner decisions D155–D163, 2026-11-14)*
What a session was played with, read by the Agent from outside the game — so for hooked and unhooked sessions alike (`21_INPUT_DEVICES`, `03_METRICS` §Input).
- FR-16.1 The share of the time the game was in front that it was played with a controller, with the keyboard or mouse (one class), with both, with neither; the number of switches between a controller and the keyboard and mouse.
- FR-16.2 Each controller: its maker and model by its USB ids, how it is connected, its connections and disconnections during the session, the time it was in use.
- FR-16.3 Each controller's battery: the time at each level, the level that lasted longest, the first and the last, a rate where one can be worked out.
- FR-16.4 Each maker's share of the time controllers were in use, and the number of switches between makers. A pad that is one controller seen twice (Steam Input) counts once.
- FR-16.5 Whether a game supports controllers, as evidence and never a verdict: what the store's own file on the disk says, which input libraries the game loaded, how it was played (D163).
- FR-16.6 An option, **on unless switched off**, that reads nothing until the Privacy Policy describing it has been accepted on the PC (D156). Off means nothing is read or stored.
- FR-16.7 Never read or stored: which button, stick, trigger or key; text; the mouse's position; a serial number, a Bluetooth address, a device path. Nothing is ever sent to a controller (D159). Held by `tools/input-readonly-check.ps1`.
## Non-functional requirements
- **NFR-1 Game-side overhead:** ≤ 1 µs per present, ≤ 8 MB resident, measured game FPS impact ≤ 0.5% vs uninstrumented.
+2 -1
View File
@@ -350,6 +350,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
|---|---|---|---|
| **Session loop** (`CaptureSession.RunAsync`, one async loop per session) | `Task.Delay(100 ms)` drain ticks; the 30 s guard scan is awaited inline | The ring reader, for the life of the session — drain, `PublishGuardResult`, `SetPaused`, `RequestLogFlush` — and the record buffer it fills | Samples foreground and the display mode per tick (beta.10), drains the telemetry queue per tick (PR-D), writes `.partial` itself (PR-D) |
| **Telemetry** (`fl-telemetry`, `TelemetryPoller`, one per session) | 1 Hz, never faster than 500 ms | Its own `ConcurrentQueue` of `TelemetrySample` | Reads the composite source only; L2 has a thread of its own inside the library, and the composite is read from this thread and no other |
| **Input** (`fl-input`, `InputDeviceHub`, **one for the Agent**, since 0.1.0-beta.50) | A slice every 100 ms, only while a session has a view of it — with none there is no thread, no window, no registration | The message-only window raw input is delivered to, and the registration for joysticks and gamepads; the reader's device table | Raw input's buffer, three XInput getters, `GetLastInputInfo`, the window in front. Hands each slice to every session's view under one lock; the telemetry thread takes a view's sum once a tick. Opens no device, sends nothing to one (`21_INPUT_DEVICES`) |
| **Watcher** (built 2026-09-10, PR-F: `CaptureOrchestrator.RunAsync` on a `PeriodicTimer(1 s)`) | 1 Hz process snapshot | The watcher's events and the running-session table — ~~`PollOnceAsync` is their only writer; there is no `Channel`, because there is no second consumer~~ **since 2026-09-13 (P3 PR-1b) the table has one lock**: `PollOnceAsync` on the timer, `LaunchAsync` and `StopSession` from the pipe's tasks (HANDOFF §P3 D12 as built — two commands do not justify a channel); the sessions themselves never take it | The `games` rows (one read per poll) and never the ring; each session it starts runs on its own task |
| **Finalize** (PR-D) | Once, on the session loop's task | The one SQLite connection, behind a `SemaphoreSlim(1)` | `ApplicationStopping` cancels the loop; finalize gets a grace window, then the `.partial` stays for recovery |
| **Pipe** (built 2026-09-13, P3 PR-1: `PipeServer.RunAsync` accepting, one reader and one writer task per client) | Per frame | Each client's bounded outbound queue (drop-oldest, so a publisher never waits) and the answer to each request | `Hello` / `GetStatus` / `Ping` read `AgentStatus`, an immutable snapshot the publisher swaps whole; **never the ring, never the recorder**. The events themselves are handed over ON the session loop's task by `SessionEventPublisher` (`ISessionObserver`, called after the recorder's own work each tick) — the loop enqueues a frame and returns |
@@ -372,7 +373,7 @@ the pipe's tasks touches the ring or the recorder, and the session loop never wa
## Telemetry poller
1 Hz (the session's `telemetry.interval_ms`, 500–2000 ms) on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) ~~+ optional CPU sample when the Agent is elevated and PawnIO is present~~ + *(corrected 2026-10-04)* the machine's reading on the same tick — CPU load and memory in use without elevation, CPU temperature only when elevated with PawnIO — and the game process's memory (beta.12, D43). Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
1 Hz (the session's `telemetry.interval_ms`, 500–2000 ms) on its own thread: `CompositeTelemetrySource.TryRead` (`18_GPU_VENDOR_APIS` — DXGI/PDH baseline, LibreHardwareMonitor sensors, NVAPI extras on NVIDIA) ~~+ optional CPU sample when the Agent is elevated and PawnIO is present~~ + *(corrected 2026-10-04)* the machine's reading on the same tick — CPU load and memory in use without elevation, CPU temperature only when elevated with PawnIO — and the game process's memory (beta.12, D43). **Since 0.1.0-beta.50 (D155, D156) also what the session was played with**: when the option `capture.input_devices` is on and its terms are accepted, the poller opens a view of the Agent's input reader at its start, tells it which processes are the session's game (`Follow`), and attaches to each sample what that view saw since the tick before — `TelemetrySample.Input` (`21_INPUT_DEVICES` §The reader). A tick only the input view answered is still a sample. Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
## Session recorder — state machine
+2
View File
@@ -491,6 +491,8 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `capture.run_elevated` | bool | `0` | | The App when it starts the Agent, and an Agent the logon task started — both BEFORE the Agent exists, through `Infrastructure.Startup.RunElevatedSetting` (one row, `PRAGMA query_only`, no version gate, anything but `1` is off) (D34, beta.10): on, Windows is asked for administrator rights at every Agent start (`01_ARCHITECTURE` ADR-9) |
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
| `telemetry.interval_ms` | int | `1000` | 500–2000 | Agent, per session (FR-3.5) |
| `capture.input_devices` | bool | `1` | | Agent, per session (FR-16, owner decisions D155 and D156, 2026-11-14): **Controllers and input**. On — and only once the Privacy Policy that describes the reading (2.22 or later) is in `legal_acceptance` (`Application.Input.InputTerms`) — a session has a view of the Agent's input reader and stores what it was played with (schema 0024); off, or before that acceptance, nothing of it is read or stored, and a session held back by the terms says so in its notes. Any row that is not exactly `0` is on. Settings ▸ Recording (`21_INPUT_DEVICES`) |
| `capture.input_devices` | bool | `1` | | Agent, per session (FR-16, owner decisions D155 and D156, 2026-11-14): **Controllers and input**. On — and only once the Privacy Policy that describes the reading (2.22 or later) is in `legal_acceptance` (`Application.Input.InputTerms`) — a session has a view of the Agent's input reader and stores what it was played with (schema 0024); off, or before that acceptance, nothing of it is read or stored, and a session held back by the terms says so in its notes. Any row that is not exactly `0` is on. Settings ▸ Recording (`21_INPUT_DEVICES`) |
| `telemetry.advanced` | bool | `0` | | Agent, per session (FR-5.6, owner decision D101, 2026-11-11): **Advanced metrics**. On, a session holds the Agent's shared reader and stores its `adv.*` series and its `session_advanced` row (schema 0023); off — and any row that is not exactly `1` — nothing more is read or stored, and a session recorded while off has no row. Settings ▸ Recording (`18_GPU_VENDOR_APIS` §The switch) |
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
| `retention.remove_uninstalled_games` | bool | `1` | | Agent, at every detection sweep (beta.19, D55, FR-1.8): on, an entry whose executable has been gone for ten minutes — its drive connected, the folder it was installed in still there — and that has no session and no anti-cheat block or exception is removed; off, it stays and reads *Not installed* (D41's behaviour) |
+20
View File
@@ -1265,6 +1265,26 @@ outlives a rules change, a game update and *Change executable*; §What a finding
> the user. Cautious mode returns with the overlay, when there is something
> for it to switch off.
## What the Agent reads about input, from outside every game (owner decisions D155–D159)
Since 0.1.0-beta.50 the Agent can say what a session was played with (`21_INPUT_DEVICES`). It is on this page
because of what it must never become:
- **It is read from Windows, by the Agent. Nothing is added to a game**: no hook, no injected code, nothing in
`17_HOOK_ENGINE` §Hook inventory. Rule 4 is untouched, and a game the guard refuses is read like any other —
nothing about it touches the game's process.
- **No hook of any kind.** `SetWindowsHookEx` stays forbidden everywhere (`tools/chokepoint-check.ps1`); keyboard
and mouse are known by one call that returns a time (`GetLastInputInfo`), and raw input is registered for
joysticks and gamepads only — never for a keyboard or a mouse. A tool that hooks or registers for the keyboard is
what security software, and some anti-cheat, look for; this is not one.
- **No device is opened and nothing is sent to one.** A handle of FrameLedger's on a controller could make a game's
own exclusive open fail; an output or feature report could change how a controller reports to the game. Neither
is done.
- **A committed list holds it**: `tools/input-readonly-check.ps1` (`12_BUILD` step 14g).
Whether any anti-cheat objects to a background program that receives controllers' reports is not known; none is
documented to. It reads nothing of, and does nothing to, the game.
## Honest limits to document to users
The Disclaimer states these explicitly, and the UI consent dialog echoes them:
+1
View File
@@ -1874,6 +1874,7 @@ Moved verbatim, in this order.
| 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. **Two of the four answered 2026-11-11, before the option exists.** (1) **Storage: not opened, by the first outcome.** LibreHardwareMonitor 0.9.6's `StorageGroup` lists every drive through DiskInfoToolkit's `ReloadStorages` with no filter by bus and follows drives plugged in later — it cannot be opened without touching removable drives. `lhm.storage.*` reads `Deferred`, and `LhmGroups` has no member for it. (2) **Cost, unelevated, measured with `probe-advanced`** on the dev box: one refresh of the graphics-card group alone is 14 ms of processor time (62 ms elapsed) — 1.4% of one core at one a second, above NFR-2 — and one NVAPI read 0.4 ms. By the third outcome the sensor library is read every fifth tick (0.28%). **Still open, and the owner's**: the same probe as administrator with PawnIO — whether the processor, memory and motherboard groups open on this board, what they cost, and `PrivilegeFootprintTests`' new case on a token that holds the privileges (CI's does; the dev box's unelevated run passes by construction). **The first run was taken on 2026-11-12, by the owner, in ordinary use** (0.1.0-beta.40, the Agent as administrator with PawnIO, an i7-14700KF on a board with an IT8689E chip, an RTX 5080), and read here from a copy of the ledger and the Agent's log, not from a probe. **The groups open and read**: nine of ten sessions stored 119 processor series (a clock and a load per thread, temperatures, powers, voltages), 14 memory series and 21 motherboard series (six fans, six temperatures, nine voltages) beside the card's 41 — 195 from the sensor library in all. **No value was compared with another tool**; that is still the owner's. **Two faults, one cause** (`Infrastructure.Telemetry.LhmLibrary`): the Agent held up to three `Computer`s at once, and the library keeps the driver it reads the processor through and its bus mutexes per process — closing one `Computer` let go of them under the others. After seven sessions the Advanced reader's processor device threw `NullReferenceException` twice and was left alone (the page lost the processor until the reader reopened); once a session's start met another instance's close, the reader's `Open` threw `ObjectDisposedException`, and that session stored 17 series instead of 212. **Fixed 2026-11-12**: opens and closes are serialised and a `Computer` is parked, not closed, while another is in use. The cause is read from the log's timing and was not reproduced — it needs this elevation — so **whether the faults are gone is the owner's next sessions to show**: no `advanced: a device is left alone` and no `did not open` in the Agent's log. **First evidence, 2026-11-12, 0.1.0-beta.41, the same PC:** seven sessions between 06:38 and 07:01 with no `advanced:` line at all, each with the option on storing 212 or 213 series; on beta.40 that morning the processor device faulted out after each of six sessions (04:34–05:07) — thirteen of sixteen over the night. The reader failing to open was seen once in sixteen, so this is not yet enough to call that one gone. Still open: any value beside another tool. |
| M16 ✅ | **The L2 telemetry layer's cost — the first number, and it is above NFR-2 (found 2026-11-11, measuring something else).** `LhmTelemetrySource` refreshes LibreHardwareMonitor's graphics-card group once a second in every recorded session. `probe-advanced` measured that refresh, through the same library and the same group, at **14 ms of processor time** on the dev box (RTX 5080, 41 mapped sensors, about twenty of them the Direct3D engine nodes the library enumerates per card) — 1.4% of one core, where NFR-2 allows the whole Agent 1% during capture and `14_TESTING` §Hook overhead's Agent figure has never been measured. This is a measurement of the call, not yet of a session: L2's own poller was not instrumented. | **Measure L2 in a session** (the Agent's processor time over a ten-minute capture, telemetry at 1000 ms and at 2000 ms). Pre-committed: at or under 1% → this row closes with the number; above → the owner chooses between a slower default for `telemetry.interval_ms`, reading the sensors the layer keeps from NVAPI on NVIDIA cards (L3 already has most, at 0.4 ms), or amending NFR-2 to what is measured. Not decided here, and nothing about L2 changes in the Advanced-metrics train. **Measured in a real Agent, 2026-11-11 (owner decision D110), and answered (D117).** `tools/agent-cost.ps1` runs the shipped `FrameLedger.Agent.exe --console capture` against a copy of hook-harness in a scratch data folder — a session that is not hooked, so the telemetry poller runs as in every session and nothing drains frames — and reads the Agent process's own processor time at exit; the cost per second is the slope between a 45 s and a 165 s session, two runs of each. Dev box (RTX 5080, not elevated, layers `l1+lhm+nvapi`): **19.3 ms of processor time per second of session = 1.93 % of one core with Advanced metrics off** (2,312 and 2,312 ms over 45 s; 4,594 and 4,656 ms over 165 s), **20.4 ms = 2.04 % with it on** (2,984 and 3,000; 5,547 and 5,344); peak working set 113 MiB and 119 MiB. A first pass with 30 s and 90 s sessions gave 1.56 % and 2.21 % — its two short runs differed by 670 ms, which is why the lengths were raised. So the probe's number holds in a session: the Agent's steady cost is about twice NFR-2's 1 %, nearly all of it the layer every session has always used, and the new option adds about a tenth of a percent. **The owner's answer: NFR-2 is amended to ≤ 2.5 % of one core** — the limit had never been measured, the sensors keep their one reading a second, and nothing in the code changes. Not measured: a hooked session (the drain's cost on top), a session with the Agent elevated and PawnIO's groups open, another PC. |
| 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. **2026-11-12 — the reading that comes before that spike is `spike-notes` §30** (owner decision D130: a document first, beside 0.1.0-beta.45; nothing was run). It finds: a hook on NVAPI's latency functions is the refused class, and a hook on Streamline's Reflex and PCL functions is train D's wrapper (§M15) — and would miss a game that fetched them before the attach, as `slInit` is missed (D129); the Overlay calling `slReflexGetState` itself breaks the thread contract the vendor's header states; **what remains is the route named in this row**, the Overlay calling two driver getters with the game's device, and a no-injection ETW route that gives the game-side markers only and makes the game post messages to its own window. Corrected there: `nvapi64.dll` exports **two** functions on the dev box (`nvapi_Direct_GetMethod` beside `nvapi_QueryInterface`), not one. The go or no is the owner's, and a go needs the owner's ruling that calling a driver getter with the game's device is inside rule 4. **2026-11-13 — the owner answered (D132, D133).** Route D goes to the spike this row names, on `hook-harness` and a stub `nvapi64.dll`, with the ruling: a driver's read-only getter called with the device of the swap chain the Overlay hooks is inside rule 4 (`CLAUDE.md`, the rule's note of that day). No real game before the owner has seen the result, and nothing shipped changes for the spike (`spike-notes` §31, written after 0.1.0-beta.46). Route C is **refused**; the ETW route **stays closed**, and §G is not reopened. **2026-11-13 — the harness spike is done (`spike-notes` §31), and none of its stop conditions fired.** With a stand-in module: nothing is called or loaded when `nvapi64.dll` is absent, a missing getter is refused whole, an error and a report of nothing read as what they are, and a call the driver holds for seconds stops only the thread that made it — so not the watchdog. With the installed driver (32.0.16.2114, RTX 5080), in the probe's own process and with the probe setting the markers a game would: no fault before `NvAPI_Initialize`, without markers, or across 38 million reads beside a marker-setting thread; a call costs half a microsecond to a microsecond and a half; the report is readable from markers alone, in microseconds; and the Direct3D 12 **device** — the object the Overlay already holds — is what the driver takes. What only a game can say is unanswered: a game's own device, a real report, another driver. **The owner's next word is go or no for one real title**; a go is a plan of its own first. **2026-11-13, the same evening — go (D136)**: a plan for one title, Cyberpunk 2077; no code before the plan is approved, and no release carrying it before a stop while a game runs has been exercised on 0.1.0-beta.46 (owner-only item 44 (d)). **2026-11-13, the plan and four more answers (D138–D141).** The read has **no switch of its own**: it is part of Advanced metrics, so after the release it reaches every Direct3D 12 game that loaded the driver's `nvapi64.dll`, for everyone who switched Advanced metrics on — "one title" is the order of the owner's first runs, not a limit in code (D138). The probe ran a leg with a sleep mode first (D139; `spike-notes` §31, *The leg with a sleep*): **the getters do not wait behind `NvAPI_D3D_Sleep`** — thirty-one million reads beside a thread that slept 97 % of the time, none of a millisecond; a read after a sleeping frame costs about 2.6 µs. An `nvapi64.dll` loaded from the game's own folder is refused with the reason (D140). One call of 2 ms or more switches the read off until the game exits (D141). The plan's design, as reviewed against the source, is in [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md) §The train after 0.1.0-beta.46. **2026-11-13, night — written; released as 0.1.0Line truncated
| M17 | **What the input reader does on a real PC with a real controller — unmeasured (2026-11-14, owner decision D157: built without a probe).** Written and tested against a Windows whose answers the tests write, and run on the developer's PC with no controller connected. Open, each read from the counts a session stores (`InputHealth`) and the Agent's log: (a) **whether XInput answers a program with no window in front** — Microsoft's `XInputEnable` page says the system switches controller input by focus; the reader counts the slices in which a device's own reports changed and XInput said nothing, and falls back to the reports after ten; (b) whether raw input delivers, in the background, the reports of an Xbox pad on USB, on the wireless adapter and on Bluetooth, and of a DualSense on USB and on Bluetooth; (c) whether XInput returns a battery for an Xbox pad on Bluetooth (reported not to); (d) whether a DualSense's reports are laid out as `Domain.Input.DualSenseReport` reads them, and whether its battery is there on Bluetooth with Steam running; (e) whether a controller's own input moves `GetLastInputInfo`'s time (if it does, a controller reads as *both*); (f) **the reader's cost with a controller that sends several hundred reports a second**, against NFR-2's 2.5 % of one core, of which about 2 % is already used — `tools/agent-cost.ps1` measures it with no controller only. **Measured 2026-11-14, the real Agent, no controller connected**: in four sessions of 30 and 90 s the reader took 277 and 834 slices, Windows accepted the registration, XInput's library and the time of the last input were there, and the reader's thread used 15–62 ms of processor time — under 0.2 % of one core in the worst of them. The whole Agent, per second of session: 2.06 % of one core with nothing optional, 1.54 % with input read, 1.61 % with Advanced metrics — three numbers inside the tool's own run-to-run variation (the two 90 s medians with and without input differ by 48 ms), so **the reader's cost is not distinguishable from nothing with no controller connected, and unmeasured with one**; (g) an unelevated Agent beside a game that runs as administrator. Owner-only item 48 (`HANDOFF`) |
| M15 🅓 | **Decided 2026-11-14 (D154): not built. The owner closed Advanced metrics with the refusal standing; the ten entries are listed as not read, with the reason.** ~~**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 |
+17 -5
View File
@@ -4,12 +4,13 @@ What FrameLedger reads about game controllers and about the keyboard and mouse,
The numbers a session makes of it are in [`03_METRICS.md`](03_METRICS.md) §Input; the columns are in
[`06_DATA_MODEL.md`](06_DATA_MODEL.md).
> **Status, 2026-11-14 — the reader exists and the Agent does not start it yet.** The model and the arithmetic
> **Status, 2026-11-14 — the Agent records it; the App does not show it yet.** A session recorded with the option
> on, after the terms were accepted, stores what it was played with: the model and the arithmetic
> (`FrameLedger.Domain.Input`, `FrameLedger.Application.Input`, `Application.Recording.InputSessionBuilder`), the
> storage (schema 0024, the `.partial` file's chunk 11, the finalizer for both tiers — `06_DATA_MODEL`) and the reader
> itself (`Application.Input.InputReader`, `Infrastructure.Input`) are written and under test. Nothing composes the
> reader into the Agent: the switch, the terms and the screens come in the pull requests after this one, and this
> note is rewritten by each. **No report from a real controller has passed through any of this code**
> storage (schema 0024, the `.partial` file's chunk 11 — `06_DATA_MODEL`), the reader (`Application.Input.InputReader`,
> `Infrastructure.Input`) and its composition into the Agent (`capture.input_devices`, `Application.Input.InputTerms`)
> are written and under test. The screens, the store's word and the input libraries come in the pull requests after
> this one, and this note is rewritten by each. **No report from a real controller has passed through any of this code**
> (owner decision D157): the developer has no controller, and what happens on a real one is owner-only item 48.
## The owner's request and decisions (2026-11-14)
@@ -31,6 +32,17 @@ DualSense first.
| **D162** | Also built: the number of switches between a controller and the keyboard and mouse, and the share of time with no input; marks on the frame-time chart where a controller connected, dropped or ran low; a battery's first and last level and its rate; the kind of connection; a note where Steam Input presented the controller as an Xbox pad; a trend metric, a row in Compare, and "usually played with" on the game's page. |
| **D163** | "Supports controllers" is **three pieces of evidence, never a verdict**: what Steam's own file on the disk says (no network: rule 8), which input libraries the game loaded, and how the game was actually played. From outside a game one can know that a controller was in use while the game was in front — not what the game did with it. |
## The switch, and the terms
`capture.input_devices` — Settings ▸ Recording ▸ *Controllers and input* — is **on unless switched off** (D156), and
is read at each session's start like every setting the Agent reads. On is not enough: the Agent is usually started
at logon, and after an update that is before the App has shown the Privacy Policy that describes this reading. So
`SettingsRecorderPolicy` gives a session the reader only when `legal_acceptance` holds the Privacy Policy at
`InputTerms.MinimumPrivacyVersion` (2.22) or later. Until then the session reads nothing of controllers or of the
keyboard and mouse, stores none of schema 0024's columns, and says so: the slot `input=terms_pending` in
`sessions.capture_notes` (`CaptureNotes.InputHeldForTerms`), and a line in its `.partial` file's notes. An operator's console with no acceptance store reads
nothing either. Off, or held back, a session is byte for byte what it was before the reading existed.
## What is read, and from where
Everything is a Windows API in a library Windows ships. **No third-party library is added.**
+20
View File
@@ -63,6 +63,26 @@ are kept because they record what each version changed and why (owner decision D
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
### What version 2.22 of the Privacy Policy and 2.18 of the Disclaimer changed (0.1.0-beta.50)
**Both documents said FrameLedger never reads input, and it now reads that a controller, or the keyboard or mouse,
is in use** (owner decisions D155–D163; the sentences were shown to the owner with the plan of 2026-11-14 and
approved with it). Until this version the Privacy Policy's §4 said it "does not read game saves, chat, input
content", the Disclaimer's §1 that it never reads "save files, input, chat", the README that it "never touches saves
or input", and the guide that it never reads "your input". The **Privacy Policy** (2.22) adds to §1 what a session
stores of controllers and input and what it never does — which button, stick, trigger or key, text, the mouse's
position, a serial number, a Bluetooth address; to §3A that these numbers, unlike Advanced metrics', **are** in an
export and in a bug report (D160); to §4 what is observed — the controllers' reports, looked at and not kept,
XInput's state and battery, the time of the last keyboard or mouse input, the window in front — and that nothing is
opened or sent; and narrows the sentence after it to what is still true. It also says, in §1 and §4, that nothing
of this is read until that version has been accepted on the PC (D156): the option is on unless switched off, and an
Agent that started before the App showed the document records without it. The **Disclaimer** (2.18) gains a
paragraph in §1 for what is read from outside the game about controllers, the keyboard and the mouse, and its "what
it never does" names what is kept instead of the word "input", and adds that nothing is sent to a controller
(D159). The **accuracy statement** — and so the README and the Disclaimer — gains a paragraph that ends: none of
this had been read from a real controller when it was written. The trademarks notice names Sony's and Nintendo's
products, which the App now shows as a controller's model.
### What version 2.21 of the Privacy Policy and 2.17 of the Disclaimer changed (0.1.0-beta.48)
**Two real games had been read, and the texts still said none** (owner decisions D142–D145; the wording's main
+4 -2
View File
@@ -16,8 +16,10 @@ your decision and your risk.
refuses — or stops measuring at the next check — and turns hooking off for that game. **There is no switch that
overrides this**, apart from the one narrow exception below.
- **It never hides.** It keeps its real name and does nothing to avoid being seen by security software.
- **It never reads or changes the game's memory**, its saves or your input. It only observes the graphics calls the
game makes.
- **It never reads or changes the game's memory** or its saves, and never what you type or which buttons you press.
Inside the game it only observes the graphics calls the game makes. From outside it — unless you switch
*Controllers and input* off in Settings — it notes whether a controller, or the keyboard or mouse, is in use, and
sends nothing to a controller.
## What it cannot promise
+2
View File
@@ -22,6 +22,8 @@ The link under them, *Read what the hook does and does not do*, opens the safety
| **Minimum session length (s)** | A shorter session is not kept. 5 to 600 seconds. *Agent.* | 30 |
| **Sensor interval (ms)** | How often the PC's sensors are read during a session. 500 to 2000 ms. With a value above 1000, not every reading of NVIDIA's latency report — made about once a second inside the game — becomes a point: each point is still one reading ([Advanced metrics](12-advanced-metrics.md)). *Agent.* | 1000 |
| **Raw series kept per game** | How many of each game's newest sessions keep their per-frame data; older ones keep their statistics. 0 keeps everything. *Agent.* | 20 |
| **Controllers and input** | Records what a session was played with: which game controllers were connected and in use, their battery level, and whether the keyboard or mouse was in use — as times, read from Windows and never from the game. No button, stick, key or text is kept, and nothing is sent to a controller. Nothing is read until you have accepted the Privacy Policy that describes it, so after an update the first sessions have no such figures until FrameLedger has been opened once. Off: nothing of this is read or stored. It applies from the next session; a session recorded while it was off is not filled in later. *Agent.* | On |
| **Controllers and input** | Records what a session was played with: which game controllers were connected and in use, their battery level, and whether the keyboard or mouse was in use — as times, read from Windows and never from the game. No button, stick, key or text is kept, and nothing is sent to a controller. Nothing is read until you have accepted the Privacy Policy that describes it, so after an update the first sessions have no such figures until FrameLedger has been opened once. Off: nothing of this is read or stored. It applies from the next session; a session recorded while it was off is not filled in later. *Agent.* | On |
| **Advanced metrics** | Reads more from the graphics driver and the hardware sensors during a session — the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game — and stores it with the session. In a game FrameLedger measures from inside it also reads what the game tells DLSS, Streamline and FSR, and — on an NVIDIA card, in a Direct3D 12 game that uses NVIDIA's library — asks the graphics driver about once a second how long each stage of a frame took ([Advanced metrics](12-advanced-metrics.md)). Off: nothing more is read or stored. It applies from the next session; a session recorded while it was off is not filled in later. While it is on, the **Advanced** page is in the list on the left ([Advanced metrics](12-advanced-metrics.md)). *Agent.* | Off |
## Data
+10
View File
@@ -106,6 +106,16 @@
> temperature in every session, and, on NVIDIA cards only, how much of the time its power limit or its temperature held
> it back, read once a second; and frames per watt — the game's own frames per second for each watt the graphics card
> drew, never counting generated frames, `N/A` where the game's own frame rate is not known.
> - **Controllers and input (since beta.50; on unless you switch it off in Settings, and only once you have accepted
> the Privacy Policy that describes it):** how much of the time a game was in front it was played with a
> controller, with the keyboard or mouse, with both or with neither; each controller's connections and drops; its
> battery. All of it is read from Windows, from outside the game: it says a controller was in use while the game
> was in front, not what the game did with it. Keyboard and mouse are one figure — only the time of the last input
> is read — and input a program injects (Steam Input mapping a controller to keys, a macro tool) counts as keyboard
> and mouse. An Xbox-compatible controller and a DualSense are read for use; another maker's controller is listed
> and never counted as in use. A DualSense on Bluetooth reports its battery only where Steam or the game has
> switched it to its long report, and an Xbox controller on Bluetooth may report none. **None of this had been
> read from a real controller when it was written (2026-11-14)**: it was checked against data written by hand.
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
+14 -2
View File
@@ -1,6 +1,6 @@
# FrameLedger — Disclaimer
**Version:** 2.17 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.18 · **Effective:** {{RELEASE_DATE}}
## 0. This is pre-release software
@@ -47,9 +47,11 @@ Install it somewhere only you can write to, and verify the published SHA-256 che
**What it reads about the game from outside it, in every session:** the game process's own memory use — its dedicated and shared video memory and its working sets, the figures Windows' Task Manager shows — from Windows' performance counters and process-memory information. For a game it does not inject into, FrameLedger opens the game's process for this with the least access Windows offers, once a second, and closes it again; it reads nothing inside the process.
**What it reads about controllers, the keyboard and the mouse, from outside the game, unless you switch it off:** which game controllers are connected, whether one is in use, its battery level, and the time of the last keyboard or mouse input — to say how much of a session was played with a controller and how much with the keyboard or mouse. It asks Windows, never the game; it opens no controller and sends nothing to one; and it keeps no key, button or text (the Privacy Policy says exactly what is kept). It reads none of this until you have accepted the Privacy Policy that describes it.
> **What of that list is observed today is stated once, in §4 below** (the block `legal/ACCURACY.md` carries, dated). The list here describes what the software is designed to observe, and the boundary — API arguments, and the one report asked of the graphics driver that the line above names; nothing of the game's own memory — holds for all of it.
**What it never does:** read or write the game's memory outside those API arguments; read save files, input, chat, or network traffic; modify game behavior; hide itself from any security software; or install a kernel driver of its own.
**What it never does:** read or write the game's memory outside those API arguments; read save files, chat, or network traffic; read what you type or which buttons you press — it keeps only whether a controller, or the keyboard or mouse, was in use, read from Windows and never from the game; send anything to a controller; modify game behavior; hide itself from any security software; or install a kernel driver of its own.
## 2. Anti-cheat systems — the main risk to you
@@ -219,6 +221,16 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> temperature in every session, and, on NVIDIA cards only, how much of the time its power limit or its temperature held
> it back, read once a second; and frames per watt — the game's own frames per second for each watt the graphics card
> drew, never counting generated frames, `N/A` where the game's own frame rate is not known.
> - **Controllers and input (since beta.50; on unless you switch it off in Settings, and only once you have accepted
> the Privacy Policy that describes it):** how much of the time a game was in front it was played with a
> controller, with the keyboard or mouse, with both or with neither; each controller's connections and drops; its
> battery. All of it is read from Windows, from outside the game: it says a controller was in use while the game
> was in front, not what the game did with it. Keyboard and mouse are one figure — only the time of the last input
> is read — and input a program injects (Steam Input mapping a controller to keys, a macro tool) counts as keyboard
> and mouse. An Xbox-compatible controller and a DualSense are read for use; another maker's controller is listed
> and never counted as in use. A DualSense on Bluetooth reports its battery only where Steam or the game has
> switched it to its long report, and an Xbox controller on Bluetooth may report none. **None of this had been
> read from a real controller when it was written (2026-11-14)**: it was checked against data written by hand.
> - **Processor and memory:** how busy the processor was (time busy, all cores together — not the
> frequency-scaled figure Task Manager draws) and how much system memory was in use, read from
> Windows once a second and charted. Processor temperature is read only when the Agent runs as
+5 -4
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.21 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.22 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -12,6 +12,7 @@ Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Images you choose for a game (Edit…), copied into the `covers` folder; choosing the store's image again, or removing the game together with its sessions, deletes the copy. Artwork a store's app keeps on your PC, or a game ships in its own folder, is shown from where it is and not copied.
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, power, memory usage, and the graphics card's clock speeds, fan speed, memory temperature and whether its power limit or heat held it back), the game's own memory use (its dedicated and shared video memory, private working set, working set and commit, once a second), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), how the game's window was shown (full-screen, borderless or windowed, for how long, its size and the monitor's), tags and notes you write.
- **Only while Settings ▸ Advanced metrics is on** (it is off unless you switch it on), with each session: more hardware sensor series — the graphics card's memory use in detail, its load by part, its clocks, voltages, currents, power, each fan and its video encoder's use; and, when the capture agent runs as administrator with PawnIO installed, the processor's temperatures, load, clocks, power and voltages by core, the memory in use and its modules' temperatures, and the motherboard's temperatures, fans and voltages — and a description of the hardware: the graphics card's firmware version, architecture, bus and memory sizes, the graphics driver's package and the chipset it names, the motherboard's and the memory modules' model names, what each connected display can do (the HDR formats it accepts, its brightness range, variable refresh), whether variable refresh was in use on the display the game ran on and the colour space the game presented in, and the graphics driver's settings — its global ones and the ones it holds for the game (NVIDIA only). For a game FrameLedger injects into, a session then also stores what the game itself passed to its upscaler in the calls FrameLedger intercepts: the output size, the model presets and the exposure values it gave DLSS, whether it said its colour buffers are HDR, auto-exposure and alpha upscaling; and the sharpening, the size of the jitter, the exposure, the depth range, the lowest and highest field of view and the flags it gave FSR, the frame time it reported to FSR, and FSR's own video memory when the game asked for it; what the game told NVIDIA Streamline about each frame — the size of the jitter, the motion-vector scale, the depth range and whether depth is inverted, the lowest and highest field of view, the aspect ratio, whether the projection is orthographic, how its motion vectors are stored and how often it reset the upscaler's history; and how it configured FSR frame generation — on or off, whether it may run asynchronously, its flags, whether only generated frames are presented, and the rectangle it generates in; and what NVIDIA Streamline answered when the game asked it about a feature — which features the game asked about, the version of each and of its NGX model, and what each requires: the graphics APIs it supports, whether V-Sync must be off and hardware-accelerated GPU scheduling on, how many processor threads, viewports and buffers, and the versions of Windows and of the graphics driver that Streamline found beside the ones the feature needs ; and, for each Streamline feature the game asks about or controls: whether Streamline answers that it is supported, whether it is loaded, whether the game switched it on or off while it ran, and how many times its resources were allocated and freed; and whether the game shut Streamline down, and how many times — never the lists Streamline's answer points to (the buffers' names, the names of Vulkan extensions and features), never what identifies the graphics card that the game hands over with its question, never the content of a graphics resource, and never where the game's camera is, which way it looks, or its matrices. For a Direct3D 12 game that had itself loaded NVIDIA's driver library, a session also stores what the graphics driver reports about the game's frames when FrameLedger asks it, about once a second, from inside the game: how long each stage of a frame took — simulation, render submit, present, the driver, the operating system's queue and the graphics card, and the whole from the start of simulation to the end of the graphics card's work — as averages in microseconds, with two figures the driver works out itself (how long the graphics card was actually at work on a frame, and the time from the end of one frame's work to the end of the next), and the driver's low-latency state (five switches it reports, and the frame-generation multipliers it gave during the session) — never a time of day, and never the moment the player pressed anything. No serial number, no display identification data (EDID) and no list of other programs is read or stored. Switching the option off stops the reading, inside a game as well; what earlier sessions stored stays with them until you delete those sessions.
- **Unless you switch Settings ▸ Controllers and input off** — and it reads nothing until you have accepted this version of this document — with each session: which game controllers were connected (the model's name, its maker and how it was connected: USB, Bluetooth or a wireless adapter), how many times each connected and disconnected, its battery level when the controller reports one, and, for each second the game was in front, whether a controller was in use, whether the keyboard or mouse was in use, both, or neither. Never which button, stick, trigger or key, never text, never where the mouse is, and never a serial number or a Bluetooth address. Switching the option off stops the reading; what earlier sessions stored stays with them until you delete those sessions.
- A hardware snapshot per session (CPU/GPU model, driver version, RAM size, OS build, display mode) used for the "what changed between sessions" feature.
- App settings, logs (rotated daily — the app keeps 7 days, the capture agent 14 — including the logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- Which games you enabled code injection for, and when you consented.
@@ -39,13 +40,13 @@ The "Report a bug" feature builds a zip file **on your device**, shows you exact
## 3A. Sharing an export or a bug report
An exported session (CSV or JSON) and a bug report can contain your games' names and **the paths to their files** — which include your **Windows user name** when a game is installed under your user folder — your hardware model, graphics driver and Windows build, the times you played, and your tags and notes. What a session stores only while Advanced metrics is on (§1) is in neither: an export and a bug report carry what they carried before. A bug report removes user directory paths from its logs; an export is written as it is. Look at a file before you share it. Once you share it, it is outside FrameLedger: whoever receives it, and the site you post it to, can read it under their own terms.
An exported session (CSV or JSON) and a bug report can contain your games' names and **the paths to their files** — which include your **Windows user name** when a game is installed under your user folder — your hardware model, graphics driver and Windows build, the times you played, and your tags and notes. What a session stores only while Advanced metrics is on (§1) is in neither. What a session stores of controllers and input (§1) is in both: the shares of its time played with a controller and with the keyboard or mouse, and each controller's model name, how it was connected, its battery levels and its connection counts. A bug report removes user directory paths from its logs; an export is written as it is. Look at a file before you share it. Once you share it, it is outside FrameLedger: whoever receives it, and the site you post it to, can read it under their own terms.
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, and the parameters of ten further calls it begins to intercept in a game only once a session with that option on has started there (the constants the game gives NVIDIA Streamline for each frame, the game's configuration of FSR frame generation, Streamline's answers to the game's four questions about a feature — which version it is, what it requires, whether it is supported and whether it is loaded — and the game switching a feature on or off, allocating and freeing its resources, and shutting Streamline down), which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the motion-vector scale, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory, how frame generation is configured, the versions and requirements of Streamline's features, whether each is supported and loaded, and how often the game switched it, allocated and freed its resources and shut Streamline down), never the camera's position, direction or matrices, and never what identifies the graphics card; and — only while Advanced metrics is on, only in a Direct3D 12 game that had itself loaded NVIDIA's driver library — the graphics driver's own report of the game's last frames and its low-latency state, which the component asks that driver for itself about once a second (it makes that call; the game does not), keeping only how long each stage took; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphLine truncated
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, and the parameters of ten further calls it begins to intercept in a game only once a session with that option on has started there (the constants the game gives NVIDIA Streamline for each frame, the game's configuration of FSR frame generation, Streamline's answers to the game's four questions about a feature — which version it is, what it requires, whether it is supported and whether it is loaded — and the game switching a feature on or off, allocating and freeing its resources, and shutting Streamline down), which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the motion-vector scale, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory, how frame generation is configured, the versions and requirements of Streamline's features, whether each is supported and loaded, and how often the game switched it, allocated and freed its resources and shut Streamline down), never the camera's position, direction or matrices, and never what identifies the graphics card; and — only while Advanced metrics is on, only in a Direct3D 12 game that had itself loaded NVIDIA's driver library — the graphics driver's own report of the game's last frames and its low-latency state, which the component asks that driver for itself about once a second (it makes that call; the game does not), keeping only how long each stage took; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphLine truncated
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, what you type or which buttons you press — only that a controller, or the keyboard or mouse, was in use (§1) — network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
All of this stays on your device. None of it is transmitted anywhere.
+2 -1
View File
@@ -12,7 +12,8 @@ Microsoft Corporation. NVIDIA, GeForce, RTX, DLSS,
Reflex, NVAPI and Streamline are trademarks of NVIDIA Corporation. AMD, Radeon, FSR and FidelityFX are trademarks of
Advanced Micro Devices, Inc. Intel, Arc and XeSS are trademarks of Intel Corporation. Vulkan is a registered trademark
of the Khronos Group Inc.; OpenGL is a registered trademark of Hewlett Packard Enterprise, used under licence by the
Khronos Group. Steam and Valve are trademarks of Valve Corporation; Epic Games, the Epic Games Store and Unreal Engine of
Khronos Group. PlayStation, DualSense and DualShock are trademarks of Sony Interactive Entertainment Inc.; Nintendo Switch is a
trademark of Nintendo. Steam and Valve are trademarks of Valve Corporation; Epic Games, the Epic Games Store and Unreal Engine of
Epic Games, Inc.; Unity of Unity Technologies. GOG, GOG Galaxy and itch.io are trademarks of their respective owners. The
names of anti-cheat and anti-tamper products, and the names and store identifiers of games, belong to their respective
owners. All other product names are trademarks of their respective owners.
@@ -5,6 +5,7 @@ using FrameLedger.Application.Advanced;
using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Consent;
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Infrastructure.Display;
@@ -45,6 +46,7 @@ internal sealed class AgentRecording
private readonly UserModeExceptionLapsePolicy _exceptionLapse;
private readonly ICrashReporterSightings _reporters;
private readonly IAdvancedHardware _advanced;
private readonly IInputDevices _input;
public AgentRecording(
IGameConsentStore store,
@@ -70,9 +72,11 @@ internal sealed class AgentRecording
IOverlayToleranceChannel tolerance,
UserModeExceptionLapsePolicy exceptionLapse,
ICrashReporterSightings reporters,
IAdvancedHardware advanced)
IAdvancedHardware advanced,
IInputDevices input)
{
_advanced = advanced;
_input = input;
_reporters = reporters;
_profiles = profiles;
_exceptions = exceptions;
@@ -123,7 +127,7 @@ internal sealed class AgentRecording
_partials,
_finalizer,
_crashes,
options => Poller(options.TelemetryInterval, options.AdvancedMetrics ? _advanced : null),
options => Poller(options.TelemetryInterval, options.AdvancedMetrics ? _advanced : null, options.InputDevices ? _input : null),
TimeProvider.System,
new RecorderOptions { MinimumSessionLength = minimum, PartialFlushInterval = flush },
_observer,
@@ -137,7 +141,8 @@ internal sealed class AgentRecording
/// <summary>L1 + L2 + L3 under the composite, one poller per session; the poller owns and disposes the layers. The interval is the session's (<c>telemetry.interval_ms</c>, D16).</summary>
/// <param name="interval">Between two polls.</param>
/// <param name="advanced">The Agent's shared advanced reader when the session records Advanced metrics (D101); null — the option off — composes none.</param>
public static TelemetryPoller Poller(TimeSpan interval, IAdvancedHardware? advanced = null)
/// <param name="input">The Agent's one input reader when the session reads controllers and input (D155, D156); null - the option off, or its terms not accepted - opens none.</param>
public static TelemetryPoller Poller(TimeSpan interval, IAdvancedHardware? advanced = null, IInputDevices? input = null)
{
// Ownership walks up one step at a time and each local is nulled at its hand-off, so a throw
// anywhere below disposes exactly what nobody owns yet.
@@ -168,7 +173,7 @@ internal sealed class AgentRecording
// The game process's own memory (beta.12, D43): read from outside it through FrameLedger.ProcessStats.dll, for
// whichever process the capture loop tells the poller to follow. Absent DLL = N/A, never a fault.
game = new GameMemoryReader(new NativeProcessStats());
var poller = new TelemetryPoller(composite, new TelemetryPollerOptions { Interval = interval }, TimeProvider.System, ownsSource: true, system, game, advanced);
var poller = new TelemetryPoller(composite, new TelemetryPollerOptions { Interval = interval }, TimeProvider.System, ownsSource: true, system, game, advanced, input);
composite = null;
system = null;
game = null;
@@ -7,6 +7,7 @@ using FrameLedger.Application.AntiCheat;
using FrameLedger.Application.Capture;
using FrameLedger.Application.Consent;
using FrameLedger.Application.Detection;
using FrameLedger.Application.Input;
using FrameLedger.Application.Ipc;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
@@ -19,6 +20,7 @@ using FrameLedger.Infrastructure.Blobs;
using FrameLedger.Infrastructure.Capture;
using FrameLedger.Infrastructure.Detection;
using FrameLedger.Infrastructure.Import;
using FrameLedger.Infrastructure.Input;
using FrameLedger.Infrastructure.Ipc;
using FrameLedger.Infrastructure.Persistence;
using FrameLedger.Infrastructure.Recording;
@@ -72,6 +74,8 @@ internal static class AgentServices
services.AddSingleton<ISettingsStore, SqliteSettingsStore>();
// The registry over the store (P3 PR-3, D16): the recorder resolves its three keys at each session start.
services.AddSingleton<RegisteredSettings>();
// Read by the recorder's policy only: the input reading waits for the Privacy Policy that describes it (D156).
services.AddSingleton<ILegalAcceptanceStore, SqliteLegalAcceptanceStore>();
services.AddSingleton<IRecorderPolicy, SettingsRecorderPolicy>();
services.AddSingleton<SettingsKillSwitch>();
services.AddSingleton<IKillSwitch>(static sp => sp.GetRequiredService<SettingsKillSwitch>());
@@ -130,6 +134,18 @@ internal static class AgentServices
interval: TimeSpan.FromSeconds(1),
linger: TimeSpan.FromSeconds(10),
static line => Serilog.Log.Information("{Line}", line)));
// Controllers and input (owner decisions D155-D159): ONE reader for the whole Agent, on a thread of its own, that
// exists only while a session has a view of it - a session recorded with the option on, after the terms that
// describe the reading were accepted (D156). Constructing it opens nothing: with no session there is no thread,
// no window and no registration. It is paused with the recording. The container disposes it with the host.
services.AddSingleton<IInputDevices>(static sp =>
{
CapturePause pause = sp.GetRequiredService<CapturePause>();
return new InputDeviceHub(
static () => new Win32InputBackend(),
paused: () => pause.IsPaused,
note: static line => Serilog.Log.Information("{Line}", line));
});
services.AddSingleton<AgentRecording>();
}
@@ -227,6 +227,19 @@
IsChecked="{Binding ViewModel.AdvancedMetrics, Mode=TwoWay}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}" />
</ui:CardControl>
<!-- Controllers and input (owner decisions D155 and D156, 2026-11-14): on unless switched off, and read only
once the Privacy Policy that describes it has been accepted. The Agent reads it at each session's start. -->
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon XboxController24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_Input_Label}" />
<ui:TextBlock MaxWidth="560" HorizontalAlignment="Left" Style="{StaticResource SecondaryText}" Text="{x:Static res:Strings.Settings_Input_Body}" TextWrapping="Wrap" />
</StackPanel>
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_Input_Label}"
IsChecked="{Binding ViewModel.InputDevices, Mode=TwoWay}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}" />
</ui:CardControl>
<!-- beta.12: "Record games launched outside FrameLedger" stood here; nothing read it (capture.background,
06_DATA_MODEL §Settings registry), and with no way to start a game from the App "off" could only have
meant recording nothing. Removed until a launch path exists. -->
@@ -102,7 +102,7 @@ public sealed class SessionExporter
w.WriteLine("# exe: " + game.Fingerprint.ExePath);
w.WriteLine("# started_at: " + row.StartedAt.ToString("O", _inv));
w.WriteLine("# ended_at: " + row.EndedAt.ToString("O", _inv));
w.WriteLine("# capture_tier: " + ((int)row.Tier).ToString(_inv) + (row.Tier == CaptureTier.Hooked ? " (hooked, measured)" : " (not hooked: duration and sensors only; no per-frame rows)"));
w.WriteLine("# capture_tier: " + ((int)row.Tier).ToString(_inv) + (row.Tier == CaptureTier.Hooked ? " (hooked, measured)" : " (not hooked: duration, sensors and what is read from outside the game; no per-frame rows)"));
if (row.AcExceptionFamily is { Length: > 0 } excepted)
{
// D33: a session hooked under the game's user-mode anti-cheat exception says so wherever it goes (the JSON carries
+6
View File
@@ -1294,6 +1294,8 @@ public static class Strings
nameof(Settings_HideScrollBars_Label),
nameof(Settings_HookedGames_Label),
nameof(Settings_HookedGames_Revoke),
nameof(Settings_Input_Body),
nameof(Settings_Input_Label),
nameof(Settings_Interval_Body),
nameof(Settings_Interval_Label),
nameof(Settings_Invalid_Format),
@@ -4092,6 +4094,10 @@ public static class Strings
public static string Settings_HookedGames_Revoke => ResourceManager.GetString(nameof(Settings_HookedGames_Revoke), Culture) ?? nameof(Settings_HookedGames_Revoke);
public static string Settings_Input_Body => ResourceManager.GetString(nameof(Settings_Input_Body), Culture) ?? nameof(Settings_Input_Body);
public static string Settings_Input_Label => ResourceManager.GetString(nameof(Settings_Input_Label), Culture) ?? nameof(Settings_Input_Label);
public static string Settings_Interval_Body => ResourceManager.GetString(nameof(Settings_Interval_Body), Culture) ?? nameof(Settings_Interval_Body);
public static string Settings_Interval_Label => ResourceManager.GetString(nameof(Settings_Interval_Label), Culture) ?? nameof(Settings_Interval_Label);
+9 -1
View File
@@ -1589,6 +1589,14 @@
<value>詳細メトリクス</value>
<comment>review</comment>
</data>
<data name="Settings_Input_Body" xml:space="preserve">
<value>セッションが何でプレイされたかを記録します - 接続されていたゲーム コントローラーと使用中だったコントローラー、そのバッテリー残量、キーボードまたはマウスが使われていたかどうか - を時間として、ゲームからではなく Windows から読み取ります。ボタン、スティック、キー、文字は保存されず、コントローラーには何も送信されず、これを説明するプライバシー ポリシーに同意するまでは何も読み取りません。オフ: これらは読み取りも保存もされません。次のセッションから適用され、オフの間に記録されたセッションが後から補われることはありません。</value>
<comment>review</comment>
</data>
<data name="Settings_Input_Label" xml:space="preserve">
<value>コントローラーと入力</value>
<comment>review</comment>
</data>
<data name="Settings_Appearance_Header" xml:space="preserve">
<value>外観</value>
<comment>review</comment>
@@ -2474,7 +2482,7 @@
<comment>review</comment>
</data>
<data name="Tier_NotHooked_Tooltip" xml:space="preserve">
<value>ティア 2: フックなし — 時間、センサー、ゲームのメモリのみ。フレームから算出する値はすべて N/A</value>
<value>ティア 2: フックなし — 時間、センサー、ゲームのメモリ、何でプレイされたかのみ。フレームから算出する値はすべて N/A</value>
<comment>review</comment>
</data>
<data name="Upscaler_None" xml:space="preserve">
+7 -1
View File
@@ -1197,6 +1197,12 @@
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Advanced metrics</value>
</data>
<data name="Settings_Input_Body" xml:space="preserve">
<value>Record what a session was played with: which game controllers were connected and in use, their battery level, and whether the keyboard or mouse was in use - as times, read from Windows and never from the game. No button, stick, key or text is kept, nothing is sent to a controller, and nothing is read until you have accepted the Privacy Policy that describes it. Off: nothing of this is read or stored. It applies from the next session, and a session recorded while it was off is not filled in later.</value>
</data>
<data name="Settings_Input_Label" xml:space="preserve">
<value>Controllers and input</value>
</data>
<data name="Settings_Appearance_Header" xml:space="preserve">
<value>Appearance</value>
</data>
@@ -1861,7 +1867,7 @@
<value>T2</value>
</data>
<data name="Tier_NotHooked_Tooltip" xml:space="preserve">
<value>Tier 2: not hooked — duration, sensors and the game's memory only; every frame-derived value is N/A</value>
<value>Tier 2: not hooked — duration, sensors, the game's memory and what it was played with only; every frame-derived value is N/A</value>
</data>
<data name="Upscaler_None" xml:space="preserve">
<value>No upscaler</value>
+7 -1
View File
@@ -1192,6 +1192,12 @@
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Thông số nâng cao</value>
</data>
<data name="Settings_Input_Body" xml:space="preserve">
<value>Ghi lại phiên được chơi bằng gì: tay cầm nào đang kết nối và đang được dùng, mức pin của chúng, và bàn phím hay chuột có được dùng hay không - dưới dạng thời gian, đọc từ Windows chứ không bao giờ từ game. Không lưu nút, cần, phím hay văn bản nào, không gửi gì tới tay cầm, và không đọc gì cho tới khi bạn chấp nhận Chính sách quyền riêng tư mô tả việc này. Tắt: không đọc hay lưu gì trong số này. Áp dụng từ phiên kế tiếp; phiên ghi lúc đang tắt sẽ không được bổ sung về sau.</value>
</data>
<data name="Settings_Input_Label" xml:space="preserve">
<value>Tay cầm và thao tác nhập</value>
</data>
<data name="Settings_Appearance_Header" xml:space="preserve">
<value>Giao diện</value>
</data>
@@ -1856,7 +1862,7 @@
<value>T2</value>
</data>
<data name="Tier_NotHooked_Tooltip" xml:space="preserve">
<value>Mức 2: không hook — chỉ có thời lượng, cảm biến và bộ nhớ của game; mọi giá trị suy ra từ khung hình đều là N/A</value>
<value>Mức 2: không hook — chỉ có thời lượng, cảm biến, bộ nhớ của game và việc phiên được chơi bằng gì; mọi giá trị suy ra từ khung hình đều là N/A</value>
</data>
<data name="Upscaler_None" xml:space="preserve">
<value>Không upscaler</value>
@@ -87,6 +87,14 @@ public sealed partial class SettingsViewModel : ObservableObject
[ObservableProperty]
private bool _advancedMetrics;
/// <summary>
/// "Controllers and input" (owner decisions D155 and D156, <c>capture.input_devices</c>, on by default): the Agent
/// reads which controllers are connected and in use and the time of the last keyboard or mouse input, from outside
/// the game, and a session stores what it was played with; off, nothing of it is read or stored.
/// </summary>
[ObservableProperty]
private bool _inputDevices;
[ObservableProperty]
private int _minSessionSeconds;
@@ -443,6 +451,8 @@ public sealed partial class SettingsViewModel : ObservableObject
Persist(SettingsRegistry.TelemetryAdvanced, value);
}
partial void OnInputDevicesChanged(bool value) => Persist(SettingsRegistry.CaptureInputDevices, value);
partial void OnHideAntiCheatHookingChanged(bool value) => Persist(SettingsRegistry.UiHideAntiCheatHooking, value);
/// <summary>D33: the option is one settings row the Agent reads at every session start and command; the list follows it.</summary>
@@ -599,6 +609,7 @@ public sealed partial class SettingsViewModel : ObservableObject
RetentionRawSessions = await _settings.GetIntegerAsync(SettingsRegistry.RetentionRawSessionsPerGame).ConfigureAwait(true);
RemoveUninstalledGames = await _settings.GetBooleanAsync(SettingsRegistry.RetentionRemoveUninstalledGames).ConfigureAwait(true);
AdvancedMetrics = await _settings.GetBooleanAsync(SettingsRegistry.TelemetryAdvanced).ConfigureAwait(true);
InputDevices = await _settings.GetBooleanAsync(SettingsRegistry.CaptureInputDevices).ConfigureAwait(true);
MinimizeToTray = await _settings.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true);
HideAntiCheatHooking = await _settings.GetBooleanAsync(SettingsRegistry.UiHideAntiCheatHooking).ConfigureAwait(true);
UserModeExceptions = await _settings.GetBooleanAsync(SettingsRegistry.HookingUserModeExceptions).ConfigureAwait(true);
@@ -0,0 +1,45 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
namespace FrameLedger.Application.Input;
/// <summary>
/// The terms that describe the input reading, and whether they have been accepted on this PC (owner decision D156,
/// 2026-11-14). The option is on unless switched off, and the Agent is often started at logon - before the App that
/// shows a new Privacy Policy has been opened. So the Agent reads controllers and keyboard-and-mouse activity only
/// when the Privacy Policy the user accepted is the one that first described that reading, or a later one.
/// </summary>
public static class InputTerms
{
/// <summary>The Privacy Policy's key in <c>legal_acceptance</c> - the App's <c>LegalDocuments.Privacy</c>, which a test holds to this.</summary>
public const string PrivacyDocument = "privacy";
/// <summary>The first version of the Privacy Policy that describes the reading.</summary>
public const string MinimumPrivacyVersion = "2.22";
/// <summary>
/// Whether an accepted version is <see cref="MinimumPrivacyVersion"/> or later. A version is two whole numbers with
/// a dot between them, compared as numbers - 2.9 is before 2.22. No version, and anything that is not one, is not
/// accepted: a document nobody can be shown to have accepted permits nothing.
/// </summary>
public static bool Accepted(string? acceptedVersion) =>
Parse(acceptedVersion) is { } accepted && Parse(MinimumPrivacyVersion) is { } minimum
&& (accepted.Major > minimum.Major || (accepted.Major == minimum.Major && accepted.Minor >= minimum.Minor));
private static (int Major, int Minor)? Parse(string? version)
{
if (version is null)
{
return null;
}
string[] parts = version.Trim().Split('.');
return parts.Length == 2
&& int.TryParse(parts[0], NumberStyles.None, CultureInfo.InvariantCulture, out int major)
&& int.TryParse(parts[1], NumberStyles.None, CultureInfo.InvariantCulture, out int minor)
? (major, minor)
: null;
}
}
@@ -52,12 +52,23 @@ public readonly record struct CaptureNotes(string? End, string? GuardReason, str
/// <summary>beta.14: a crash reporter the game started that did not count — the game kept running (<c>crash_reporter_seen=</c>).</summary>
public string? CrashReporterSeen { get; init; }
public static CaptureNotes Parse(string? notes)
/// <summary>
/// 0.1.0-beta.50 (owner decision D156): the session read nothing of controllers or of the keyboard and mouse
/// because the Privacy Policy that describes the reading was not accepted on the PC yet (<see cref="InputHeldSlot"/>).
/// False on every other session - one that read, one recorded with the option off, one from before the reading existed.
/// </summary>
public bool InputHeldForTerms { get; init; }
/// <summary>The slot of a session whose input reading waited for the terms (D156).</summary>
public const string InputHeldSlot = "input=terms_pending";
public static CaptureNotes Parse(string? notes) => string.IsNullOrWhiteSpace(notes)
? default
: Slots(notes) with { InputHeldForTerms = notes.Split(';').Any(static part => string.Equals(part.Trim(), InputHeldSlot, StringComparison.Ordinal)) };
/// <summary>The slots that carry a value, each by its prefix.</summary>
private static CaptureNotes Slots(string notes)
{
if (string.IsNullOrWhiteSpace(notes))
{
return default;
}
string? end = null, reason = null, family = null, signal = null, acException = null, scanAtExit = null, reporter = null, reporterSeen = null;
int? exitCode = null, launchError = null;
@@ -24,4 +24,17 @@ public sealed record RecorderOptions
/// nothing more than a session always did.
/// </summary>
public bool AdvancedMetrics { get; init; }
/// <summary>
/// Whether this session reads controllers and keyboard-and-mouse activity (owner decisions D155 and D156): the
/// option <c>capture.input_devices</c> is on AND the Privacy Policy that describes the reading has been accepted on
/// this PC. False - the default, and every recorder with no input reader - reads and stores nothing of it.
/// </summary>
public bool InputDevices { get; init; }
/// <summary>
/// The option is on and the reading is held back because the terms that describe it are not accepted yet (D156).
/// The session says so in its notes, so that "nothing was read" has a reason beside it.
/// </summary>
public bool InputHeldForTerms { get; init; }
}
@@ -118,6 +118,9 @@ public sealed class SessionRecorder : ISessionRecorder
}
}
/// <summary>The note of a session whose input reading waits for the terms (owner decision D156).</summary>
public const string InputHeldNote = "input: not read - the Privacy Policy that describes it is not accepted on this PC yet";
private async Task<RecordedSession> RecordStartedAsync(RecordRequest request, GameRow game, Guid guid, DateTimeOffset startedAt,
long qpcEpoch, long snapshotId, RecorderOptions options, CancellationToken ct)
{
@@ -151,6 +154,13 @@ public sealed class SessionRecorder : ISessionRecorder
using var writer = new PartialSessionWriter(_partials.Create(header), _clock, options.PartialFlushInterval);
var run = new Run(writer, poller, _clock, _observer, guid, advanced, request.NormalisedExePath);
writer.Note("started " + request.Mode);
if (options.InputHeldForTerms)
{
// D156: the option is on and nothing of controllers or of the keyboard and mouse is read, because the
// Privacy Policy that describes the reading has not been accepted on this PC yet.
writer.Note(InputHeldNote);
}
CaptureOutcome outcome = await RunLoopAsync(request, run, ct).ConfigureAwait(false);
DateTimeOffset endedAt = _clock.GetUtcNow();
await run.CompleteAdvancedAsync().ConfigureAwait(false);
@@ -213,7 +223,7 @@ public sealed class SessionRecorder : ISessionRecorder
bool crashEvent = hadPid && _crashes.FoundCrash(query);
ExitStatus exit = ExitStatusMapper.Map(outcome.Reason, outcome.ExitCode, crashEvent, reporterCounted);
SessionRow skeleton = Skeleton(header, outcome, endedAt, exit, new CrashWitness(crashEvent, reporter?.Image, reporterCounted), hooked) with { DriverProfileJson = driverProfile };
SessionRow skeleton = WithInputHeld(Skeleton(header, outcome, endedAt, exit, new CrashWitness(crashEvent, reporter?.Image, reporterCounted), hooked), options.InputHeldForTerms) with { DriverProfileJson = driverProfile };
var input = new FinalizeInput
{
Skeleton = skeleton,
@@ -263,6 +273,10 @@ public sealed class SessionRecorder : ISessionRecorder
};
}
/// <summary>D156: a session whose input reading waited for the terms says so in its stored notes, so the App can say why it has no input figures.</summary>
private static SessionRow WithInputHeld(SessionRow row, bool held) =>
held ? row with { CaptureNotes = row.CaptureNotes + "; " + CaptureNotes.InputHeldSlot } : row;
private static SessionRow Skeleton(PartialHeader h, CaptureOutcome o, DateTimeOffset endedAt, ExitStatus exit, CrashWitness crash, bool hooked)
{
string notes = ExitStatusMapper.Describe(o.Reason, o.ExitCode, crash.ApplicationLog, crash.Reporter, crash.ReporterCounted);
@@ -1,6 +1,8 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Settings;
namespace FrameLedger.Application.Recording;
@@ -12,11 +14,23 @@ namespace FrameLedger.Application.Recording;
/// already under the product's) keeps its bound — the setting raises or lowers the product's rule, not the
/// operator's.
/// </summary>
/// <remarks>
/// <b>The input reading has a second condition</b> (owner decision D156): <c>capture.input_devices</c> is on unless
/// switched off, and the Agent may be recording before the App has shown the Privacy Policy that describes the
/// reading. So a session reads controllers and keyboard-and-mouse activity only when the accepted Privacy Policy is
/// that version or a later one (<see cref="InputTerms"/>). With no acceptance store given - an operator's console -
/// nothing can be shown to be accepted, and nothing is read.
/// </remarks>
public sealed class SettingsRecorderPolicy : IRecorderPolicy
{
private readonly RegisteredSettings _settings;
private readonly ILegalAcceptanceStore? _legal;
public SettingsRecorderPolicy(RegisteredSettings settings) => _settings = settings ?? throw new ArgumentNullException(nameof(settings));
public SettingsRecorderPolicy(RegisteredSettings settings, ILegalAcceptanceStore? legal = null)
{
_settings = settings ?? throw new ArgumentNullException(nameof(settings));
_legal = legal;
}
public async ValueTask<RecorderOptions> ResolveAsync(RecorderOptions baseline, CancellationToken ct = default)
{
@@ -25,6 +39,9 @@ public sealed class SettingsRecorderPolicy : IRecorderPolicy
int keep = await _settings.GetIntegerAsync(SettingsRegistry.RetentionRawSessionsPerGame, ct).ConfigureAwait(false);
int intervalMs = await _settings.GetIntegerAsync(SettingsRegistry.TelemetryIntervalMs, ct).ConfigureAwait(false);
bool advanced = await _settings.GetBooleanAsync(SettingsRegistry.TelemetryAdvanced, ct).ConfigureAwait(false);
bool input = await _settings.GetBooleanAsync(SettingsRegistry.CaptureInputDevices, ct).ConfigureAwait(false);
bool accepted = input && _legal is not null
&& InputTerms.Accepted((await _legal.FindAsync(InputTerms.PrivacyDocument, ct).ConfigureAwait(false))?.Version);
TimeSpan minimum = baseline.MinimumSessionLength < SessionFinalizer.MinimumSessionLength
? baseline.MinimumSessionLength
@@ -35,6 +52,8 @@ public sealed class SettingsRecorderPolicy : IRecorderPolicy
RetentionKeep = keep == 0 ? int.MaxValue : keep,
TelemetryInterval = TimeSpan.FromMilliseconds(intervalMs),
AdvancedMetrics = advanced,
InputDevices = accepted,
InputHeldForTerms = input && !accepted,
};
}
}
@@ -206,6 +206,22 @@ public static class SettingsRegistry
AgentReads = true,
};
/// <summary>
/// "Controllers and input" (owner decisions D155 and D156, 2026-11-14): whether the Agent reads, from outside the
/// game, which controllers are connected and in use, their batteries and the time of the last keyboard or mouse
/// input, and a session stores what it was played with (<c>21_INPUT_DEVICES</c>). <b>On by default</b> - and read
/// only once the Privacy Policy that describes it has been accepted on the PC (<c>Input.InputTerms</c>), which is
/// the recorder policy's to check, not this key's. Off means nothing is read or stored; a session recorded while
/// it was off is never filled in afterwards. Read at each session's start. Exactly "0" is off.
/// </summary>
public static readonly SettingDefinition CaptureInputDevices = new()
{
Key = "capture.input_devices",
Kind = SettingKind.Boolean,
Default = "1",
AgentReads = true,
};
/// <summary>FR-3.5: telemetry at 1 Hz, configurable 0.5–2 s. Milliseconds.</summary>
public static readonly SettingDefinition TelemetryIntervalMs = new()
{
@@ -284,7 +300,7 @@ public static class SettingsRegistry
public static IReadOnlyList<SettingDefinition> All { get; } =
[
UiLanguage, UiTheme, UiStartWithWindows, UiMinimizeToTray, UiHideAntiCheatHooking, UiFpsDecimals, UiHideScrollBars, UiLibraryView, UiPlayMode,
UiGameArt, UiGameArtTint, CaptureBackground, HookingKillSwitch, HookingUserModeExceptions, CaptureRunElevated, CaptureMinSessionSeconds, TelemetryIntervalMs, TelemetryAdvanced, RetentionRawSessionsPerGame,
UiGameArt, UiGameArtTint, CaptureBackground, HookingKillSwitch, HookingUserModeExceptions, CaptureRunElevated, CaptureMinSessionSeconds, CaptureInputDevices, TelemetryIntervalMs, TelemetryAdvanced, RetentionRawSessionsPerGame,
RetentionRemoveUninstalledGames, UpdateChannel, UpdateAutoCheck, PrivacyOnlineMetadata, LogDebug,
];
@@ -4,6 +4,7 @@
using System.Collections.Concurrent;
using System.Diagnostics;
using FrameLedger.Application.Advanced;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
namespace FrameLedger.Infrastructure.Telemetry;
@@ -49,6 +50,12 @@ public sealed class TelemetryPoller : ITelemetryPoller
private IDisposable? _advancedHold;
private AdvancedSnapshot? _lastAdvanced;
// Controllers and input (owner decisions D155 and D156): the Agent's one reader, of which this poller opens a
// view for its session and reads it on every tick. Null when the option is off or its terms are not accepted.
private readonly IInputDevices? _input;
private IInputActivitySource? _inputView;
private volatile GameProcess? _followed;
private Thread? _thread;
private int _queued;
private long _dropped;
@@ -65,9 +72,11 @@ public sealed class TelemetryPoller : ITelemetryPoller
/// <param name="system">The machine beside the GPU, read on the same tick (2026-09-21); owned and disposed with <paramref name="source"/> when <paramref name="ownsSource"/> is set. Null composes none, and every sample's <see cref="TelemetrySample.System"/> is empty.</param>
/// <param name="game">The game process's own memory (beta.12, D43), read on the same tick for the process <see cref="Follow"/> named; owned and disposed with the others when <paramref name="ownsSource"/> is set. Null composes none, and every sample's <see cref="TelemetrySample.Game"/> is empty.</param>
/// <param name="advanced">The Agent's shared reader of advanced metrics (owner decision D101), held while this poller runs and never owned by it: each of its ticks is attached to one sample. Null - the option is off - composes none, and every sample's <see cref="TelemetrySample.Advanced"/> is null.</param>
/// <param name="input">The Agent's one input reader (owner decisions D155 and D156), never owned by this poller: a view of it is open while the poller runs, and what it saw since the last tick is attached to each sample. Null - the option is off, or its terms are not accepted - opens none, and every sample's <see cref="TelemetrySample.Input"/> is null.</param>
public TelemetryPoller(IGpuTelemetrySource source, TelemetryPollerOptions options, TimeProvider clock, bool ownsSource = false,
ISystemTelemetrySource? system = null, IGameMemorySource? game = null, IAdvancedHardware? advanced = null)
ISystemTelemetrySource? system = null, IGameMemorySource? game = null, IAdvancedHardware? advanced = null, IInputDevices? input = null)
{
_input = input;
_source = source ?? throw new ArgumentNullException(nameof(source));
_system = system;
_game = game;
@@ -107,6 +116,9 @@ public sealed class TelemetryPoller : ITelemetryPoller
// Held from here to Dispose: the shared reader runs while a session samples, and closes some seconds after
// the last session and the page have let go (D107).
_advancedHold = _advanced?.Acquire();
// The input reader runs from its first view to its last (D155): this session's view is open from here to Dispose.
_ = InputView();
_thread = new Thread(Loop)
{
IsBackground = true,
@@ -130,14 +142,16 @@ public sealed class TelemetryPoller : ITelemetryPoller
ProcessReading game = default;
bool measured = _game is not null && _game.TryRead(out game);
IReadOnlyList<AdvancedReading>? advanced = NewAdvancedReadings();
if (!gpu && !machine && !measured && advanced is null)
InputReading? played = null;
bool read = InputView() is { } view && view.TryRead(out played);
if (!gpu && !machine && !measured && advanced is null && !read)
{
return;
}
// A tick only the machine or the game answered still carries them: the placeholder names no layer and no field.
sample ??= new GpuSample { TakenAt = _clock.GetUtcNow(), Layer = TelemetryLayer.None };
_queue.Enqueue(new TelemetrySample(_clock.GetTimestamp(), sample, system, game, advanced));
_queue.Enqueue(new TelemetrySample(_clock.GetTimestamp(), sample, system, game, advanced, played));
if (Interlocked.Increment(ref _queued) > _options.QueueCapacity && _queue.TryDequeue(out _))
{
Interlocked.Decrement(ref _queued);
@@ -163,6 +177,25 @@ public sealed class TelemetryPoller : ITelemetryPoller
return snapshot.Readings.Count > 0 ? snapshot.Readings : null;
}
/// <summary>
/// This session's view of the input reader, opened where it is first needed - <see cref="Start"/> in the Agent, the
/// first tick where a test drives the poller without its thread - and told at once whose windows are the game's.
/// Null when no reader was composed: the option is off, or its terms are not accepted.
/// </summary>
private IInputActivitySource? InputView()
{
if (_inputView is null && _input is not null && !_disposed)
{
_inputView = _input.Open();
if (_followed is { } target)
{
_inputView.Follow(target);
}
}
return _inputView;
}
public bool FollowAdapter(ulong luid) => _source is IGpuAdapterSelector selector && selector.SelectAdapter(luid);
/// <summary>The game process whose memory the next ticks read (beta.12, D43); ignored without a game source.</summary>
@@ -170,6 +203,10 @@ public sealed class TelemetryPoller : ITelemetryPoller
{
ArgumentNullException.ThrowIfNull(target);
_game?.Follow(target);
// Whose windows count as this session's game (D155). Kept, so a view opened after this is told as well.
_followed = target;
_inputView?.Follow(target);
}
public int Drain(ICollection<TelemetrySample> into)
@@ -198,6 +235,7 @@ public sealed class TelemetryPoller : ITelemetryPoller
_thread?.Join(TimeSpan.FromSeconds(2));
_stop.Dispose();
_advancedHold?.Dispose();
_inputView?.Dispose();
if (_ownsSource)
{
_source.Dispose();
@@ -3,6 +3,7 @@
using FluentAssertions;
using FrameLedger.App.Services;
using FrameLedger.Application.Input;
using FrameLedger.Shared;
namespace FrameLedger.App.Tests;
@@ -58,6 +59,22 @@ public sealed class LegalDocumentsTests
}
}
/// <summary>
/// D156: the Agent reads controllers and input only once the Privacy Policy that describes the reading has been
/// accepted. The Agent knows that document by a key and a version of its own; both must be the App's - the key
/// the Legal Gate stores an acceptance under, and a version the shipped document has reached.
/// </summary>
[Fact]
public void TheInputReadingsTermsAreThePrivacyPolicyThisBuildShips()
{
InputTerms.PrivacyDocument.Should().Be(LegalDocuments.Privacy);
LegalDocument privacy = LegalDocuments.Load(BuildLine.Main).Single(static d => string.Equals(d.Key, LegalDocuments.Privacy, StringComparison.Ordinal));
InputTerms.Accepted(privacy.Version).Should().BeTrue(
"accepting the document this build shows must be enough for the reading it describes; shipped is " + privacy.Version);
privacy.Text.Should().Contain("Controllers and input", "the document the reading waits for is the one that describes it");
}
[Fact]
public void TheVersionLineIsTheDocumentsOwn()
{
@@ -448,6 +448,32 @@ public sealed class SettingsViewModelTests
}
}
[Fact]
public async Task ControllersAndInputIsOnByDefaultAndItsToggleIsPersisted()
{
// Owner decisions D155 and D156 (2026-11-14): capture.input_devices, default 1. The Agent reads it at the next
// session's start - and uses it only once the terms that describe the reading are accepted, which is not the
// page's to decide.
await using ScratchLedger s = await ScratchLedger.OpenAsync();
Harness h = await OpenAsync(s);
h.Vm.InputDevices.Should().BeTrue("on unless switched off");
(await h.Settings.GetBooleanAsync(SettingsRegistry.CaptureInputDevices, Ct)).Should().BeTrue();
h.Vm.InputDevices = false;
Task off = h.Vm.Pending;
await off;
(await h.Settings.GetBooleanAsync(SettingsRegistry.CaptureInputDevices, Ct)).Should().BeFalse();
Harness reopened = await OpenAsync(s);
reopened.Vm.InputDevices.Should().BeFalse("the page shows what the row holds");
reopened.Vm.InputDevices = true;
Task on = reopened.Vm.Pending;
await on;
(await reopened.Settings.GetBooleanAsync(SettingsRegistry.CaptureInputDevices, Ct)).Should().BeTrue();
}
[Fact]
public async Task AdvancedMetricsIsOffByDefaultAndItsToggleIsPersisted()
{
@@ -155,6 +155,7 @@ public sealed class ViewerModeTests
[SettingsRegistry.HookingUserModeExceptions.Key] = ("IsChecked", "UserModeExceptions, Mode=TwoWay"),
[SettingsRegistry.CaptureRunElevated.Key] = ("IsChecked", "RunElevated, Mode=TwoWay"),
[SettingsRegistry.CaptureMinSessionSeconds.Key] = ("Value", "MinSessionSeconds, Mode=TwoWay"),
[SettingsRegistry.CaptureInputDevices.Key] = ("IsChecked", "InputDevices, Mode=TwoWay"),
[SettingsRegistry.TelemetryIntervalMs.Key] = ("Value", "TelemetryIntervalMs, Mode=TwoWay"),
[SettingsRegistry.TelemetryAdvanced.Key] = ("IsChecked", "AdvancedMetrics, Mode=TwoWay"),
[SettingsRegistry.RetentionRawSessionsPerGame.Key] = ("Value", "RetentionRawSessions, Mode=TwoWay"),
@@ -328,7 +328,7 @@ public sealed class SessionRecorderTests : IAsyncDisposable
private async Task<Harness> MakeAsync(bool consented = true, AntiCheatVerdict? verdict = null, int records = 3_000, FakeLiveness? liveness = null, bool poller = true,
bool clockStepsOnDrain = false, IDriverProfileSource? profiles = null, bool excepted = false, IDisplayProbe? display = null, ulong adapterLuid = 0,
AntiCheatVerdict? rescan = null, ICrashReporterSightings? reporters = null, IAdvancedHardware? advanced = null, bool advancedOn = false,
AntiCheatVerdict? rescan = null, ICrashReporterSightings? reporters = null, IAdvancedHardware? advanced = null, bool advancedOn = false, bool inputHeld = false,
InGameScript? inGame = null)
{
_db ??= await LedgerDatabase.OpenAsync(Path.Combine(_dir, LedgerPaths.DatabaseFileName), ct: TestContext.Current.CancellationToken).ConfigureAwait(false);
@@ -359,7 +359,7 @@ public sealed class SessionRecorderTests : IAsyncDisposable
games, new FakeSnapshots(), new FixedHardware(), partials,
new SessionFinalizer(sessions, new RawSeriesCodec()), new NoCrashEvents(),
_ => fakePoller, clock,
new RecorderOptions { PartialFlushInterval = TimeSpan.FromSeconds(10), MinimumSessionLength = SteppingClock.Step, AdvancedMetrics = advancedOn }, profiles: profiles,
new RecorderOptions { PartialFlushInterval = TimeSpan.FromSeconds(10), MinimumSessionLength = SteppingClock.Step, AdvancedMetrics = advancedOn, InputHeldForTerms = inputHeld }, profiles: profiles,
exceptionLapse: new UserModeExceptionLapsePolicy(store, sessions), reporters: reporters, advanced: advanced);
return new Harness { Recorder = recorder, Games = games, Sessions = sessions, Partials = partials, Clock = clock, Store = store, Poller = fakePoller };
}
@@ -811,6 +811,28 @@ public sealed class SessionRecorderTests : IAsyncDisposable
}
}
/// <summary>
/// D156: with the option on and the Privacy Policy that describes the reading not accepted yet, the session reads
/// nothing of controllers or of the keyboard and mouse - and says so, so that "nothing was read" has its reason
/// beside it. A session that was not held back says nothing.
/// </summary>
[Theory]
[InlineData(true)]
[InlineData(false)]
public async Task ASessionWhoseInputReadingWaitsForTheTermsSaysSoInItsNotes(bool held)
{
Harness h = await MakeAsync(inputHeld: held);
RecordedSession r = await h.Recorder.RecordAsync(Request(), TestContext.Current.CancellationToken);
h.Partials.Created[r.Row.SessionGuid].Notes.Count(static n => string.Equals(n.Text, SessionRecorder.InputHeldNote, StringComparison.Ordinal))
.Should().Be(held ? 1 : 0);
SessionRow row = h.Sessions.Stored.Single().Row;
row.InputObservedMs.Should().BeNull("nothing was read either way: the harness composes no input reader");
CaptureNotes.Parse(row.CaptureNotes).InputHeldForTerms.Should().Be(held, "the stored notes say it, where the App reads it");
CaptureNotes.Parse(row.CaptureNotes).End.Should().NotBeNullOrEmpty("the slot is added to the notes, not put in their place");
}
[Fact]
public async Task WithAdvancedMetricsOffTheSharedReaderIsNeverHeldAndTheSessionStoresNothingOfThem()
{
@@ -2,6 +2,7 @@
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Application.Persistence;
using FrameLedger.Application.Recording;
using FrameLedger.Application.Settings;
@@ -98,4 +99,81 @@ public sealed class RegisteredSettingsTests
RecorderOptions bounded = await policy.ResolveAsync(baseline with { MinimumSessionLength = TimeSpan.FromSeconds(8) }, Ct);
bounded.MinimumSessionLength.Should().Be(TimeSpan.FromSeconds(8));
}
/// <summary>
/// D156: controllers and input are read when the option is on - it is, unless switched off - AND the Privacy
/// Policy that describes the reading has been accepted on this PC. The Agent starts at logon, before the App has
/// shown a new document; until it has, a session reads nothing and says why.
/// </summary>
[Theory]
[InlineData(null, null, false, true)] // nothing accepted yet
[InlineData(null, "2.21", false, true)] // the version before the one that describes it
[InlineData(null, "2.22", true, false)]
[InlineData(null, "2.30", true, false)]
[InlineData(null, "3.0", true, false)]
[InlineData("1", "2.22", true, false)]
[InlineData("0", "2.22", false, false)] // switched off: not read, and not "held"
[InlineData("0", null, false, false)]
[InlineData("yes", "2.22", true, false)] // a row that is not 0 or 1 reads as the default, which is on
public async Task TheInputReadingNeedsTheOptionOnAndTheTermsThatDescribeItAccepted(string? row, string? accepted, bool reads, bool held)
{
var store = new MemoryStore();
if (row is not null)
{
store.Rows["capture.input_devices"] = row;
}
var legal = new MemoryAcceptance();
if (accepted is not null)
{
await legal.RecordAsync(new LegalAcceptance(InputTerms.PrivacyDocument, accepted, DateTimeOffset.UnixEpoch), Ct);
}
RecorderOptions options = await new SettingsRecorderPolicy(new RegisteredSettings(store), legal).ResolveAsync(new RecorderOptions(), Ct);
options.InputDevices.Should().Be(reads);
options.InputHeldForTerms.Should().Be(held);
}
[Fact]
public async Task WithNoAcceptanceStoreNothingCanBeShownAcceptedAndNothingIsRead()
{
RecorderOptions options = await new SettingsRecorderPolicy(new RegisteredSettings(new MemoryStore())).ResolveAsync(new RecorderOptions(), Ct);
options.InputDevices.Should().BeFalse("an operator's console has no Legal Gate behind it");
options.InputHeldForTerms.Should().BeTrue();
}
[Theory]
[InlineData("2.22", true)]
[InlineData("2.23", true)]
[InlineData("2.100", true)] // compared as numbers: 100 is after 22
[InlineData("3.0", true)]
[InlineData(" 2.22 ", true)]
[InlineData("2.21", false)]
[InlineData("2.9", false)] // 9 is before 22
[InlineData("1.99", false)]
[InlineData("2", false)]
[InlineData("2.22.1", false)]
[InlineData("two", false)]
[InlineData("-2.22", false)]
[InlineData("", false)]
[InlineData(null, false)]
public void TheTermsAreAcceptedFromTheVersionThatFirstDescribedTheReading(string? version, bool accepted) =>
InputTerms.Accepted(version).Should().Be(accepted);
private sealed class MemoryAcceptance : ILegalAcceptanceStore
{
private readonly Dictionary<string, LegalAcceptance> _rows = new(StringComparer.Ordinal);
public ValueTask<LegalAcceptance?> FindAsync(string document, CancellationToken ct = default) => ValueTask.FromResult(_rows.GetValueOrDefault(document));
public ValueTask<IReadOnlyList<LegalAcceptance>> ListAsync(CancellationToken ct = default) => ValueTask.FromResult<IReadOnlyList<LegalAcceptance>>([.. _rows.Values]);
public ValueTask RecordAsync(LegalAcceptance acceptance, CancellationToken ct = default)
{
_rows[acceptance.Document] = acceptance;
return ValueTask.CompletedTask;
}
}
}
@@ -80,8 +80,10 @@ public sealed class SettingsRegistryTests
// capture.background left in beta.12: it was listed here and no Agent code ever read it; the key is reserved.
// retention.remove_uninstalled_games joined in beta.19 (D55): the detection sweep reads it at every pass.
// telemetry.advanced joined on 2026-11-11 (D101): Advanced metrics, off by default, read at each session's start.
// capture.input_devices joined on 2026-11-14 (D155, D156): controllers and input, on by default, read at each
// session's start - and used only once the terms that describe it are accepted, which is the policy's to check.
agent.Should().BeEquivalentTo(["hooking.kill_switch", "hooking.usermode_ac_exceptions", "capture.run_elevated",
"capture.min_session_s", "telemetry.interval_ms", "telemetry.advanced", "retention.raw_sessions_per_game", "retention.remove_uninstalled_games"]);
"capture.min_session_s", "capture.input_devices", "telemetry.interval_ms", "telemetry.advanced", "retention.raw_sessions_per_game", "retention.remove_uninstalled_games"]);
agent.Should().OnlyContain(static k => k.StartsWith("hooking.", StringComparison.Ordinal) || k.StartsWith("capture.", StringComparison.Ordinal)
|| k.StartsWith("telemetry.", StringComparison.Ordinal) || k.StartsWith("retention.", StringComparison.Ordinal));
}
@@ -2,6 +2,7 @@
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using FluentAssertions;
using FrameLedger.Application.Input;
using FrameLedger.Application.Telemetry;
using FrameLedger.Infrastructure.Telemetry;
@@ -153,6 +154,93 @@ public sealed class TelemetryPollerTests
game.Disposed.Should().BeTrue("the poller owns the game source with the layers");
}
private sealed class FakeInput : IInputDevices
{
public List<FakeView> Views { get; } = [];
public IInputActivitySource Open()
{
var view = new FakeView();
Views.Add(view);
return view;
}
}
private sealed class FakeView : IInputActivitySource
{
public List<GameProcess> Followed { get; } = [];
public InputReading? Next { get; set; }
public bool Disposed { get; private set; }
public void Follow(GameProcess target) => Followed.Add(target);
public bool TryRead([System.Diagnostics.CodeAnalysis.NotNullWhen(true)] out InputReading? reading)
{
reading = Next;
Next = null;
return reading is not null;
}
public void Dispose() => Disposed = true;
}
/// <summary>
/// D155: what the session was played with rides the same tick. The poller opens ONE view of the Agent's reader,
/// tells it whose windows are the game's - a process named before the view existed included - attaches what the
/// view saw to the sample, queues a tick only the view answered, and closes the view when it is disposed.
/// </summary>
[Fact]
public void WhatTheSessionWasPlayedWithRidesTheSameTickThroughOneViewOfTheReader()
{
using var layer = new FakeLayer(TelemetryLayer.Lhm);
var input = new FakeInput();
var poller = new TelemetryPoller(layer, new TelemetryPollerOptions(), new ManualTimeProvider(), input: input);
GameProcess before = GameProcess.Unpinned([new GameProcessId(4242, DateTimeOffset.UnixEpoch)]);
GameProcess after = GameProcess.Unpinned([new GameProcessId(4243, DateTimeOffset.UnixEpoch)]);
input.Views.Should().BeEmpty("constructing a poller opens nothing");
poller.Follow(before);
layer.Publish(null);
poller.PollOnce();
FakeView view = input.Views.Should().ContainSingle().Subject;
view.Followed.Should().Equal(before);
poller.Queued.Should().Be(0, "nothing answered, the view included");
var played = new InputReading { SpanMs = 1000, ObservedMs = 1000, ForegroundMs = 900, ControllerMs = 900 };
view.Next = played;
poller.Follow(after);
poller.PollOnce();
poller.PollOnce();
var drained = new List<TelemetrySample>();
poller.Drain(drained).Should().Be(1, "a tick only the input view answered is still a sample; the next one, with nothing, is not");
drained[0].Input.Should().BeSameAs(played);
drained[0].Sample.Layer.Should().Be(TelemetryLayer.None);
view.Followed.Should().Equal(before, after);
input.Views.Should().ContainSingle("one view for the session, however many ticks");
poller.Dispose();
view.Disposed.Should().BeTrue("the reader runs from its first view to its last: the poller gives its view back");
poller.PollOnce();
input.Views.Should().ContainSingle("a disposed poller opens no view");
}
[Fact]
public void WithNoInputReaderComposedNoSampleCarriesAnInputReading()
{
using var layer = new FakeLayer(TelemetryLayer.Lhm);
layer.Publish(layer.Sample(_t0, load: 50));
using var poller = new TelemetryPoller(layer, new TelemetryPollerOptions(), new ManualTimeProvider());
poller.PollOnce();
var drained = new List<TelemetrySample>();
poller.Drain(drained).Should().Be(1);
drained[0].Input.Should().BeNull("the option is off, or the terms that describe the reading are not accepted: nothing is read");
}
[Fact]
public void WithNoSystemSourceEverySampleCarriesAnEmptyReading()
{
+51 -18
View File
@@ -5,7 +5,8 @@
<#
.SYNOPSIS
What the shipped Agent costs while it records a session: processor time per second of session, measured on the
real FrameLedger.Agent.exe, with Advanced metrics off and on.
real FrameLedger.Agent.exe - with nothing optional read, with controllers and input read, and with Advanced
metrics on.
.DESCRIPTION
docs/20_OPEN_QUESTIONS.md §M16 (owner decision D110, 2026-11-11): a number read off a probe is not the number of
@@ -22,21 +23,34 @@
run says little. Each mode is run at two lengths and the cost per second is the slope between them:
(processor time of the long run - of the short run) / (long - short).
Three modes since 0.1.0-beta.50 (owner decisions D155 and D156): `baseline` has controllers-and-input and
Advanced metrics both off; `input` switches controllers-and-input on AND writes the acceptance of the Privacy
Policy that describes it into the scratch ledger - without it the Agent reads nothing, by design; `advanced`
switches Advanced metrics on instead. The input mode measures the reader with whatever controllers this PC has
connected, which on the developer's PC is none: what a controller that sends some hundreds of reports a second
costs is not measured here (docs/20_OPEN_QUESTIONS.md section M17).
Developer tool, not a gate: it needs a release build (./build.ps1 native, then a Release build of the solution),
Python 3 on the path to write one row of the scratch ledger's `settings` table, and a few minutes.
Python 3 on the path to write rows of the scratch ledger's `settings` and `legal_acceptance` tables, and a few
minutes.
.PARAMETER Seconds
The two session lengths, short then long.
.PARAMETER Repeats
How many times each (mode, length) is run; the median is reported.
.PARAMETER Keep
Leave the scratch folder - its ledger and the Agent's logs - where it is and print its path, to look at what the
sessions stored. It is under the temporary folder, never the profile's.
#>
[CmdletBinding()]
param(
[string]$RepoRoot = (Split-Path $PSScriptRoot -Parent),
[int[]]$Seconds = @(30, 90),
[int]$Repeats = 2,
[string]$Configuration = 'Release'
[string]$Configuration = 'Release',
[switch]$Keep
)
Set-StrictMode -Version Latest
@@ -61,12 +75,30 @@ New-Item -ItemType Directory -Force $data | Out-Null
$target = Join-Path $scratch "hook-harness-$run.exe"
Copy-Item $harness $target
function Set-Advanced([bool]$On) {
# What each mode writes into the scratch ledger before its captures.
$modes = [ordered]@{
baseline = @{ Advanced = '0'; Input = '0'; Terms = $false }
input = @{ Advanced = '0'; Input = '1'; Terms = $true }
advanced = @{ Advanced = '1'; Input = '0'; Terms = $false }
}
function Set-Mode([string]$Name) {
$db = Join-Path $data 'ledger.db'
$value = if ($On) { '1' } else { '0' }
$code = "import sqlite3,sys; c=sqlite3.connect(sys.argv[1]); c.execute('INSERT INTO settings(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value', ('telemetry.advanced', sys.argv[2])); c.commit(); c.close()"
& python -c $code $db $value
if ($LASTEXITCODE -ne 0) { throw 'could not write telemetry.advanced into the scratch ledger (is Python 3 on the path?)' }
$m = $modes[$Name]
$terms = if ($m.Terms) { '1' } else { '0' }
$code = @'
import sqlite3, sys
c = sqlite3.connect(sys.argv[1])
for key, value in (('telemetry.advanced', sys.argv[2]), ('capture.input_devices', sys.argv[3])):
c.execute('INSERT INTO settings(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value', (key, value))
c.execute("DELETE FROM legal_acceptance WHERE doc = 'privacy'")
if sys.argv[4] == '1':
c.execute("INSERT INTO legal_acceptance(doc, version, accepted_at) VALUES('privacy', '2.22', 0)")
c.commit()
c.close()
'@
& python -c $code $db $m.Advanced $m.Input $terms
if ($LASTEXITCODE -ne 0) { throw "could not write the mode '$Name' into the scratch ledger (is Python 3 on the path?)" }
}
function Measure-Capture([int]$Length) {
@@ -108,27 +140,28 @@ try {
# The first run creates and migrates the scratch ledger; it is not measured.
$null = Measure-Capture 5
$rows = @()
foreach ($mode in $false, $true) {
Set-Advanced $mode
foreach ($mode in $modes.Keys) {
Set-Mode $mode
foreach ($length in $Seconds) {
foreach ($i in 1..$Repeats) {
$m = Measure-Capture $length
$rows += [pscustomobject]@{ Advanced = $mode; Seconds = $length; CpuMs = [Math]::Round($m.CpuMs); PeakMiB = $m.PeakMiB; Layers = $m.Layers }
Write-Host (" advanced={0,-5} {1,3} s cpu {2,6:N0} ms peak {3,6:N1} MiB {4}" -f $mode, $length, $m.CpuMs, $m.PeakMiB, $m.Layers)
$rows += [pscustomobject]@{ Mode = $mode; Seconds = $length; CpuMs = [Math]::Round($m.CpuMs); PeakMiB = $m.PeakMiB; Layers = $m.Layers }
Write-Host (" {0,-8} {1,3} s cpu {2,6:N0} ms peak {3,6:N1} MiB {4}" -f $mode, $length, $m.CpuMs, $m.PeakMiB, $m.Layers)
}
}
}
Write-Host ''
foreach ($mode in $false, $true) {
$short = Median @($rows | Where-Object { $_.Advanced -eq $mode -and $_.Seconds -eq $Seconds[0] } | ForEach-Object CpuMs)
$long = Median @($rows | Where-Object { $_.Advanced -eq $mode -and $_.Seconds -eq $Seconds[1] } | ForEach-Object CpuMs)
foreach ($mode in $modes.Keys) {
$short = Median @($rows | Where-Object { $_.Mode -eq $mode -and $_.Seconds -eq $Seconds[0] } | ForEach-Object CpuMs)
$long = Median @($rows | Where-Object { $_.Mode -eq $mode -and $_.Seconds -eq $Seconds[1] } | ForEach-Object CpuMs)
$perSecond = ($long - $short) / ($Seconds[1] - $Seconds[0])
$peak = ($rows | Where-Object { $_.Advanced -eq $mode } | Measure-Object PeakMiB -Maximum).Maximum
Write-Host ("advanced={0,-5}: {1:N1} ms of processor time per second of session = {2:N2} % of one core (median {3:N0} ms over {4} s, {5:N0} ms over {6} s); peak working set {7:N1} MiB" -f `
$peak = ($rows | Where-Object { $_.Mode -eq $mode } | Measure-Object PeakMiB -Maximum).Maximum
Write-Host ("{0,-8}: {1:N1} ms of processor time per second of session = {2:N2} % of one core (median {3:N0} ms over {4} s, {5:N0} ms over {6} s); peak working set {7:N1} MiB" -f `
$mode, $perSecond, ($perSecond / 10), $short, $Seconds[0], $long, $Seconds[1], $peak)
}
}
finally {
Remove-Item -Recurse -Force $scratch -ErrorAction SilentlyContinue
if ($Keep) { Write-Host "scratch kept: $scratch" }
else { Remove-Item -Recurse -Force $scratch -ErrorAction SilentlyContinue }
}