poli0981andClaude Opus 5 81011315ab feat(tier2): PresentMon is dropped, and Tier 2 keeps its place while losing its mechanism (#96)
Owner decision 2026-08-27. §S31 retired PresentMon as a measurement ORACLE (row
P2); this removes it as an IMPLEMENTATION. It is not bundled, not fetched, not
used, and tools/frametype-oracle.ps1 -- the parser written for its output -- is
deleted with it, along with its build.ps1 gate.

THE DISTINCTION THIS COMMIT IS BUILT ON: dropping PresentMon is not dropping
Tier 2. The owner's earlier instruction was explicit that a release "will use a
different approach", so Tier 2 keeps its place in the design and loses its named
tool. Nothing here rewrites the tier out of the product; everything here stops
naming an implementation nobody chose.

TWELVE DOCUMENTS NAMED IT AS THE MECHANISM AND EVERY ONE IS CORRECTED:
CLAUDE.md's pinned-stack row; README's capture-tier table AND its safety row;
01_ARCHITECTURE's tier table and ADR-3; 03_METRICS rung 2; 04_CAPTURE's source
table and tier selection; 05_DETECTION's two Tier-2 rows; 07_IPC's
PresentMonMissing error code; 12_BUILD; 14_TESTING's CSV-parser row;
15_ROADMAP's P2 phase and v2 backlog; and legal/THIRD_PARTY_NOTICES.md plus
legal/licenses/README.md. Struck in place rather than deleted wherever the
reasoning is what a later reader needs.

THE NOTICES ROW AND license-check's CLAIM HAD TO GO TOGETHER, AND THAT IS THE
GATE WORKING. tools/license-check.ps1 bound `Intel PresentMon` to
assets/native/PresentMon.exe BIDIRECTIONALLY, so removing the row alone fails
with "no table row mentions Intel PresentMon, so its bundling claim cannot be
checked". Removing a claim is a deliberate act and is recorded as one, in the
notices file itself. legal/licenses/README.md also listed a presentmon-MIT.txt
that never existed -- a row pointing at a file nobody had shipped.

§M1, §M2 AND §M6 CLOSE BY DECISION, NOT BY MEASUREMENT, and each row says which.
They were questions about a tool that no longer has a subject. §M2's answers are
kept in full -- the binary's identity, its refusal to run unelevated, the 24-column
set -- because every one of them cost a measurement, and a closed row that deletes
its evidence is how the next person re-runs it.

§G IS NOT CLOSED. IT GETS BIGGER. "Is the binary committed or fetched?" becomes
"by what mechanism does a shipped build reach Tier 2 at all?", and nothing in
this repository names one. The row now carries its own constraints: README's
capture-tier table and its SAFETY row, legal/DISCLAIMER.md §73 and
legal/EULA.md §33 all describe a no-injection mode as THE DEFAULT for uncertain
cases; ETW needs elevation regardless of tool (§M6); and 15_ROADMAP has no v2
fallback any more either.

WHAT THIS COSTS USERS, PUT WHERE THEY WILL READ IT. README's safety row promised
"always a way out". It now carries, in that row, that the mode is unbuilt and has
no chosen mechanism, and that A REFUSED OR UNHOOKABLE TITLE GETS TIER 3 --
session duration and hardware telemetry. Said in the safety table rather than in
a footnote, because a way out that does not exist is the wrong thing to be
reassured by.

THE TWO LEGAL DOCUMENTS ARE DELIBERATELY NOT TOUCHED. DISCLAIMER §73 and EULA §33
still call the no-injection mode "the default" without the qualification the
README now carries. That is a real gap, §G names both files, and changing a legal
document is not a cleanup -- it is an owner decision with its own review.

AND THE DISCRIMINATOR RUN PRODUCED NOTHING, so it settled nothing. The command I
supplied targeted explorer.exe, which may present nothing PresentMon tracks, so
"no CSV" and "no FrameType column" are indistinguishable -- the §Traps entry
about a canary that dies before reaching the gate, in a command I wrote. A target
known to present would have settled it. Recorded in §S31 and spike-notes §11 so
nobody re-runs it believing it is untried, and moot either way now.

Also corrected while in the file: CLAUDE.md's tools list omitted
hookinventory-check. Same class as §R10 and found by counting the directory
rather than by reading the line.

./build.ps1 check with no switches: PASSED, one skipped gate (resx-audit, which
does not exist). license-check green -- the row/claim pair was removed
consistently, which is the only way that gate can stay green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>


---

docs: two pointers to a script that was never landed, left by closing #94

`spike-notes` §11 and `HANDOFF` item 3 both credited the §S31 run to
`tools/s31-capture.ps1`. That script lived in #94, which was closed unmerged
because it drives PresentMon and PresentMon was dropped the same day. So two
documents on `main` name a file the repository does not contain -- a reader
follows the pointer and finds nothing.

Caught by grepping `main` for the name after the close, not by reading the
diff: the reference was correct when it was written and became wrong when a
DIFFERENT pull request was closed. That is the "a document can go stale by NOT
being touched" entry arriving from the one direction §Traps does not describe --
staleness caused by a decision taken elsewhere.

Both now describe the run without naming an artifact, and `spike-notes` says
explicitly that the script is not in this repository so nobody goes looking.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-28 09:57:36 +07:00
2026-08-02 14:29:45 +07:00

FrameLedger

A local-first game performance ledger for Windows. FrameLedger records frame times, FPS metrics, hardware telemetry, and — crucially — the settings your game is actually rendering with, every time you play. Then it turns your history into charts, so you can see exactly how a patch, a driver update, or a settings change affected performance.

No telemetry. No accounts. All data stays on your machine.

⚠ Accuracy note — 2026-08-05. This README describes the finished product; the software is pre-alpha and most of what follows is not built yet. Added because every other user-facing document here carries such a note and this one — the first thing anyone reads — carried none, while legal/DISCLAIMER.md had already been through two rounds of exactly this correction.

What actually works today: frame boundaries, frame times and output resolution, from a Direct3D 11/12 present hook, written into shared memory and read back by the Agent's ring reader. Plus, for titles that go through NVIDIA Streamline, which upscaler is executing and whether Ray Reconstruction is running with it — identity only, not the quality preset and not the render resolution. The anti-cheat guard runs all of its pre-injection checks and refuses.

What does not yet exist, and is written above in the present tense: every bullet under What makes it different except output resolution and upscaler identity — no quality preset, render resolution, frame generation, ray tracing, VRAM, shader-stutter or Reflex hook has been written. The capture side says so in its own data rather than defaulting to "none" (docs/03_METRICS.md, CLAUDE.md rules 6 and 7). There is also no storage, no charts, no library import, no UI and no installer.

The two rows that describe safety behaviour are qualified where they sit, rather than here, because that is where a reader checking their own risk will look.

What makes it different

Most tools tell you your frame rate. FrameLedger tells you what produced that frame rate:

  • Real render resolution vs output resolution — the actual internal resolution, not the one in the settings menu.
  • Which upscaler is running, at which quality preset — DLSS / FSR / XeSS, read from the API the game calls, not guessed from files on disk.
  • Frame Generation, measured — native and generated frames counted separately. Always shown as 62 → 118 FPS (×1.9 FG), never as one inflated number.
  • Ray tracing, actually detected — including inline ray tracing (DXR 1.1 RayQuery), which frame-counting tools miss entirely.
  • Per-process VRAM and whether the driver was exceeding its budget (a real stutter explanation).
  • Shader-compilation stutter attribution — which frame spikes were pipeline compiles.
  • PC latency when the game uses Reflex.

Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io library import. UI in English / Tiếng Việt / 日本語.

How it works — and the trade-off, stated plainly

None of the settings data above is visible from outside a game process. To read it, FrameLedger loads a component into the game and observes the calls the game makes to graphics APIs — the same class of technique used by frame-rate overlays, recording software, and post-processing injectors. Vulkan titles use a standard Vulkan layer instead.

That carries a real risk: anti-cheat systems can detect injected code and may ban accounts.

FrameLedger is built to keep that risk small and to be honest about it:

Safeguard
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

⚠ Half of this is built. The pre-injection refusal is real and runs every documented check. The in-session re-scan does not run at all: 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 — but nothing yet drives the scanner during a session, so nothing ever tells it. legal/DISCLAIMER.md §2 states this in full. The Vulkan layer additionally intercepts nothing yet, so there is no Vulkan capture to stop.
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
Always a way out A no-injection mode (ETW-based) is the default for anything the software is unsure about. It needs the Agent running elevated, because Windows restricts the trace sessions it uses — FrameLedger tells you when that applies rather than silently recording less

⚠ None of this is built, and as of 2026-08-27 it does not even have a chosen mechanism. The design named Intel PresentMon; that was dropped after measurement, and no replacement has been picked (docs/20_OPEN_QUESTIONS.md §G). Today a refused or unhookable title gets Tier 3 — session duration and hardware telemetry — not a degraded measurement. Said here rather than in a footnote, because this row is in the SAFETY table and a way out that does not exist is the wrong thing to be reassured by

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 and docs/19_SAFETY_AND_ANTICHEAT.md before enabling it for anything.

Capture tiers

Tier How What you get
1 Injected hooks (opt-in, per game) Everything above
2 ETW, no injection — mechanism not chosen, nothing built Frame times, FPS, lows, present mode. (An earlier design named Intel PresentMon and promised coarse frame-generation inference. PresentMon was dropped on 2026-08-27 after its FrameType column classified every frame of a ×4 capture as an application frame; there is no Tier-2 frame-generation signal today and none is claimed.)
3 None Session duration + hardware telemetry

The tier is recorded on every session and shown in the UI. Metrics unavailable at a session's tier read N/A — FrameLedger never substitutes an estimate for a measurement.

Architecture

Component Runs as Role
FrameLedger.exe Standard user Fluent desktop UI (WPF + WPF UI), charts, library, settings
FrameLedger.Agent.exe Standard user (elevation optional) Injection control, safety guard, data collection, GPU telemetry, storage
FrameLedger.Overlay.dll Inside the game C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks
FrameLedger.VkLayer.dll Inside the game Vulkan implicit layer (Vulkan titles use this instead of injection)

Elevation is optional for Tier-1 hooked capture — that is the normal path and it runs as a standard user. It unlocks CPU temperature sensors, attaching to games that themselves run elevated, and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.

Requirements

  • Windows 10 (22H2) or Windows 11, 64-bit
  • A 64-bit DirectX 11/12, Vulkan, or OpenGL game for full (Tier-1) capture. 32-bit games — including most DirectX 9 titles — are supported at Tier 2 only
  • Optional: PawnIO for CPU temperature (GPU telemetry works without it, through your graphics driver's own libraries)

Install

  1. Download the latest FrameLedger-win-Setup.exe from Releases.
  2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then More info → Run anyway.
  3. Follow the first-run Legal Gate and Agent setup. Nothing is injected until you enable it for a specific game.

Privacy

Everything lives locally in %LOCALAPPDATA%\FrameLedger. The only network calls FrameLedger will ever make: update checks against GitHub Releases, detection-rules updates from this repository, and optional, opt-in store metadata lookups. Bug reports are always built locally, shown to you, and submitted by you. Full policy: legal/PRIVACY_POLICY.md.

Today it makes none of them. The rules feed in particular does not exist — the blocklist ships with the build and updates only when you install a new one (docs/20_OPEN_QUESTIONS.md §S20). Listing a fetch that has no code is over-disclosure, and this document was already corrected once for describing a weekly outbound request the software never made.

License

GPL-3.0-only. See LICENSE. Third-party components: legal/THIRD_PARTY_NOTICES.md.

GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras such as Reflex latency. No Intel or AMD GPU SDK is bundled — see docs/18_GPU_VENDOR_APIS.md for why.

Documentation

Developer/AI-facing docs in docs/. Start with CLAUDE.md, then docs/19_SAFETY_AND_ANTICHEAT.md (which constrains everything else), then docs/01_ARCHITECTURE.md.

Reporting a safety gap

If you find a game with anti-cheat that FrameLedger fails to detect, please open an issue — that is a safety bug and is treated with the same priority as a security report.

How fast a fix can reach you, stated accurately. Blocklist entries are data rather than code, so a fix is a one-line change here. But the software has no rules-update path yet: it installs the blocklist that shipped with your build and never fetches another (docs/20_OPEN_QUESTIONS.md §S20, feed half). Until that exists, a blocklist fix reaches you only when you install a new release. This paragraph previously said the opposite, and the sentence it said it in was a response-time promise attached to a security-priority commitment.


Status: pre-alpha, under active development. Roadmap: docs/15_ROADMAP.md.

S
Description
No description provided
Readme GPL-3.0
10 MiB
0 Stars 1 Watchers 0 Forks
Languages
C# 73.7%
C++ 20.6%
PowerShell 4.4%
CMake 1%
C 0.3%