Compare commits
57
Commits
No files matched your search
@@ -116,6 +116,22 @@ jobs:
|
||||
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
|
||||
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
|
||||
|
||||
# The Overlay's build id is `git describe --dirty` at CMake's configure
|
||||
# (src/native/FrameLedger.Shm/CMakeLists.txt), and the next step edits tracked
|
||||
# files: every release until beta.18 shipped "<tag>-dirty". So the id is read
|
||||
# here, from the clean checkout, and handed to CMake through the environment;
|
||||
# buildid-check reads it back out of the published binaries.
|
||||
- name: Build id (the clean checkout)
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$id = "$(git describe --always --dirty --abbrev=12)".Trim()
|
||||
if ($LASTEXITCODE -ne 0 -or -not $id) { throw 'git describe failed' }
|
||||
if ($id.EndsWith('-dirty')) { throw "the checkout is dirty before the release has touched it: $id" }
|
||||
if ($id.Length -gt 31) { throw "build id '$id' is $($id.Length) characters; FlShmHandshake::buildId holds 31" }
|
||||
"FL_BUILD_ID=$id" >> $env:GITHUB_ENV
|
||||
Write-Host "FL_BUILD_ID = $id"
|
||||
|
||||
# 12_BUILD §Release-time token substitution: the effective date of a legal
|
||||
# document is the date it ships. The only placeholder that survives into the
|
||||
# repository, substituted here and nowhere else; the App embeds legal/*.md at
|
||||
@@ -149,9 +165,14 @@ jobs:
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$v = '${{ steps.version.outputs.version }}'
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
||||
# beta.12: the App's links into the repository open the documents of THIS release (Services/RepositoryLinks.cs):
|
||||
# the tag, or for a rehearsal - which has no tag - the commit it was built from.
|
||||
$ref = if ('${{ steps.version.outputs.dry_run }}' -eq 'true') { '${{ github.sha }}' } else { "v$v" }
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
|
||||
if ($LASTEXITCODE -ne 0) { throw 'App publish failed' }
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -o out/app
|
||||
# beta.14 (D50): the same ref for the Agent - Directory.Build.props stamps it on every assembly, and both
|
||||
# publishes build the same libraries into this one folder.
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:Version=$v -p:FrameLedgerSourceRef=$ref -o out/app
|
||||
if ($LASTEXITCODE -ne 0) { throw 'Agent publish failed' }
|
||||
|
||||
# A self-contained package redistributes the .NET runtime, and its licence and
|
||||
@@ -178,7 +199,7 @@ jobs:
|
||||
}
|
||||
Get-ChildItem $dest | ForEach-Object { Write-Host (" {0,-64} {1,8:N0}" -f $_.Name, $_.Length) }
|
||||
|
||||
# What ships is what matters: the two entry points and the four shipped native
|
||||
# What ships is what matters: the two entry points and the five shipped native
|
||||
# binaries (versioninfo-check's list) must be in the tree, and the unshipped
|
||||
# capture host must not be (package-closure-check proves it statically; this
|
||||
# reads the directory).
|
||||
@@ -186,14 +207,18 @@ jobs:
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'rules/detection-rules.json',
|
||||
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
|
||||
$required = 'FrameLedger.exe', 'FrameLedger.Agent.exe', 'FrameLedger.Overlay.dll', 'FrameLedger.VkLayer.dll', 'FrameLedger.Guard.dll', 'FrameLedger.NvapiBridge.dll', 'FrameLedger.ProcessStats.dll', 'rules/detection-rules.json',
|
||||
'licenses/nuget/INDEX.md', 'licenses/THIRD_PARTY_NOTICES.md', 'licenses/FrameLedger-GPL-3.0.txt', 'licenses/NOTICE.txt', 'licenses/mpl-2.0.txt', 'licenses/apache-2.0.txt'
|
||||
$missing = @($required | Where-Object { -not (Test-Path (Join-Path out/app $_)) })
|
||||
if ($missing.Count -gt 0) { throw "out/app is missing: $($missing -join ', ')" }
|
||||
if (Test-Path out/app/FrameLedger.CaptureHost.exe) { throw 'out/app contains the unshipped capture host (12_BUILD: exactly two roots)' }
|
||||
if (@(Get-ChildItem out/app/licenses/dotnet -File -ErrorAction SilentlyContinue).Count -lt 2) { throw 'out/app/licenses/dotnet holds fewer than two files -- the runtime licence step did not run' }
|
||||
./tools/versioninfo-check.ps1 -BuildDir out/app
|
||||
# beta.14 (D50): the managed half too - the eight managed binaries, carrying the tag's full version.
|
||||
./tools/versioninfo-check.ps1 -BuildDir out/app -ManagedDir out/app -ExpectedProductVersion '${{ steps.version.outputs.version }}'
|
||||
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-check over the published tree' }
|
||||
# beta.18: the native binaries carry the build id read from the clean checkout, exactly - never "<tag>-dirty".
|
||||
./tools/buildid-check.ps1 -BuildDir out/app -Expected $env:FL_BUILD_ID
|
||||
if ($LASTEXITCODE -ne 0) { throw 'buildid-check over the published tree' }
|
||||
$size = (Get-ChildItem out/app -Recurse -File | Measure-Object Length -Sum).Sum / 1MB
|
||||
Write-Host ("published tree: {0:N0} MB" -f $size)
|
||||
|
||||
@@ -207,17 +232,53 @@ jobs:
|
||||
# ledger.db, logs, the layer manifest). The same id would put the install inside
|
||||
# the ledger's folder and have the uninstaller remove every session without the
|
||||
# question 12_BUILD promises. The title the user sees is still "FrameLedger".
|
||||
# A DELTA (beta.13): vpk pack diffs against the newest full package already in --outputDir, and until beta.13 that
|
||||
# directory was always empty - so no release carried a delta and every update downloaded the whole package
|
||||
# (11_UPDATER §Built). The previous release is downloaded first; what THIS pack produced is assets.win.json, and only
|
||||
# that is kept: the previous full package moves out (not uploaded, not checksummed) and the feed lists this build
|
||||
# alone, as `vpk upload github` would write it. No previous release, or a download that fails, is a full-only
|
||||
# release - said as a warning, not a stop, because it is exactly what every release before this one was.
|
||||
- name: Pack (Velopack)
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
dotnet tool install -g vpk --version 1.2.0
|
||||
if ($LASTEXITCODE -ne 0) { throw 'vpk install failed' }
|
||||
$v = '${{ steps.version.outputs.version }}'
|
||||
New-Item -ItemType Directory out/release -Force | Out-Null
|
||||
vpk download github --repoUrl "https://github.com/${{ github.repository }}" --channel win --pre --token $env:GH_TOKEN --outputDir out/release
|
||||
if ($LASTEXITCODE -ne 0) { Write-Host '::warning::the previous release could not be downloaded - this release carries a full package only' }
|
||||
Write-Host 'previous release:'
|
||||
Get-ChildItem out/release -File | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
|
||||
vpk pack --packId FrameLedger.App --packVersion $v --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
if ($LASTEXITCODE -ne 0) { throw 'vpk pack failed' }
|
||||
|
||||
$built = @((Get-Content out/release/assets.win.json -Raw | ConvertFrom-Json) | ForEach-Object { $_.RelativeFileName })
|
||||
if ($built.Count -eq 0) { throw 'vpk pack wrote no assets.win.json entries' }
|
||||
$keep = $built + @('releases.win.json', 'assets.win.json', 'RELEASES')
|
||||
New-Item -ItemType Directory out/previous -Force | Out-Null
|
||||
Get-ChildItem out/release -File | Where-Object { $keep -notcontains $_.Name } | Move-Item -Destination out/previous
|
||||
$feed = Get-Content out/release/releases.win.json -Raw | ConvertFrom-Json
|
||||
$feed.Assets = @($feed.Assets | Where-Object { $built -contains $_.FileName })
|
||||
if ($feed.Assets.Count -eq 0) { throw 'the feed lists none of this build''s packages' }
|
||||
[System.IO.File]::WriteAllText((Join-Path $PWD 'out/release/releases.win.json'), ($feed | ConvertTo-Json -Depth 8 -Compress), [System.Text.UTF8Encoding]::new($false))
|
||||
if (Test-Path out/release/RELEASES) {
|
||||
$legacy = @(Get-Content out/release/RELEASES | Where-Object { $built -contains ($_ -split ' ')[1] })
|
||||
[System.IO.File]::WriteAllLines((Join-Path $PWD 'out/release/RELEASES'), [string[]]$legacy, [System.Text.UTF8Encoding]::new($false))
|
||||
}
|
||||
|
||||
Write-Host 'this release:'
|
||||
Get-ChildItem out/release | ForEach-Object { Write-Host (" {0,-48} {1,12:N0}" -f $_.Name, $_.Length) }
|
||||
Write-Host ('feed: ' + (($feed.Assets | ForEach-Object { '{0} {1} {2}' -f $_.Type, $_.Version, $_.FileName }) -join '; '))
|
||||
if (-not (Test-Path out/release/FrameLedger.App-win-Setup.exe)) { throw 'vpk did not produce FrameLedger.App-win-Setup.exe (README §Install names it)' }
|
||||
$delta = "out/release/FrameLedger.App-$v-delta.nupkg"
|
||||
if (Get-ChildItem out/previous -Filter '*-full.nupkg' -ErrorAction SilentlyContinue) {
|
||||
if (-not (Test-Path $delta)) { throw "the previous full package was downloaded, but vpk produced no delta ($delta)" }
|
||||
} else {
|
||||
Write-Host '::warning::no previous full package - this release carries no delta'
|
||||
}
|
||||
|
||||
- name: Checksums
|
||||
shell: pwsh
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
# Gate changes to the detection + anti-cheat rules (docs/13_CI_CD.md).
|
||||
#
|
||||
# The raw file on `main` IS the distribution endpoint (docs/05_DETECTION.md),
|
||||
# so there is nothing to publish — this workflow only gates correctness. That
|
||||
# also means a bad merge ships to every user on their next rules check, which
|
||||
# is why the anticheat block gets extra scrutiny here.
|
||||
# There is nothing to publish: no rules feed exists (docs/20_OPEN_QUESTIONS.md
|
||||
# §S20 feed half), so a rules change reaches users inside a release, seeded by
|
||||
# the Agent from the packaged copy. This header said the raw file on `main` was
|
||||
# the distribution endpoint until 2026-10-04. This workflow only gates
|
||||
# correctness, and the anticheat block still gets the extra scrutiny, because
|
||||
# whatever merges here ships in the next release.
|
||||
|
||||
name: Rules
|
||||
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# The GitHub Wiki is a copy of the repository's own pages (D53/D54, the owner, 2026-10-07): wiki/ (Home, the sidebar,
|
||||
# the developer pages) and guide/ (the user guide, which is the End-user part) with LIMITATIONS.md, assembled and checked
|
||||
# by tools/wiki-build.ps1 - the check build.ps1 runs as `wiki-check`. A page edited on the Wiki tab is overwritten here;
|
||||
# edit wiki/ or guide/ instead (docs/13_CI_CD.md §wiki.yml).
|
||||
#
|
||||
# Separate from release.yml on purpose. The release stays as it was and its dry run stays a pure rehearsal; a wiki that
|
||||
# fails to publish is a red run of its own, re-run on its own, never a red release. A step after `gh release create`
|
||||
# could never be re-run at all: the release would already exist.
|
||||
#
|
||||
# A release that release.yml creates with GITHUB_TOKEN fires no `release` event for other workflows. `workflow_run` does
|
||||
# fire - the Release run itself was started by the owner's tag push - and it runs THIS file as it is on main, so the job
|
||||
# checks out the commit the release was built from (head_sha) and links the repository's files at the tag (head_branch).
|
||||
|
||||
name: Wiki
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: [Release]
|
||||
types: [completed]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
ref:
|
||||
description: 'Branch, tag or commit to build the wiki from; repository files are linked at this ref'
|
||||
required: true
|
||||
default: main
|
||||
type: string
|
||||
publish:
|
||||
description: 'Publish to the Wiki tab (off: build, check and upload the pages only)'
|
||||
required: true
|
||||
default: false
|
||||
type: boolean
|
||||
|
||||
# The repository's default token is read-only; pushing to <repo>.wiki.git needs contents: write.
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
concurrency:
|
||||
group: wiki
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
wiki:
|
||||
# A rehearsal of release.yml (workflow_dispatch) never publishes the wiki: only a run started by a pushed v* tag
|
||||
# that succeeded.
|
||||
if: >-
|
||||
github.event_name == 'workflow_dispatch' ||
|
||||
(github.event.workflow_run.conclusion == 'success' &&
|
||||
github.event.workflow_run.event == 'push' &&
|
||||
startsWith(github.event.workflow_run.head_branch, 'v'))
|
||||
runs-on: windows-latest
|
||||
timeout-minutes: 10
|
||||
env:
|
||||
# Values reach the scripts through the environment only, never pasted into them.
|
||||
WIKI_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_branch }}
|
||||
WIKI_PUBLISH: ${{ github.event_name == 'workflow_run' || inputs.publish }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
|
||||
persist-credentials: false
|
||||
|
||||
- name: Build and check the wiki
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
./tools/wiki-build.ps1 -Ref $env:WIKI_REF -Out out/wiki
|
||||
if ($LASTEXITCODE -ne 0) { throw 'wiki-build failed' }
|
||||
|
||||
- name: Upload the pages
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: wiki-${{ github.run_id }}
|
||||
path: out/wiki/**
|
||||
if-no-files-found: error
|
||||
retention-days: 14
|
||||
|
||||
- name: Publish to the Wiki tab
|
||||
if: env.WIKI_PUBLISH == 'true'
|
||||
shell: pwsh
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
run: |
|
||||
$ErrorActionPreference = 'Stop'
|
||||
gh auth setup-git
|
||||
if ($LASTEXITCODE -ne 0) { throw 'gh auth setup-git failed' }
|
||||
git clone --depth 1 "https://github.com/$env:GITHUB_REPOSITORY.wiki.git" wiki-repo
|
||||
if ($LASTEXITCODE -ne 0) { throw 'cloning the wiki failed - it must have one page created on github.com first' }
|
||||
Get-ChildItem wiki-repo -Force | Where-Object Name -ne '.git' | Remove-Item -Recurse -Force
|
||||
Copy-Item out/wiki/* wiki-repo -Recurse
|
||||
Set-Location wiki-repo
|
||||
git add -A
|
||||
git diff --cached --quiet
|
||||
if ($LASTEXITCODE -eq 0) { Write-Host "The wiki already shows $env:WIKI_REF; nothing to publish."; exit 0 }
|
||||
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' commit -q -m "wiki: $env:WIKI_REF"
|
||||
if ($LASTEXITCODE -ne 0) { throw 'commit failed' }
|
||||
# The wiki repository's branch is master (git ls-remote, 2026-10-07).
|
||||
git push origin HEAD:master
|
||||
if ($LASTEXITCODE -ne 0) { throw 'push failed' }
|
||||
Write-Host "Published the wiki at $env:WIKI_REF"
|
||||
+645
-1
@@ -10,7 +10,8 @@ bumps for a database schema or IPC protocol break (`docs/11_UPDATER.md`).
|
||||
uses it as the GitHub release body. A missing or empty `## [x.y.z]` section is a **red
|
||||
release**, not an empty note — so cutting a release means moving the `[Unreleased]` entries
|
||||
under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, then tagging
|
||||
(`docs/13_CI_CD.md` §Branch & release policy).
|
||||
(`docs/13_CI_CD.md` §Branch & release policy). *(For a pre-release, `vX.Y.Z-beta.N`, `VERSION` already holds the
|
||||
numeric core and does not move; the heading is the full version — corrected 2026-10-04.)*
|
||||
|
||||
> **Built 2026-09-14 (P4 PR-5).** From 2026-08-06 until then this paragraph said the workflow
|
||||
> "will" exist and that a missing section "will mean an empty release note"; the second half
|
||||
@@ -27,8 +28,647 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [0.1.0-beta.21] - 2026-10-13
|
||||
|
||||
**The twenty-first pre-release: an anti-cheat kept beside a game's executable found before anything is injected, four
|
||||
itch.io downloads that carry malware, documents that scroll further and smoothly, and Play.** The same unsigned
|
||||
installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.20`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.10) is shown once for you to accept. Every game is read and checked for anti-cheat once more (detection rules
|
||||
`2026.10.4`): Wuthering Waves, and any game that keeps an anti-cheat beside its executable, has its hooking turned off.
|
||||
If you installed HELLO, HELLO WORLD!, A Doll's Locket - Remake, City of Bones or Träumerei Chapter 2 from itch.io, read
|
||||
*Security* below first.
|
||||
|
||||
### Added
|
||||
|
||||
- **Play, on a game's page and on each game in the library.** Through the store that installed the game — Steam or the
|
||||
Epic Games Launcher starts it, GOG GALAXY runs it, the itch app asks which copy to launch — or started directly by
|
||||
FrameLedger, recorded from its first frame: **Settings ▸ Games ▸ Play button** switches between the two. A game no
|
||||
store installed, and a GOG game without GOG GALAXY, is started directly. FrameLedger never starts a game as
|
||||
administrator: *Start directly* does not start one that asks for it, and while FrameLedger itself runs as
|
||||
administrator, Play starts every game directly so that the game does not. A game whose recording is off is started
|
||||
only through its store. The Epic Games Launcher's link is the one its own shortcuts carry and has not been tried on a
|
||||
real Epic game yet (`docs/08_UI.md` §Games).
|
||||
- **The Privacy Policy (version 2.10)** names the store records Play and the library import read — the lists of installed
|
||||
games the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed; the import
|
||||
read the Epic and itch lists before and the policy did not say so — and that Play hands a game to its store's app,
|
||||
which may connect to its store while FrameLedger itself connects to nothing. It is shown once for you to accept.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The documents in the app scroll further and smoothly** — the user guide, Help ▸ Limitations, About's documents, the
|
||||
Legal Gate and the update notes. A wheel notch moved them a fixed short step whatever the wheel or touchpad sent;
|
||||
it now moves the number of lines Windows is set to scroll (a screen if it is set to that), about twice as far by
|
||||
default, in proportion for a touchpad, and glides there unless Windows' animations are off. At the end of the update
|
||||
notes the wheel scrolls the window instead; Ctrl+wheel still zooms. A page is drawn once when it is opened, not two or
|
||||
three times, and going back to a page you have read in the same window is immediate.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An anti-cheat kept beside a game's executable is found before anything is injected.** The safety check looked three folder
|
||||
levels into a game's install folder and no further, so an anti-cheat beside an executable that is itself three levels down
|
||||
was never seen: Wuthering Waves keeps Tencent's Anti-Cheat Expert in `Client\Binaries\Win64\AntiCheatExpert\`, its
|
||||
page read clean, and a session with hooking turned on was hooked for 37 seconds before the check that runs every 30 seconds
|
||||
met the anti-cheat's driver — and because a driver counts for the whole PC, the game's hooking stayed on. The check now also
|
||||
looks in the executable's own folder, on the game's page and before every injection. Wuthering Waves is also named by its
|
||||
Steam id (owner decision D58), and ACE's files, its second driver, its driver's service and its module are named (detection
|
||||
rules `2026.10.4`). Every game is checked for anti-cheat once more after the update; one found this way has its hooking
|
||||
turned off, as any finding does (`docs/19_SAFETY_AND_ANTICHEAT.md` §Pre-injection checks, item 4).
|
||||
- **A game's Supports card said *Not scanned yet* for a game the agent had read** whenever the game ships none of the
|
||||
upscaler, frame-generation or Vulkan files the rules name — beside a Details card the same read had filled. It says
|
||||
so now only until the agent has read the game, then *None found*.
|
||||
|
||||
### Security
|
||||
|
||||
- **Four itch.io downloads this project's documentation used as examples carry malware.** HELLO, HELLO WORLD!, A Doll's
|
||||
Locket - Remake, City of Bones and Träumerei Chapter 2 put the same 213 MB program in front of their RPG Maker game.
|
||||
Read without running it, it ships a registry file that switches off Windows' script scanning (AMSI) and adds
|
||||
Microsoft Defender exclusions, carries an encrypted payload, and checks for virtual machines and debuggers before it
|
||||
starts the game. The documentation called it a launcher and, for A Doll's Locket, said to measure it with the agent
|
||||
running as administrator: that advice is withdrawn. If you installed one of them, remove it and scan your PC.
|
||||
FrameLedger itself does not change: it reads a game's files to find its engine and anti-cheat, and does not judge
|
||||
whether a game is safe (`docs/spike-notes.md` §20).
|
||||
|
||||
## [0.1.0-beta.20] - 2026-10-12
|
||||
|
||||
**The twentieth pre-release: the engine version of Ren'Py games.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.19`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.9) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.3`).
|
||||
|
||||
### Added
|
||||
|
||||
- **The engine version of Ren'Py games**, as Unity's, Godot's and RPG Maker's have been shown since beta.19 — on the game's
|
||||
page with what it was read from, the engine's own `renpy/vc_version.py`: *Ren'Py 8.5.0*. A game whose engine names no
|
||||
version there reads as not found. Every game is read once more after the update (detection rules `2026.10.3`;
|
||||
`docs/05_DETECTION.md` §Engine version — Ren'Py).
|
||||
- **The Privacy Policy (version 2.9)** names that file among the version marks it reads; it is shown once for you to
|
||||
accept.
|
||||
|
||||
## [0.1.0-beta.19] - 2026-10-12
|
||||
|
||||
**The nineteenth pre-release: an imported game that is its own runtime and not a helper, Change executable… in the game's
|
||||
folder, the engine version of Unity, Godot and RPG Maker games, and games you uninstalled leaving the library by
|
||||
themselves.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.18`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
|
||||
Policy (2.8) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.2`).
|
||||
The agent removes the entries of games you uninstalled that have no sessions, about ten minutes after it sees them gone —
|
||||
turn **Settings ▸ Data ▸ Remove uninstalled games** off first if you want them kept. An entry an earlier import made for a
|
||||
helper is not changed: re-point it with *Change executable…*.
|
||||
|
||||
### Added
|
||||
|
||||
- **The engine version of Unity, Godot and RPG Maker games**, as Unreal Engine's has been shown since beta.10 — on the game's
|
||||
page with what it was read from, and the maker on the library card too: *Unity 2022.3.39f1* (from the player library,
|
||||
else its data file; a game whose data file is encrypted reads without the release letter, *2019.4.40*), *Godot 4.4.1*
|
||||
(from its data pack), *RPG Maker MZ 1.10.0* and *MV 1.6.2* (from the core script), *RPG Maker VX Ace (RGSS 3.0.1)*
|
||||
(from the runtime library its `Game.ini` names — that number is the library's, not the editor's). A Unity version used
|
||||
to read as its library's build number (`2022.3.39.5118735`), and a Godot one was never found. Every game is read once
|
||||
more after the update (detection rules `2026.10.2`). RPG Maker 2000/2003 is not recognised (`docs/05_DETECTION.md`
|
||||
§Engine version — Unity, Godot, RPG Maker).
|
||||
- **The Privacy Policy (version 2.8)** names the files those versions are read from, and two that were already read and
|
||||
never named (Unity's player library and an RPG Maker game's title); it is shown once for you to accept.
|
||||
- **A game you uninstalled leaves the library by itself** when it has no sessions: the agent removes an entry whose `.exe`
|
||||
has been gone for ten minutes, if its drive is connected and the folder it was installed in is still there — an
|
||||
unplugged or re-lettered drive never counts — and never one where anti-cheat was found. A game with sessions stays, with
|
||||
them, and reads *Not installed* as before. The Games page says so when it happens — once, naming them, for all the games
|
||||
one check removes; **Settings ▸ Data ▸ Remove uninstalled games** turns it off (`docs/02_SPEC.md` FR-1.8).
|
||||
|
||||
### Changed
|
||||
|
||||
- **Change executable… opens in the game's own folder** — the install folder a store made (`steamapps\common\<game>`
|
||||
and the like), or above an Unreal game's `Binaries\Win64`, else the folder the executable is in — instead of wherever
|
||||
the last file dialog was. For a game whose folder is gone it opens at the nearest folder still there
|
||||
(`docs/08_UI.md` §Games).
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An imported game is no longer one of its helpers, and an RPG Maker MV/MZ game behind a launcher is its runtime.**
|
||||
A Doll's Locket - Remake (itch) was added as `notification_helper.exe`, NW.js's notification helper, because the itch
|
||||
app's own record named only that file (it leaves out a launcher that asks for administrator and anything a folder
|
||||
deeper) and the import took it as the game. A helper named by the store is skipped now and the executable is guessed —
|
||||
the import list says so — and the guess takes the executable beside NW.js's `nw.dll` and `package.json`, the process
|
||||
that draws (`css\Game.exe` there; its launcher asks for administrator, so it is measured with *Run the agent as
|
||||
administrator* on — *withdrawn 2026-10-13: that launcher is malware, do not run it; [0.1.0-beta.21]'s Security*). The
|
||||
import also no longer offers a store's game again when the library has it at another
|
||||
executable: an entry already there is re-pointed with *Change executable…* (`docs/05_DETECTION.md` §Library import).
|
||||
- **The Games page shows its newest read of the library.** When two reads overlapped — a session ending while an import
|
||||
added games — the one that started first could finish last and be shown, an older list until the next read.
|
||||
|
||||
## [0.1.0-beta.18] - 2026-10-07
|
||||
|
||||
**The eighteenth pre-release: every page readable in the dark theme, notices that say what happened in words, and a
|
||||
release whose build no longer calls itself dirty.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.17`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Page titles and section headings read in the dark theme again.** Every page's title and its section headings — Dashboard,
|
||||
Recent sessions, Games, Compare, Settings and each of its groups, Logs — were drawn near-black on the dark window
|
||||
(owner's screenshots of beta.17; beta.16 had it too). A page is shown in WPF UI's navigation Frame, which passes no text
|
||||
colour into the page, and a text that sets none is black; a page open during a theme switch picked the right colour up,
|
||||
and the next one navigated to did not. Every page now sets the theme's text colour itself. `AccessibilityTests.EveryPageSetsItsOwnTextColour`
|
||||
and `PagesLoadTests.EveryTextIsReadableInBothThemes` (every surface hosted as the App hosts it, ≥ 3:1 in both themes)
|
||||
went red on the unfixed pages first; the theme-switch check now hosts pages in the Frame too, and its harness derives the
|
||||
accent for each theme as the App does (`docs/08_UI.md` §Contrast, `docs/16_WPFUI_SYNTAX.md` §Gotchas, `docs/14_TESTING.md`).
|
||||
- **Every notice says what happened in words.** With *Disable all hooking* on, a game's notice read "kill switch was
|
||||
detected in this game (the global 'disable all hooking' switch is on (FR-2.4); …)" — it reads "All hooking is switched
|
||||
off in Settings, so nothing was measured." now, and a game blocked before reads as that, not as a finding. A refusal no
|
||||
anti-cheat names read "… reason RefusedByGuard." and is said in the guard's words ("the game is 32-bit, and the hook
|
||||
runs in 64-bit games only"); the agent sends the guard's reason for every refusal (`docs/07_IPC.md`). A safety re-scan
|
||||
that could not look while the game ran read "Access is denied. was detected" and says the check could not be made. And
|
||||
*Measurement stopped* printed "The hook stopped (WriterSelfDisabled); the session continues without measuring." — it
|
||||
says why in a sentence, and no longer that the session went on: a stop ends it. `NoticesFromTheAgentTests` builds the
|
||||
agent's own events for every refusal and every stop and went red with each text above (`docs/08_UI.md` §Notifications policy).
|
||||
- **Disable all hooking says when it applies.** Turning it on said "The capture agent reads it at the next session start";
|
||||
a game being measured stops at its next safety scan, within 30 seconds, and the message says so.
|
||||
- **Turning hooking off with no agent says nothing changed** — Settings' *Turn off*, the game page's switch and a
|
||||
withdrawn exception said "Nothing was enabled.", the enabling path's words.
|
||||
- **A viewer over a copy leaves every agent setting alone.** The user-mode exception option, the three Recording numbers
|
||||
and the update channel stayed live in `--data-dir`, where no agent reads them (`ViewerModeTests`).
|
||||
- `docs/08_UI.md` listed a "PawnIO missing" banner that was never built; struck, with the banners that do exist.
|
||||
- **A release's overlay build no longer calls itself dirty.** The Dashboard read *Overlay build v0.1.0-beta.17-dirty* (and
|
||||
beta.16's, and every release's before): the release workflow writes the release date into the legal documents before
|
||||
the build, and the build id was read from the tree after that. It is read from the clean checkout first and handed to
|
||||
the build, and `tools/buildid-check.ps1` reads it back out of the published binaries (`docs/12_BUILD.md` §Release-time
|
||||
token substitution). Nothing changes for a game: both sides of the ring's handshake always carried the same id.
|
||||
- **Two end-to-end tests no longer fail CI by a race** (developers only). The Vulkan launch test asks the test harness
|
||||
whether this machine can present through Vulkan before it starts the capture host: on GitHub's runners the harness's
|
||||
own "skip" line never reached the host's output, and a scan of the exiting harness failed the test instead of skipping
|
||||
it. The target-exit test holds its harness 15 seconds instead of 6, the margin a slow runner's host needed
|
||||
(`docs/13_CI_CD.md`).
|
||||
|
||||
## [0.1.0-beta.17] - 2026-10-07
|
||||
|
||||
**The seventeenth pre-release: text that keeps up with a change of theme, scroll bars hidden everywhere when you ask, a
|
||||
user guide that answers more, and a wiki.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.16`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Text keeps up with a change of theme.** After switching between Light and Dark, the descriptions and captions of the
|
||||
page in view — Settings above all, where the theme is chosen — kept the old theme's colour: light grey on white, or dark
|
||||
grey on dark. Every such text now follows the switch, on every page, window and dialog (`08_UI` §Contrast,
|
||||
`16_WPFUI_SYNTAX` §Gotchas).
|
||||
- **Hide scroll bars hides every scroll bar.** With Settings ▸ Window ▸ Hide scroll bars on, the Dashboard still drew its
|
||||
scroll bar — and so did the first run, About, the user guide and a game's wide sessions table; only screens with a
|
||||
switch or a tick box on them lost theirs. Every scroller follows the option now, and still scrolls with the wheel, the
|
||||
keyboard and touch (`08_UI` §Settings, `16_WPFUI_SYNTAX` §Gotchas).
|
||||
- **The first run names the right place to import your library.** Its last step said *File ▸ Import library… on the
|
||||
Games page*; File is the main window's menu, and the Games page has no such button. In Vietnamese it now names the menu
|
||||
as it is shown (*Tệp*).
|
||||
|
||||
### Added
|
||||
|
||||
- **The user guide looks things up too.** Four pages join it, in Help ▸ User guide: *The screens* (every page, menu,
|
||||
button and shortcut), *Every setting* (what each one does and its default), *When something goes wrong* (what you see,
|
||||
what it means, what to do) and *Words FrameLedger uses*. Tests now fail when a setting or a menu item is added without
|
||||
its line in the guide, or a link names a section that does not exist.
|
||||
- **A wiki.** The project's [wiki](https://github.com/poli0981/frameledger/wiki) has two halves: the user guide, the
|
||||
same pages the app shows, and short pages for developers — the architecture, the repository, building and testing,
|
||||
the rules every change keeps, capture, metrics, data, the app's UI and releasing — each linking to its full document.
|
||||
It is published from the repository whenever a release is made (`wiki.yml`), so it always matches the newest
|
||||
release, and `./build.ps1 check` fails on any link in it that leads nowhere (`13_CI_CD` §wiki.yml).
|
||||
|
||||
## [0.1.0-beta.16] - 2026-10-06
|
||||
|
||||
**The sixteenth pre-release: nothing changes in the app.** It is 0.1.0-beta.15 as the owner verified it on real hardware
|
||||
the same day, with the developers' end-to-end tests made reliable. The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.15`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
|
||||
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Development: the Agent's and the capture host's end-to-end tests no longer fail when another test project starts
|
||||
the test harness at the same moment.** Each such suite now records into a copy of the harness under a name of its
|
||||
own, so the target it asks for is never ambiguous (`14_TESTING`). Nothing in the app changes.
|
||||
|
||||
## [0.1.0-beta.15] - 2026-10-06
|
||||
|
||||
**The fifteenth pre-release: a quick restart recorded, an anti-cheat check that stays on the game's own programs, a
|
||||
change of language that reaches every list, and a launcher followed to its game.** The same unsigned installer: verify
|
||||
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **A game started again a few seconds after closing is recorded** — while the session before it was being saved, the
|
||||
new start used to be turned away and never looked at again.
|
||||
- **The anti-cheat check stays on the game's own programs.** Windows reuses process numbers, and a program that had
|
||||
taken over the number of a game's closed launcher could be scanned as part of the game — refusing the session, or
|
||||
turning the game's measuring off. It no longer is.
|
||||
- **A change of language reaches every list at once** — the theme and update-channel lists, the Logs page, the Games
|
||||
sort order, the tray's menu and the Agent's status — without a restart.
|
||||
- **A game started through its launcher is followed to the game itself** (the Agent's console `launch`).
|
||||
- **`FrameLedger.exe --data-dir <folder>` opens a copy of a data folder to look at**, with no Agent and nothing on the PC
|
||||
changed.
|
||||
|
||||
**Updating from `0.1.0-beta.14`:** Help ▸ Check for updates, then *Restart to update* with no game running — FrameLedger
|
||||
stops its Agent before the update is applied. Nothing in the database changes and nothing is shown again for you to
|
||||
accept; sessions already stored keep their status.
|
||||
|
||||
### Added
|
||||
|
||||
- **`FrameLedger.exe --data-dir <folder>` opens a copy of a data folder to look at**, for checking a build of your own
|
||||
against real data without touching your own. Such a window starts and contacts no Agent, records nothing and changes
|
||||
nothing on the PC — the controls that would are disabled, and a banner says whose data it shows. It refuses
|
||||
FrameLedger's own folder.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The anti-cheat check could scan a program that had nothing to do with the game**: Windows reuses process numbers, and
|
||||
once a game's launcher had closed, the check followed its number to whatever program held it now — a protected one
|
||||
refused the session, one carrying anti-cheat turned the game's measuring off for good. A program started after the game
|
||||
is no longer taken for its launcher, nor one started before the game for its child; when FrameLedger cannot read when a
|
||||
program started, it still scans it, as before.
|
||||
- **A game started again within a few seconds of closing was not recorded**: while FrameLedger was still saving the
|
||||
session that had just ended, the new start was turned away ("one session at a time") and never looked at again. It is
|
||||
recorded now, as soon as the session before it is saved — unless the game's other processes are still running beside
|
||||
it, as a multi-process game's helpers are.
|
||||
- **A game started through its launcher was never followed to the game itself** (the Agent's `--console launch`): when
|
||||
the launcher exited or never drew a frame, FrameLedger was to find the game the launcher had started and record it, and
|
||||
it never did — the launcher's process id was not passed on, so the search stopped before it began. It is passed on now,
|
||||
and a launch that ends without one says so in the log.
|
||||
- **After a change of language some text stayed in the old one** until FrameLedger restarted: the theme and update-channel
|
||||
lists in Settings, the log and level lists on the Logs page, the sort order on the Games page, the tray icon's menu and
|
||||
the Agent's status in the title bar. They follow the language at once now.
|
||||
|
||||
## [0.1.0-beta.14] - 2026-10-06
|
||||
|
||||
**The fourteenth pre-release: a wheel that scrolls, updates that find this channel and wait for your games, crashes told
|
||||
apart from memory reports, and new measurements.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The mouse wheel scrolls every page, dialog and chart**; over a chart the wheel scrolls the page and **Ctrl+wheel**
|
||||
zooms the chart. **Settings ▸ Window ▸ Hide scroll bars** draws no bar and still scrolls. The import list is readable
|
||||
in the dark theme.
|
||||
- **Updates come from the channel of the copy you run** — a beta looks for betas — and are never applied on their own
|
||||
when the App starts; restarting to update waits while a game FrameLedger measured is still running, and says so.
|
||||
- **A game that crashed reads *crashed*, and only then**: a Windows memory report about a game no longer counts as a
|
||||
crash, and an Unreal Engine game that opens its crash reporter and closes is recorded as crashed, the reporter named.
|
||||
- **A game starting up or closing during FrameLedger's anti-cheat check** is read again once instead of refused, and a
|
||||
check that could not read a game that had already closed ends the session as the game's own exit.
|
||||
- **New in every session's summary**: time below 30 and 60 FPS and below the monitor's refresh rate, how even the frames
|
||||
were, VSync and tearing, the graphics card's clocks, fan and memory temperature, how much of the time its power limit
|
||||
or heat held it back (NVIDIA), frames per watt, and a render scale chart. Trend and Compare have them too.
|
||||
- **FrameLedger's own programs say what they are** in Explorer and Task Manager (*FrameLedger Agent*).
|
||||
|
||||
**Updating from `0.1.0-beta.13`:**
|
||||
|
||||
1. **First choose *Beta* in Settings ▸ Updates.** beta.13 looks for stable releases by default, and every release so far
|
||||
is a pre-release, so it finds nothing until you do. From beta.14 on the channel follows the copy you run.
|
||||
2. **Update with no game running.** beta.13 still applies a downloaded update the next time the App starts, stopping the
|
||||
Agent to do it; beta.14 no longer does.
|
||||
3. **The database is migrated in place** (schema 0019, new columns only). An earlier version cannot open it afterwards.
|
||||
4. Sessions already stored keep their status — a few may still read *crashed* because Windows logged a memory report
|
||||
about the game. The Privacy Policy (version 2.7) is shown once for you to accept.
|
||||
|
||||
### Added
|
||||
|
||||
- **Settings ▸ Window ▸ Hide scroll bars.** No scroll bar is drawn anywhere in the app while it is on, and everything
|
||||
still scrolls with the mouse wheel, the keyboard and touch. Off by default; it applies at once, to the open windows
|
||||
too, and off brings every bar back.
|
||||
- **New measurements in every session** (recorded from this version on; earlier sessions read N/A):
|
||||
- **time below 30 FPS, below 60 FPS and below the monitor's refresh rate**, and how much one frame's time differs from
|
||||
the next. A game held at its frame limit is not counted as dropping below it for the small wobble every frame limit
|
||||
has — on the developer's machine a game capped at 60 read half its time "below 60" by the plain rule;
|
||||
- **VSync and tearing**: how many of the game's frames asked to wait for the display, and how many allowed tearing
|
||||
(Direct3D games);
|
||||
- **the graphics card's clock speeds, fan speed and memory temperature**, and — on NVIDIA cards — how much of the time
|
||||
its power limit or its temperature held it back;
|
||||
- **frames per watt**: the game's own frames per second for each watt the graphics card drew, never counting generated
|
||||
frames.
|
||||
|
||||
The session's sensor statistics table shows the new card readings in their own units. The database is migrated in
|
||||
place (schema 0019), and an earlier version cannot open it afterwards.
|
||||
- **Where the new measurements are shown:** the session summary has a card for each (the 1% low card also shows the
|
||||
displayed frames' 1% low when frame generation was counted, beside the game's own), a **Render scale** chart — the
|
||||
share of the screen's resolution the game rendered at, over the session — and a **Clocks and fan** chart under
|
||||
Sensors, with the moments the card was held back shaded; the card's memory temperature joins the temperatures chart.
|
||||
A game's **Trend** has nine more metrics and **Compare** nine more rows, where a figure taken over presents says
|
||||
*(presented)* beside one taken over the game's own frames. The **Latency** tab is shown only for a game with a session
|
||||
that measured latency — none does yet.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A session could read "crashed" when the game had not crashed, and an Unreal game's crash read "ended normally".**
|
||||
Any Windows report that named the game counted as a crash — on the developer's machine a memory-leak report Windows
|
||||
writes about large games marked an ordinary The Witcher 3 session *crashed*; hang reports and another program whose
|
||||
name contains the game's would have done the same. Only a crash report of this game's own process counts now. And
|
||||
Unreal Engine games handle their own crash: they open their crash reporter and exit with code 3, which said nothing;
|
||||
FrameLedger now sees the crash reporter a game starts (Unreal's, CD PROJEKT RED's, Capcom's, BugSplat's) and records
|
||||
the session as crashed when the game exits within a minute of it — the summary names the reporter. Unity's and
|
||||
Chromium's crash handlers start with their game and are never taken for a crash. Sessions already stored keep their
|
||||
status. BugSplat's sender (Kingdom Come: Deliverance II) can no longer be picked as a game's executable by the import.
|
||||
The Privacy Policy (2.7) now says that FrameLedger reads Windows' crash reports and the names of programs a game starts.
|
||||
- **A game that exited as FrameLedger's anti-cheat check ran could be recorded as "unhooked (safety)"** — and, under a
|
||||
user-mode anti-cheat exception, end the exception's trial for good. The check reads every process in the game's
|
||||
tree every 30 s; one that was just starting (an engine's crash reporter as its game dies, any helper the game launched
|
||||
a moment before) or already gone could not be read, and the check refused. Such a process is now read once more a
|
||||
quarter of a second later, and refused only if it is still unreadable (a protected process never gets the second
|
||||
look). And when the check could not read and the game itself has exited, the session ends as that exit, normal or
|
||||
crashed by its exit code. Anything the check *finds* is a refusal exactly as before (owner decision D48).
|
||||
- **An installed copy never found an update unless you had changed its channel.** The update channel was *Stable* by
|
||||
default and every FrameLedger release so far is a pre-release, so the check found nothing. The channel is now
|
||||
*Automatic*: a pre-release looks for pre-releases and a release for releases; choosing *Stable* or *Beta* still decides.
|
||||
- **A downloaded update was applied the next time FrameLedger started, before anything could check for a running game.**
|
||||
The update library applies a waiting package at start unless told not to, and nothing told it: it stopped the capture
|
||||
agent mid-session instead of letting it finish. The App now offers such a package as *Restart to update*, which waits
|
||||
for the session to end and stops the agent properly, as it always did for a download in the same run.
|
||||
- **The update dialog said ~102 MB when the download was the 1.6 MB delta.** It now says the delta's size and names the
|
||||
full package as the fallback; the updater's own lines are in the App's log, so a full download shows there.
|
||||
- **Restart to update could fail half way** when a game FrameLedger had measured was still running — its loaded overlay
|
||||
cannot be replaced — or when an agent was still waiting on the administrator prompt, and it gave the agent 10 s to stop
|
||||
where the agent takes up to 15. It waits for all three now and says why. A full disk no longer reads as "offline",
|
||||
and uninstalling removes the *Start FrameLedger with Windows* entry.
|
||||
- **The import list was unreadable in the dark theme.** File ▸ Import library (and Games ▸ Refresh) drew every row white
|
||||
with white text, and each tick box as a sliver at the row's edge: a row style added in beta.11 to dim the games already
|
||||
in the library fell through to Windows' own row, which is white in every theme, and WPF UI's check box is too wide for
|
||||
its 40 px column. The rows take the theme's colours again and the boxes are whole, and the list is the one thing in the
|
||||
dialog that scrolls — its intro and the count under it stay in view, where a list scrolling inside a scrolling dialog
|
||||
used to carry the intro away. Compare's session picker draws the theme's check boxes too (it drew Windows' old ones).
|
||||
- **The mouse wheel scrolled nothing on the Dashboard, Games, a game's page, Compare and Settings** — only dragging the
|
||||
scroll bar did. WPF UI wraps a page in a scroller of its own unless the page says otherwise, and inside it each page's
|
||||
own scroller had nothing to scroll and still took every wheel. Every page scrolls itself now. The Logs page had the same
|
||||
cause: its tail grew to hold every line and never followed the newest one, as it was meant to. A scroller inside a
|
||||
dialog (the consent, administrator, anti-cheat exception and bug report dialogs) hands the wheel on at its ends.
|
||||
- **The chart-wheel test read the real keyboard** (developers): a Ctrl held anywhere on the machine while the test ran
|
||||
turned its plain wheel into a zoom, and a local gate went red once. The keys held are now the test's own input, and the
|
||||
Ctrl+wheel half is driven end to end as well.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Over a chart, the wheel scrolls the page; Ctrl+wheel zooms the chart.** ScottPlot zoomed on every wheel, which with
|
||||
the pages scrolling again would have zoomed the chart and scrolled the page at once. Dragging still pans and
|
||||
double-click still resets.
|
||||
- **FrameLedger's own programs say what they are.** In Explorer (*Properties ▸ Details*) `FrameLedger.exe` and
|
||||
`FrameLedger.Agent.exe` now name the product, the author's copyright and what each one does, as the native DLLs always
|
||||
have; Task Manager lists the background service as *FrameLedger Agent* rather than *FrameLedger.Agent*. Until this
|
||||
release the Agent called its company and product "FrameLedger.Agent" and no managed file carried a copyright. The
|
||||
release check now reads both kinds of file and fails when one of them does not name FrameLedger or carries a different
|
||||
copyright line.
|
||||
|
||||
## [0.1.0-beta.13] - 2026-10-04
|
||||
|
||||
**The thirteenth pre-release: refusal notices that say where the anti-cheat is, GPU sensors that follow the game's graphics
|
||||
card, and smaller updates.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run
|
||||
anyway*. What changed for a user:
|
||||
|
||||
- **An anti-cheat driver or service running on the PC is said as that.** While, for example, Easy Anti-Cheat's service
|
||||
runs for another game, FrameLedger hooks no game at all; the notice used to say the anti-cheat "was detected in this
|
||||
game", naming a game that may not even use it. It now says the anti-cheat is running on this PC, and the session's
|
||||
summary says the same. A finding in the game itself still says "in this game".
|
||||
- **The notice for a capture stopped mid-game** no longer promises that FrameLedger will hook the game again "when you
|
||||
enable it again" — which was not true either way. It says where the anti-cheat was found and whether hooking was
|
||||
turned off.
|
||||
- **On a PC with more than one graphics card**, the GPU figures follow the card the game draws on once it has shown its
|
||||
first frame, instead of the first card Windows lists (often a laptop's integrated GPU). Not yet tested on such a PC.
|
||||
- **Updates download only what changed**: this release carries a delta package against `0.1.0-beta.12`, so updating
|
||||
from it through the App downloads a fraction of the full ~107 MB.
|
||||
|
||||
**Updating from `0.1.0-beta.12`:**
|
||||
|
||||
- Help ▸ Check for updates downloads the delta; or quit the App (tray icon → Exit), end `FrameLedger.Agent.exe` and
|
||||
run the installer as before.
|
||||
- No database change, and no document to accept again.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A refusal because of a driver or service said the anti-cheat "was detected in this game".** The guard's checks for
|
||||
drivers and services are machine-wide: while Easy Anti-Cheat's service runs for another title, every game is refused,
|
||||
and the notice named a game the user may not even own. It now says the anti-cheat is running on this PC — a driver or
|
||||
service that may belong to another game or program — and the session summary says the same; a finding in the game
|
||||
itself still says "in this game" (`20_OPEN_QUESTIONS` §S23-3, closed). The Agent's refusal and unhook events carry the
|
||||
guard's own reason for this (`guardReason`, additive).
|
||||
- **The notice for a mid-session stop promised "FrameLedger will not inject into this game again until you enable it
|
||||
again"**, untrue both ways since beta.5: a driver or service that starts on the PC turns no hooking off, and a finding
|
||||
in the game turns it off for good. It says where the finding was, and whether hooking was turned off.
|
||||
- **On a PC with more than one graphics card, the GPU sensors could describe a card the game was not using.** The
|
||||
adapter the game draws on is now followed once it has shown its first frame: the DXGI layer switches to it,
|
||||
LibreHardwareMonitor reads that brand's GPU rather than the first one it lists (often a laptop's integrated GPU), and
|
||||
NVAPI says nothing when the game runs on an AMD or Intel card — N/A rather than another card's temperature.
|
||||
`LIMITATIONS.md` says what still describes the first card.
|
||||
- **Updates download only what changed**, from this release on: each release now carries a Velopack delta package
|
||||
against the previous one beside the full package, and an installed copy one release behind downloads the delta. No
|
||||
earlier release had one — every update so far downloaded the whole ~107 MB package — so the first update that can use
|
||||
a delta is from `0.1.0-beta.12` to this one; Velopack falls back to the full package whenever the delta does not apply.
|
||||
- **Tests that change the App's language ran beside tests that read its text**, so the second kind could read the
|
||||
wrong language once in many runs; the language-changing tests now run on their own.
|
||||
|
||||
## [0.1.0-beta.12] - 2026-10-04
|
||||
|
||||
**The twelfth pre-release: how much memory each game itself uses, documents you can read, and a user guide.** The same
|
||||
unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The game's own memory, in every session** — its video memory and its RAM, the figures Task Manager's Details tab
|
||||
shows for the game's process, read once a second from outside the game, whether or not the game is hooked. The
|
||||
session summary shows the median and the peak, the Sessions tab has two new columns, the Trend and Compare have the
|
||||
memory metrics, the Sensors charts draw this game's memory beside the whole graphics card's and the whole PC's, and
|
||||
the Dashboard shows it live.
|
||||
- **Statistics per series**: every sensor's mean, median, minimum and peak, at the bottom of a session's summary.
|
||||
- **Documents are rendered**, not shown as raw text: the first-start documents, Help ▸ Limitations, the update notes,
|
||||
and a new **Help ▸ About** with the program's legal notices, the third-party licences and the legal documents.
|
||||
- **A user guide** — eight short pages, under **Help ▸ User guide**.
|
||||
- **The GPL is no longer something you accept**: it is your licence, shown for information. You accept the EULA (now
|
||||
1.5), the Disclaimer (2.10) and the Privacy Policy (2.6), so the first-start window opens once after the update.
|
||||
- Links to the project's documents open the version you run, not the newest one.
|
||||
- **The Logs page's Warning and Error filters show the Agent's lines** too; they showed only the App's.
|
||||
- **Settings no longer has "Record games launched outside FrameLedger"**: the switch never did anything.
|
||||
|
||||
**Updating from `0.1.0-beta.11`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0018 adds the memory columns; the database opens in place, and an older version cannot open it again.
|
||||
- Sessions recorded before this version have no memory figures and no per-series statistics: they read N/A, and the
|
||||
summary says so.
|
||||
- The new `FrameLedger.ProcessStats.dll` is installed beside the Agent; without it the memory figures read N/A.
|
||||
|
||||
### Added
|
||||
|
||||
- **The game's own memory, measured from outside the game, in every session** (owner decision D43, beta.12). A new
|
||||
C++ library loaded by the Agent — never into a game — `FrameLedger.ProcessStats.dll`, reads once a second the game
|
||||
process's **dedicated and shared GPU memory** (the documented `GPU Process Memory` performance counters, which need no
|
||||
handle to the game) and its **private working set, working set and commit** (`GetProcessMemoryInfo` with
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` only) — the numbers Task Manager's Details tab shows. A hooked game is read through
|
||||
the handle the session already holds; a game that is not measured (anti-cheat, hooking off) through a handle opened for
|
||||
the read and closed after it, the same least right the watcher already uses on every process, every process running its
|
||||
executable added up, a reused pid refused. Measured before it was written in (`spike-notes` §16): a 512 MiB allocation
|
||||
read +512.0 MiB, the private working set equals Windows' own counter, one read costs 0.1 ms, 600 reads leak nothing.
|
||||
Stored as five new sensor series and, in schema **0018**, the median / mean / peak columns
|
||||
(`game_vram_dedicated_*`, `game_ram_private_*`, …), the process count, the sources, and every sensor series'
|
||||
n / mean / median / min / max in `sensor_stats_json`; carried live to the Dashboard (`SessionProgress`, `SessionHeld`)
|
||||
and through the crash-recovery file (a new chunk type; beta.11's files still recover). The video-memory **budget** is
|
||||
still not measured (`20_OPEN_QUESTIONS` §M11). The App shows all of it (below).
|
||||
- **Sensor statistics have a median and a minimum** beside the mean and the maximum (`SeriesAggregates`).
|
||||
- **The App shows the game's own memory everywhere a session is** (D43, beta.12), in Task Manager's units — MB below
|
||||
1 GB, GB to two decimals, 1 GB = 1024 MB. The **session summary** has two new cards, *VRAM (this game)* and *RAM (this
|
||||
game)*: the median, with the peak (and the shared GPU memory's or the commit's peak) beneath, and a new table,
|
||||
**Statistics per series** — every series' mean, median, minimum, peak and number of readings, each in its own unit, as
|
||||
stored when the session ended. The **Sessions** tab has *VRAM (game)* and *RAM (game)* columns (median · peak, the rest
|
||||
in the tooltip); the **Trend** has *Median / Peak VRAM (game)* and *Median / Peak RAM (game)*; **Compare** has the same
|
||||
four rows; the **Sensors** charts draw *Video memory* (this game's dedicated and shared beside the whole graphics card's)
|
||||
and *Memory* (this game's private working set beside the whole PC's) in GB; the **live card** reads "This game: VRAM …
|
||||
· RAM …", for a game that is not measured too; and the CSV export has a `# game_memory:` header line. Where Windows does
|
||||
not report the private working set (before the September 2023 update) the working set is shown in its place and says
|
||||
so. A session recorded before beta.12 reads N/A, and its summary says the statistics table did not exist yet.
|
||||
- **Documents are shown rendered, not as raw Markdown** (owner request 4, beta.12): the Legal Gate, Help ▸ Limitations,
|
||||
the update notes and the new About window draw headings, lists, tables, code and links (Markdig 1.4.0, BSD-2-Clause;
|
||||
HTML in a document is shown as text and no image is fetched). The GPL is shown as written. Selectable and copyable;
|
||||
links open in the browser, scroll to a section, or open another document the window holds; a `file:` or
|
||||
`javascript:` link is never followed. **Help ▸ About** is a window with three tabs: the program's legal notices
|
||||
(copyright, no warranty, the licence with the NOTICE terms, this version's source code), the third-party licences
|
||||
with every shipped package's version and a button that opens the licences folder, and the legal documents (EULA,
|
||||
GPL, Disclaimer, Privacy Policy, NOTICE, Trademarks). Help ▸ Limitations is a window of its own.
|
||||
- **Links into the repository open the documents of the version you run**: a release stamps its tag into the App
|
||||
(`-p:FrameLedgerSourceRef`), so *View on GitHub*, the safety document and every document link go to that tag rather
|
||||
than to `main`, where the text may have changed since.
|
||||
- **A user guide** (owner decision D44, beta.12): eight short pages for players — install and first start, record a
|
||||
game, read your results, anti-cheat and safety, your data, questions and answers, and the terms in plain words — in
|
||||
the app under **Help ▸ User guide** (the first item of the Help menu) and in the repository's `guide/` folder. The
|
||||
README now opens with a pointer to it and keeps a separate section for developers and forks.
|
||||
- **`NOTICE`, and the licence header in every source file** (owner decision D45, beta.12). FrameLedger's own material is
|
||||
GPL-3.0-only with three additional terms of the kinds GPLv3 §7 permits: keep the copyright line and the attribution in
|
||||
the program's legal notices (b), mark a modified version as different and do not call it "FrameLedger" alone (c), and
|
||||
no trademark rights in the name (e). Section 7 wants such terms named in the source files themselves, so every
|
||||
first-party `.cs`, `.cpp`, `.h`, `.inl`, `.ps1` and `.xaml` file now opens with an `SPDX-License-Identifier:
|
||||
GPL-3.0-only` line and a line pointing at `NOTICE` (1,053 files; `src/native/third_party/` excluded). A new gate,
|
||||
`tools/notice-check.ps1` (six self-test cases, both directions; `-Fix` writes a missing header), keeps it true, and
|
||||
`tools/resx-gen.ps1` generates the string accessors with it. `NOTICE` ships in every package as
|
||||
`licenses\NOTICE.txt`, and `release.yml` refuses a published tree without it.
|
||||
- **For people who build, contribute or redistribute:** `CONTRIBUTING.md` (the gate, the definition of done, what will
|
||||
not be merged, and that a contribution is licensed GPL-3.0-only with the `NOTICE` terms — no CLA), `FORKING.md` (what
|
||||
the GPL asks of someone who distributes builds, and the names a fork must change so that it does not share
|
||||
FrameLedger's update feed, install folder, database, pipe, shared memory or Vulkan layer), `CODE_OF_CONDUCT.md` (the
|
||||
Contributor Covenant 2.1, adopted by reference) and `legal/TRADEMARKS.md` (third-party names, no affiliation, and how
|
||||
the name FrameLedger may be used).
|
||||
|
||||
### Changed
|
||||
|
||||
- **The GPL is no longer accepted at the first start** (owner decision D45): it is your licence to FrameLedger and is
|
||||
shown beside the documents for information — GPLv3 §9 needs no acceptance to run the program. **Accept** covers the
|
||||
End User License Agreement, the Disclaimer and the Privacy Policy; a row an earlier version wrote for the GPL stays,
|
||||
unread.
|
||||
- **The documents you accept change, and are shown again once:** **EULA 1.5** (an unmeasured session also records the
|
||||
game's own memory use; the GPL needs no acceptance; where the third-party notices are in an installed copy; your
|
||||
rights as a consumer that no agreement can limit, and severability), **Disclaimer 2.10** (what it reads about a game
|
||||
from outside it: the game's memory use, opened with the least access Windows offers; §2 names everything the thread
|
||||
it runs inside the game does, which it understated; the maintainers' preface moves to
|
||||
`docs/legal-drift-history.md`), **Privacy Policy 2.6** (the game's memory use, replacing a video-memory figure the
|
||||
software never read; a new §3A on what an export or a bug report can carry about you before you share it; the version
|
||||
history notes move to `docs/legal-drift-history.md`).
|
||||
- **Help ▸ Documentation is Help ▸ Online documentation**, and opens the README of the version you run.
|
||||
|
||||
### Removed
|
||||
|
||||
- **Settings ▸ Recording no longer shows "Record games launched outside FrameLedger".** Nothing ever read that switch —
|
||||
turning it off recorded every game anyway — and the App has no way to start a game itself, so "off" could only have
|
||||
meant recording nothing. Its stored value is kept, unread, until a launch path exists.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The Logs page's Warning and Error filters showed no line from the Agent.** The Agent's log starts each line with a
|
||||
date (Serilog's default form) and the filter read only the App's `[HH:mm:ss.fff LVL]` prefix; its test had fed App-form
|
||||
lines into the fake Agent log. Both forms are read now.
|
||||
- **The developer documentation is corrected in place** (owner decision D46): about a hundred statements across
|
||||
`docs/01`–`20`, `HANDOFF`, `CLAUDE.md` and `FORKING.md` that the code contradicted, each struck with a dated
|
||||
correction — among them a rules feed that does not exist (rules reach you with a release, as `LIMITATIONS.md` says),
|
||||
hooks that were never built, the in-game thread described as doing less than it does, a delta update package that was
|
||||
never published, the release steps for a pre-release, the Legal Gate's row count and the logging configuration. The
|
||||
rules file's own comment and the rules workflow's header made the feed claim too, and are corrected. `docs/README.md`
|
||||
is a new index for developers. Code comments that said what is not so (a sparkline, a flyout, a layer flag "false by
|
||||
construction", two self-test counts) are corrected with them.
|
||||
- **The first start's summary said "there is no way to override that refusal"** although a per-game user-mode exception
|
||||
has existed since beta.9, and **"Nothing is sent anywhere"** although the update check is a request to GitHub; it now
|
||||
names the exception and the one request. The README's safety table still said an exception needed two earlier
|
||||
successful sessions — the rule until beta.11 (D38) made them a trial — and its feature list promised "per-process VRAM
|
||||
and whether the driver was exceeding its budget"; both now say what the software does. The tier tooltip names the
|
||||
game's memory beside the duration and the sensors.
|
||||
- **The Legal Gate showed the documents as raw Markdown** (`**bold**`, `| --- |`) in a text box, and Help ▸ Limitations
|
||||
and the update notes the same; they are rendered now (above). The Legal Gate's *View on GitHub* went around the App's
|
||||
link opener; it goes through it.
|
||||
- **The third-party notices' component table did not render as a table** in a Markdown renderer that follows the spec
|
||||
strictly: a note line sat between its rows. The note is moved below the table, unchanged.
|
||||
- **"Max VRAM (game)" on the Trend never had a point, the live card's VRAM was always empty, and the Sensors chart's
|
||||
"VRAM used by this game" line was never drawn**: all three read the Overlay's in-game per-present figure, which nothing
|
||||
ever produced. They read the game's memory measured from outside it now (above), and the CSV's note no longer calls
|
||||
the always-empty `vram_mb` column "a held 1 Hz sample".
|
||||
- **"Avg RAM in use" on the Trend is labelled as the whole PC's**, in GB like every other memory figure, so it is not
|
||||
read as the game's.
|
||||
- **A licence header written by a contributor no longer has to name poli0981**: `tools/notice-check.ps1` accepts any
|
||||
holder and year in the same form (`Copyright (C) <year> <holder> - additional terms under GPLv3 section 7: see NOTICE`),
|
||||
and `CONTRIBUTING.md` says so; seven self-test cases.
|
||||
- **Documents that described a per-process VRAM figure the Overlay never produced** are corrected in place
|
||||
(`03_METRICS`, `17_HOOK_ENGINE`, `18_GPU_VENDOR_APIS`, `20_OPEN_QUESTIONS` §M7/§H10), and the two that said an unmeasured
|
||||
session opens no process (`04_CAPTURE`, `19_SAFETY`) now say what it opens, with which right, and why. The accuracy block
|
||||
and `LIMITATIONS.md` say what is measured now. `ITelemetryPoller`'s remark that the descriptor is read at finalize — it is
|
||||
read at session start — is corrected.
|
||||
- **The native binaries' version block named the wrong licence.** Every DLL's `LegalCopyright` read
|
||||
`GPL-3.0-or-later` while `LICENSE`, the EULA, the README and the third-party notices all say GPL-3.0-only; it now reads
|
||||
`Copyright (C) 2026 poli0981. GPL-3.0-only with additional terms: see NOTICE`.
|
||||
|
||||
## [0.1.0-beta.11] - 2026-10-03
|
||||
|
||||
**The eleventh pre-release: a user-mode anti-cheat exception that can be reached, a library that fills the window, and
|
||||
charts and clean-up across a game's sessions.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`,
|
||||
then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The user-mode anti-cheat exception no longer needs earlier sessions.** A game blocked the moment it was added could
|
||||
never qualify; now its first two sessions under the exception are a trial, and one that does not go well ends the
|
||||
exception for good. Everything else it requires is unchanged, and a ban remains possible.
|
||||
- **The Games library** fills the window at any width, can be shown as a list, counts its games and has **Refresh**: it
|
||||
reads the library again, offers the games your stores installed since, and marks games whose executable is gone.
|
||||
- **Import** hides the games already in the library — you can show them, dimmed.
|
||||
- **Delete all sessions** — of one game on its page, or of every game in Settings ▸ Data.
|
||||
- **Charts across a game's sessions**: *Sessions at a glance* on the Sessions tab, and the Trend draws more metrics at once.
|
||||
- **Settings** has no row without a control.
|
||||
- **Three CrackProof games** are on the anti-cheat list (Umamusume: Pretty Derby, Heaven Burns Red, Madoka Magica Magia
|
||||
Exedra).
|
||||
- **The Disclaimer (2.9) and the EULA (1.4) say how the exception works now**, so the Legal Gate opens once after the
|
||||
update. The Privacy Policy is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.10`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0017 adds one column; the database opens in place, and an older version cannot open it again.
|
||||
- Every game is re-checked once for anti-cheat (rules `2026.10.1`).
|
||||
- An exception made under beta.9 or beta.10 stays in force; if fewer than two sessions were played under it, the rest of
|
||||
its trial applies.
|
||||
|
||||
### Added
|
||||
|
||||
- **The Games library fills the window, switches to a list, counts its games and refreshes** (owner requests, beta.11).
|
||||
The cards were 300 px in a plain wrap, so a wide window left up to a card's width empty at the right and the third pill
|
||||
("Hooking off") was cut; the grid now has as many columns as fit at 300 px or wider, every card an equal share of the
|
||||
width, and the pills wrap. A button beside the sort switches to a **list** — one row per game with its store, engine,
|
||||
status, sessions, playtime and last played — and the choice is remembered (`ui.library_view`). The title counts the
|
||||
games. **Refresh** reads the library again, looks in the stores for games installed since and offers only those (*No
|
||||
new games* when there are none), and marks every entry whose executable is gone **Not installed** — the tooltip says
|
||||
when it is the drive that is not connected; nothing is removed. The page also reloads by itself when a session ends or
|
||||
an import adds games while it is open (an import made from the menu used to show only after leaving the page).
|
||||
|
||||
- **Import hides the games already in the library** (owner request, beta.11): on a re-import they were most of the list
|
||||
and pushed the new ones out of sight. *Show the N games already in the library* brings them back, dimmed, and a row
|
||||
that cannot be imported has its box disabled (a tick on it was taken and ignored).
|
||||
|
||||
- **Delete all sessions** (owner decision D40, beta.11): on a game's page, every session of that game; in Settings ▸
|
||||
**Data**, every session of every game — with their frame and sensor data and notes, after a confirmation that says how
|
||||
many. The library, the settings and every game's hooking consent stay. The capture agent deletes them (the rows are its)
|
||||
and refuses while a session is being recorded; an older agent is told to restart. A summary window still open on a
|
||||
deleted session closes. A new pipe request, `DeleteSessions`.
|
||||
|
||||
- **Charts across a game's sessions** (owner decision D39, beta.11): the Sessions tab opens with *Sessions at a glance* —
|
||||
every hooked session's frame rate (Presented FPS, or Native and Displayed where frame generation was measured, never one
|
||||
inflated line) and its 1% and 0.1% lows, oldest first; click a point to select that session. The Trend keeps its metric
|
||||
and can **draw more beside it** (*Also draw*), a second unit against the right axis, two units at most.
|
||||
|
||||
- **Three CrackProof titles on the anti-cheat title list** (owner request, beta.11): Umamusume: Pretty Derby (Steam
|
||||
`3224770`), Heaven Burns Red (`1973710`) and Madoka Magica Magia Exedra (`2987800`). Each store page states *"Uses
|
||||
Kernel Level Anti-Cheat"* and names HyperTech's CrackProof; its driver loads from `System32` under a numbered name,
|
||||
@@ -55,6 +695,10 @@ under a `## [x.y.z] - date` heading in the same commit that bumps `VERSION`, the
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Settings has no row without a control** (owner request, beta.11): *Games with hooking on* shows only while a game has
|
||||
hooking on, the *Elevation* row became the admin mode row's status line, and the note under the language row is gone.
|
||||
The retention message now names Settings ▸ Recording, where retention lives.
|
||||
|
||||
- **The exception's card and list say what is true** (found with D38): an eligible game's *Anti-cheat* card said hooking
|
||||
"cannot be turned on" beside a usable *Make exception…* — it now says hooking is off unless you make one; the Settings
|
||||
list showed each game's session count twice and listed games that could never qualify, with no action — it lists only
|
||||
|
||||
@@ -16,14 +16,14 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
> **Amended 2026-09-22 (owner decision): the override of 2026-09-21 is withdrawn, and the sentence above is the rule again.** For one day (releases `0.1.0-beta.3` and `beta.4`) a per-game override existed. The owner withdrew it: no entry point, no message, no column (schema 0008 drops 0007's five), no string. Do not add one in any form.
|
||||
>
|
||||
> **A finding turns the game's hooking off** (`19_SAFETY` §What a finding does to the game). An anti-cheat named in the game itself — its process, its title lists, its folder — is written to the row exactly as the pre-scan always wrote it (`hook_enabled = 0`, `hook_blocked_reason`, `hook_prescan_state = 'blocked'`), and since 2026-09-22 also when the guard finds it at a session's start or at the 30 s re-scan (`AntiCheatVerdict.IsFindingAboutTheGame`). A machine-wide driver or service refuses that session only. The notice, the game's page, the session's notes and the Agent's log all say it happened. Nothing clears the block, as before.
|
||||
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
|
||||
> **Amended 2026-09-26 (owner decision D33): one narrow, evidence-bound exception.** Asked with the 2026-09-22 withdrawal and this rule quoted back, the owner chose a per-game exception for anti-cheat that is **user-mode throughout** — a Settings option off by default, then the user ticks each eligible game through a versioned disclosure (bans are possible and can arrive days later). Eligible only when every finding about the game is `BlockedModule` / `AntiCheatFile` / `AntiCheatDirectory` of ONE family whose floor-and-file footprint has no driver, service or `.sys` (`fl::guard::FamilyIsUserModeOnly` — the GUARD decides, from a family NAME the caller passes), no `.sys` is anywhere in the install tree *(within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder)*, no title list names the game, and the ledger holds ≥ 2 successful Tier-1 sessions of it. Drivers, services, title lists, the `.sys` rule, the fuzzy tier, scan failures, `TargetUnreadable`, 32-bit, the kill switch and Vulkan are never excepted. The guard runs every check and keeps scanning past the tolerated family (`kAllowedUserModeException`, reason 28); the Overlay learns the family from `Local\FrameLedger.Tolerate.<pid>` before its loader detour exists. A new finding, a crash / safety unhook / floor stop under it, or an executable change ends it; the block is never cleared. **No other form of override is to be added** (`19_SAFETY` §The user-mode exception).
|
||||
> **Amended 2026-10-03 (owner decision D38): the evidence moved from before the grant to its trial.** "≥ 2 successful Tier-1 sessions" above could never be met by a game blocked at add time — since beta.8 that is every blocked game — nor after a ledger reset. Asked with that, the owner chose: a grant needs no session; the first two hooked sessions under it are a trial, and any end during the trial (a crash, a safety unhook, a floor stop, a new finding, or a stored hooked session with no frames or an abnormal exit) ends the exception **for good** (`games.ac_exception_trial_failed_at`, schema 0017, never cleared). Every other condition above is unchanged, and so is the last sentence.
|
||||
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
|
||||
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
|
||||
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
|
||||
6. **FPS display rule (product requirement):** wherever FPS is shown and Frame Generation is active, show *Native FPS*, *Displayed FPS*, and the FG factor together (`62 → 118 FPS (×1.9 FG)`). Never a single inflated number. See `docs/03_METRICS.md`.
|
||||
|
||||
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, which is every title on today's writer — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
|
||||
> **Amended 2026-09-03 (owner decision).** When frame generation is *not measured* — `FL_MEASURED_FG` clear, ~~which is every title on today's writer~~ which is every title with no Streamline or FidelityFX hook live *(corrected 2026-10-04: the writer sets it since #103, 2026-09-03)* — the one number that may stand alone is **Presented FPS** (`presents / D`), with a mandatory qualifier from the **runtime census** (`FlWriterState.runtimeCensus`): "no frame-generation runtime was loaded, so this cannot include in-process generated frames" or "a frame-generation runtime is loaded and nothing was observed — this MAY include generated frames". The word "Native" never appears alone. **The census never produces `none`**: a statically linked FSR has no module to see, and a census-`none` there would be exactly the inflated number this rule forbids.
|
||||
>
|
||||
> **Amended 2026-09-05.** A counted `none` (`presents = application frames`) is **withheld** — Presented FPS with a third qualifier, "this number counts application frames; the Displayed rate is unknown" — on the one shape measured to produce a false `none`: Streamline ≥ 2.8.0 with `sl.dlss_g.dll` loaded (Dying Light: The Beast, five captures, DLSS FG ×4 per the owner). `docs/03_METRICS.md` §Frame Generation carries the key and why it is the Streamline plugin rather than `nvngx_dlssg.dll`; `20_OPEN_QUESTIONS` §H5 carries the session that keeps or withdraws it.
|
||||
>
|
||||
@@ -47,7 +47,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
| UI | WPF + WPF UI (`WPF-UI` pinned = 4.3.0) + CommunityToolkit.Mvvm — `docs/16_WPFUI_SYNTAX.md` |
|
||||
| App composition | .NET Generic Host + DI in `FrameLedger.App` |
|
||||
| Charts | ScottPlot 5 |
|
||||
| GPU telemetry | Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
|
||||
| Markdown in the App | **Markdig** (BSD-2-Clause, pinned 1.4.0) → WPF `FlowDocument`, HTML off, no image fetched — the Legal Gate, the user guide, Help ▸ Limitations, the update notes, About (beta.12; row added 2026-10-04) |
|
||||
| GPU telemetry | **The game process's own memory since beta.12 (D43):** `FrameLedger.ProcessStats.dll` (C++, loaded by the Agent, never into a game) reads its dedicated/shared GPU memory from the `GPU Process Memory` counters and its working sets from `GetProcessMemoryInfo` — `18_GPU_VENDOR_APIS` §The game process's memory. Layered: DXGI + PDH counters (all vendors) → LibreHardwareMonitorLib (MPL-2.0, all vendors) → **NVAPI (MIT, headers + `amd64/nvapi64.lib` vendored 2026-08-05** at `src/native/third_party/nvapi/`, consumed via the `fl_nvapi` target; NVIDIA extras + Reflex). **No AMD/Intel vendor SDK** — `docs/18_GPU_VENDOR_APIS.md`. ~~**No telemetry source exists in code yet**~~ **`LhmTelemetrySource` (L2) exists since 2026-09-03 (`20_OPEN_QUESTIONS` §M5 row R1, eight GPU fields unelevated); L1 (`BaselineTelemetrySource`: DXGI identity + the PDH adapter-memory counter, the first CsWin32 consumer), `CompositeTelemetrySource` and the 1 Hz `TelemetryPoller` since 2026-09-09; L3 (`NvapiTelemetrySource` over the native `FrameLedger.NvapiBridge.dll` — the only shipped binary linking `nvapi64.lib`, loaded by the Agent into its own process and never into a game) since 2026-09-10 (PR-E2)** — `ctest fl_nvapi_probe` was the only NVAPI consumer until then, and it exists so the vendoring is verified rather than asserted. This row said no source existed for six days after one did, recorded 2026-09-09 rather than repaired quietly. This row previously claimed the vendoring in the present tense while `third_party/` held only `vulkan-headers`; `legal/` had already caught the identical claim about itself and gained a bidirectional gate, which is what made the real vendoring a red-then-green |
|
||||
| CPU/board sensors | LibreHardwareMonitorLib ≥ 0.9.6 (PawnIO) — **optional**, elevated only |
|
||||
| Tier-2 fallback | **There is none, and Tier 2 is not a measurement.** Owner decision 2026-08-28: the ladder is two rungs — hooked, or duration + sensors + the reason. ~~ETW-based, no injection~~; ~~Intel PresentMon console binary~~ dropped 2026-08-27 after §S31 retired it. Whether a shipped build ever regains a no-injection measurement is `docs/20_OPEN_QUESTIONS.md` §G |
|
||||
| Storage | SQLite via Microsoft.Data.Sqlite + Dapper (no EF) |
|
||||
@@ -62,6 +63,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
|
||||
```
|
||||
FrameLedger.slnx # XML solution format (SDK default since .NET 10)
|
||||
NOTICE # copyright + the GPLv3 section 7 additional terms (beta.12, D45)
|
||||
CONTRIBUTING.md FORKING.md CODE_OF_CONDUCT.md # for people who build, contribute or redistribute
|
||||
global.json # pins the SDK band — see 12_BUILD
|
||||
build.ps1 # the quality gate; CI runs this identical script
|
||||
src/
|
||||
@@ -70,6 +73,10 @@ src/
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe
|
||||
FrameLedger.VkLayer/ # C++20 Vulkan implicit layer DLL + manifest JSON
|
||||
FrameLedger.Shm/ # header-only: ring buffer + record layout, shared by native & C# (mirrored)
|
||||
FrameLedger.NvapiBridge/ # C++ DLL loaded by the Agent (never a game): NVAPI telemetry, NGX state (P2 PR-E2)
|
||||
FrameLedger.ProcessStats/ # C++ DLL loaded by the Agent (never a game): the game process's memory (beta.12, D43)
|
||||
tests/ tools/ third_party/ # ctest suites; probes, hook-harness, vendor stubs; vendored headers
|
||||
# (these three lines added 2026-10-04 — the list stopped at Shm)
|
||||
FrameLedger.Domain/ # entities, metric calculators — zero dependencies
|
||||
# (Metrics/ WRITTEN 2026-09-09, P2 PR-A: frame times,
|
||||
# percentiles, lows, stutter, the FG window and its
|
||||
@@ -88,7 +95,8 @@ src/
|
||||
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
|
||||
# reader, HeldProcessLivenessSource, TargetResolver (path only,
|
||||
# never a pid), ProcessLauncher, the module snapshot, the marker scan
|
||||
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + ShmRecord struct mirror
|
||||
FrameLedger.Shared/ # IPC contracts (System.Text.Json source-gen) + the struct mirror (ShmLayout.cs;
|
||||
# it said "ShmRecord", a type that never existed, until 2026-10-04)
|
||||
FrameLedger.Agent/ # capture orchestrator: watcher, injector control, shm drain, recorder
|
||||
# BUILT 2026-09-10 (P2 PR-F): a Generic Host. `--serve` = watcher
|
||||
# (Application.Watch: ProcessWatcher, ProcessTree, DescendantElection,
|
||||
@@ -105,7 +113,9 @@ src/
|
||||
# is built as of 2026-09-14 (PR-5 Games/Dashboard, PR-6 summary +
|
||||
# charts, PR-7 trend/compare, PR-8a Settings/safety notices/Logs/
|
||||
# --diag, PR-8b tray + the Agent's maintenance flags, PR-9 first run
|
||||
# + Legal Gate FR-11); Strings.resx en/vi/ja
|
||||
# + Legal Gate FR-11); Strings.resx en/vi/ja. `--data-dir <copy>`
|
||||
# (beta.15, D52) = a VIEWER: no Agent started or contacted,
|
||||
# nothing on the PC changed, the profile's own folder refused
|
||||
FrameLedger.CaptureHost/ # UNSHIPPED, and since P2 PR-C (2026-09-09) a THIN SHELL: verbs,
|
||||
# the operator disclosure, the report consumer, and the composition
|
||||
# of Application.Capture.CaptureSession over Infrastructure's
|
||||
@@ -118,12 +128,20 @@ src/
|
||||
# is not what holds rule 1.
|
||||
tests/
|
||||
FrameLedger.Domain.Tests/ FrameLedger.Application.Tests/ FrameLedger.Infrastructure.Tests/
|
||||
FrameLedger.Agent.Tests/ FrameLedger.App.Tests/
|
||||
FrameLedger.CaptureHost.Tests/ # incl. the Category=Integration end-to-end case
|
||||
native/FrameLedger.Overlay.Tests/ # Catch2: ring buffer, record encode, fault policy
|
||||
tools/ # changelog-check, chokepoint-check, coverage-gate, gen-ac-floor,
|
||||
# hookinventory-check, license-check, package-closure-check,
|
||||
# rules-validate, vendor-exports, versioninfo-check,
|
||||
# vklayer-blastradius
|
||||
Shared/ fixtures/ # test helpers; the detection corpus and other fixtures
|
||||
~~native/FrameLedger.Overlay.Tests/~~ # never existed (corrected 2026-10-04): the native tests are
|
||||
# src/native/tests/ (ctest, mostly Catch2 — ring, guard, layout,
|
||||
# vklayer, unhook, rules budget, NVAPI bridge, process stats)
|
||||
tools/ # accuracy-check, changelog-check, chokepoint-check, coverage-gate,
|
||||
# gen-ac-floor, hookinventory-check, license-check, license-gather
|
||||
# (+ license-overrides/), notice-check, package-closure-check,
|
||||
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
|
||||
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
|
||||
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate),
|
||||
# buildid-check (beta.18: the release's build id in the shipped natives)
|
||||
# (six names added 2026-10-04)
|
||||
# (PowerShell). This line used to name three, one of which
|
||||
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
|
||||
# resx-gen (the committed Strings.Designer.cs generator).
|
||||
@@ -131,19 +149,31 @@ tools/ # changelog-check, chokepoint-check, coverage-gat
|
||||
# fl-layout-dump -> struct offsets for the C# mirror test
|
||||
# hook-harness -> dummy D3D11 + D3D12 + Vulkan + OpenGL app
|
||||
# (--vulkan since #140, --opengl since #141)
|
||||
# fl-probe-* -> guard, hook profile, interposer, NVAPI, process
|
||||
# stats, signer, Vulkan layer; fl-baseline-probe;
|
||||
# vendor-stubs/ -> fixture DLLs with the vendors' export names
|
||||
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
|
||||
guide/ # the user guide (beta.12, D44): ~~eight~~ short English pages for players, embedded in the
|
||||
# App (Help > User guide); README.md is its contents. docs/ is for developers.
|
||||
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
|
||||
# and the guide is the wiki's End-user part)
|
||||
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
|
||||
# publishes them with guide/ and LIMITATIONS.md to the Wiki tab at a release;
|
||||
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
|
||||
docs/ legal/ legal/licenses/
|
||||
```
|
||||
|
||||
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **Two facades since 2026-09-10:** `NativeAntiCheatGuard` (required — absent throws) and `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself), both by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why a third facade claims a name there rather than setting its own.
|
||||
Dependency direction: `App/Agent → Application → Domain`; **`Application → Shared` since 2026-09-09** (P2 PR-A, decision D1 — `Application.Metrics.FrameSampleMapper` is where `FlFrameRecord` becomes Domain's `FrameSample`, and `Application.Capture.CaptureSession`, hosted there since PR-C the same day, is written over the record; `DrainResult` moved to Shared with it); `Infrastructure` implements `Application` ports; Domain references nothing. **The native layer is reachable only through `Infrastructure`** — no P/Invoke anywhere else. **~~Two~~ Three facades since ~~2026-09-10~~ 2026-10-03:** `NativeAntiCheatGuard` (required — absent throws), `NativeNvapiBridge` (optional — absent is a missing telemetry layer that reports itself) and, since beta.12 (D43), `NativeProcessStats` (optional — the game process's own memory, read from outside the game; absent reads N/A), all by absolute path beside the assembly through its one `DllImport` resolver, `Infrastructure.Native.BesideThisAssembly`; the runtime allows one resolver per assembly, which is why the third facade claims a name there rather than setting its own.
|
||||
|
||||
## Coding conventions
|
||||
|
||||
**C# —** `Nullable enable`, `TreatWarningsAsErrors`, `AnalysisLevel latest-all`, file-scoped namespaces, Roslynator + Meziantou + VS Threading analyzers, `dotnet format` clean. Async suffixed `Async`, `ConfigureAwait(false)` off the UI. All user-visible strings from `.resx`. Timestamps UTC (unix-ms in SQLite); QPC ticks only inside the capture pipeline.
|
||||
|
||||
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: `/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`).
|
||||
**C++ —** `clang-format` (LLVM base, 4-space, 120 col) enforced in CI. No STL containers that allocate in hook paths. No `std::mutex` in hook paths. `-D_HAS_EXCEPTIONS=0` in the Overlay target. Every hook entry point wrapped per the `FL_HOOK_GUARD` macro (`17_HOOK_ENGINE`). Static analysis: ~~`/analyze` + clang-tidy (`bugprone-*`, `cert-*`, `concurrency-*`)~~ CodeQL (`codeql.yml`, a required check); `/analyze` and clang-tidy are not configured *(corrected 2026-10-04)*.
|
||||
|
||||
**Struct mirroring —** `FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock` each exist twice: `src/native/FrameLedger.Shm/include/fl_shm.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by `tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
|
||||
**Licence header —** every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`) opens with two comment lines, `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` (beta.12, owner decision D45). GPLv3 §7 requires additional terms to be named in the source files, and `NOTICE` holds them — (b) preserve the notices, (c) mark modified versions, (e) no trademark rights in the name. `tools/notice-check.ps1` is a `build.ps1` gate; `-Fix` writes a missing header. `src/native/third_party/` is excluded.
|
||||
|
||||
**Struct mirroring —** ~~`FlFrameRecord`, `FlShmHandshake`, `FlWriterState` and `FlControlBlock`~~ `FlShmHandshake`, `FlWriterState`, `FlControlBlock`, `FlDisplayState` (layout 4, beta.10), `FlFrameRecord` and `FlTolerance` (D33, beta.9) each exist twice *(corrected 2026-10-04)*: `src/native/FrameLedger.Shm/include/fl_shm.h` / `fl_tolerance.h` (**normative**) and `src/FrameLedger.Shared/ShmLayout.cs` as `[StructLayout(LayoutKind.Sequential)]`. `ShmLayoutMirrorTests` asserts size and every field offset on both sides **against JSON emitted by ~~`tools/fl-layout-dump`~~ `src/native/tools/fl-layout-dump`**, never a transcribed table, and walks the field list in both directions so a field added on either side alone fails.
|
||||
|
||||
It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReferences`), because offsets cannot see it: measured 2026-08-05, swapping the `fixed byte BuildId[32]` for this repo's own `[MarshalAs(ByValTStr)] string` idiom keeps `Marshal.SizeOf` at 64 and every offset correct while `Unsafe.SizeOf` collapses to **40** — a mirror that passes the obvious checks and cannot be read out of a memory-mapped view.
|
||||
|
||||
@@ -151,7 +181,7 @@ It also asserts **blittability** (`RuntimeHelpers.IsReferenceOrContainsReference
|
||||
|
||||
The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` gives the Agent a build id of its own and `ShmHandshakeValidator` performs the refuse-to-attach comparison `07_IPC` specifies (§S23-1). **Its default is `NotEvaluated`, not `Ok`** — a result nobody produced has validated nothing, the same rule `AntiCheatVerdict` follows.
|
||||
|
||||
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. `tools/hook-harness` is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
|
||||
**Dev mode —** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (recorded 2026-08-04). When it exists it runs the whole app with a synthetic frame source and no injection at all, and it is how the UI is meant to be developed; until then, do not plan work on the assumption that it is there. ~~`tools/hook-harness`~~ `src/native/tools/hook-harness` (path corrected 2026-10-04) is a dummy **D3D11 + D3D12 + Vulkan + OpenGL** app used to exercise hooks without a real game — `--vulkan` since #140 and `--opengl` since #141 (2026-09-06); this sentence said both were unwritten until 2026-09-09 (`docs/12_BUILD.md` §Targets is the accurate list).
|
||||
|
||||
## Definition of done (per PR)
|
||||
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Code of conduct
|
||||
|
||||
FrameLedger adopts the **[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)**
|
||||
(© Contributor Covenant contributors, licensed CC BY 4.0) as its code of conduct, for everyone who takes part in the
|
||||
project — in issues, pull requests, discussions and any other project space.
|
||||
|
||||
In short: be respectful and welcoming, criticise ideas rather than people, and do not harass, insult or demean anyone.
|
||||
The full text linked above is the code; this summary does not replace it.
|
||||
|
||||
## Reporting
|
||||
|
||||
Report behaviour that breaks the code to the maintainer at **contact@poli0981.dev**. Reports are read in confidence,
|
||||
and the maintainer decides on the response in line with the Covenant's enforcement guidelines — from a private note to
|
||||
a ban from the project's spaces.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Contributing to FrameLedger
|
||||
|
||||
Thank you for looking. FrameLedger is a small project with strict rules, because it loads code into games and a mistake
|
||||
can cost a user their account. This page says how to build it, what a change has to bring with it, what will not be
|
||||
merged, and under what licence your contribution is accepted.
|
||||
|
||||
## Before you start
|
||||
|
||||
- **Read `CLAUDE.md`'s *Non-negotiable rules* and `docs/19_SAFETY_AND_ANTICHEAT.md` first.** They constrain everything
|
||||
that touches a game.
|
||||
- **Open an issue before anything larger than a fix**, so the approach can be agreed before the work is done.
|
||||
- **A game with anti-cheat that FrameLedger fails to detect** is a safety bug: use the *Safety gap* issue form.
|
||||
- **A vulnerability in FrameLedger itself** goes the private route in `SECURITY.md`, never a public issue.
|
||||
- Everyone who takes part follows the `CODE_OF_CONDUCT.md`.
|
||||
|
||||
## Building
|
||||
|
||||
You need Windows 10 22H2 or later (x64), Visual Studio 2022 with the C++ workload (MSVC v143), CMake 3.28 or later,
|
||||
PowerShell 7, and the .NET SDK that `global.json` pins. Then:
|
||||
|
||||
```powershell
|
||||
./build.ps1 check
|
||||
```
|
||||
|
||||
That is the whole quality gate, and continuous integration runs the identical script: the native build and its tests,
|
||||
`clang-format`, the managed build with warnings as errors, `dotnet format`, every test project, and the repository's own
|
||||
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
|
||||
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
|
||||
|
||||
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
|
||||
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
|
||||
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
|
||||
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
|
||||
|
||||
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
|
||||
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
|
||||
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
|
||||
§Debugging says how to copy it safely).
|
||||
|
||||
## What a pull request brings with it
|
||||
|
||||
The definition of done is the one in `CLAUDE.md`:
|
||||
|
||||
- it builds without warnings (C# and C++), the tests are green, and `dotnet format` and `clang-format` are clean;
|
||||
- a change to the hook path states its measured overhead in the PR (`docs/14_TESTING.md` §Hook overhead);
|
||||
- a new hook is listed in `docs/17_HOOK_ENGINE.md` §Hook inventory and justified against rule 4;
|
||||
- every new user-visible string exists in `en`, `vi` and `ja` (`docs/09_I18N.md`);
|
||||
- a change that makes a document wrong updates that document in the same PR;
|
||||
- a change under `src/` adds an entry under `## [Unreleased]` in `CHANGELOG.md`;
|
||||
- every new source file carries the licence header — `./tools/notice-check.ps1 -Fix` writes it. A file you wrote
|
||||
yourself may name you in its second line instead, in the same form:
|
||||
`Copyright (C) <year> <your name> - additional terms under GPLv3 section 7: see NOTICE`.
|
||||
|
||||
The pull-request template lists the safety checks for changes to the capture layer.
|
||||
|
||||
## What will not be merged
|
||||
|
||||
Whatever its other merits, a change that
|
||||
|
||||
- adds any way to override, weaken or skip the anti-cheat guard (rule 2);
|
||||
- makes FrameLedger harder to detect — manual mapping, header erasure, thread hiding, unlinking modules, obfuscation,
|
||||
renamed binaries (rules 3 and 9);
|
||||
- reads or writes game memory outside the hooked calls (rule 4), or makes a hook able to crash a game (rule 5);
|
||||
- adds telemetry, analytics or any network request beyond the ones `legal/PRIVACY_POLICY.md` lists (rule 8);
|
||||
- turns injection on for a game the user did not individually enable (rule 1).
|
||||
|
||||
## Licensing of contributions
|
||||
|
||||
FrameLedger is licensed under the GNU GPL, version 3 only, with the additional terms in `NOTICE`. **By opening a pull
|
||||
request you confirm that you have the right to submit the change, and you license it under GPL-3.0-only, with the
|
||||
additional terms in `NOTICE` (GPLv3 §7 (b), (c) and (e)) applying to it as they apply to the rest of FrameLedger's own
|
||||
material.** There is no contributor licence agreement and no copyright assignment: you keep the copyright in your
|
||||
contribution. Code from elsewhere must come with a licence compatible with GPL-3.0-only and be listed in
|
||||
`legal/THIRD_PARTY_NOTICES.md`.
|
||||
|
||||
Changes written with AI assistance are welcome on the same terms — you are responsible for what you submit, as for any
|
||||
other change.
|
||||
|
||||
## Questions
|
||||
|
||||
Open an issue, or write to contact@poli0981.dev.
|
||||
@@ -69,6 +69,32 @@
|
||||
<IncludeSourceRevisionInInformationalVersion>false</IncludeSourceRevisionInInformationalVersion>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- beta.14 (D50): every managed binary names the product and who wrote it, as the native ones always have
|
||||
(19_SAFETY: a binary says plainly what it is). Explorer's Properties > Details and Task Manager read these. Until
|
||||
beta.14 the SDK's defaults stood: the Agent's Company and Product read "FrameLedger.Agent", each library's its own
|
||||
assembly name, and no managed binary carried a copyright. The copyright is the native FL_COPYRIGHT
|
||||
(src/native/CMakeLists.txt) word for word: tools/versioninfo-check.ps1 reads both from the built binaries and is
|
||||
red when they differ. The file description is the AssemblyTitle - an entry point sets its own, a library keeps its
|
||||
assembly name - and the Description is the Comments field, the native blocks' sentence for a library. The SDK
|
||||
stamps RepositoryUrl into every assembly as AssemblyMetadata; it is the App's IssueLink.Repository, and the App's
|
||||
AssemblyIdentityTests holds the two equal (a fork changes both - FORKING.md). -->
|
||||
<PropertyGroup>
|
||||
<Company>FrameLedger</Company>
|
||||
<Product>FrameLedger</Product>
|
||||
<Authors>poli0981</Authors>
|
||||
<Copyright>Copyright (C) 2026 poli0981. GPL-3.0-only with additional terms: see NOTICE</Copyright>
|
||||
<Description>Performance measurement tool. Identifies itself deliberately; see https://github.com/poli0981/frameledger</Description>
|
||||
<RepositoryUrl>https://github.com/poli0981/frameledger</RepositoryUrl>
|
||||
</PropertyGroup>
|
||||
|
||||
<!-- beta.12: the source a build was made from - release.yml passes the tag (a rehearsal, its commit); a local build has
|
||||
none. The App's links into the repository open THIS version's documents with it (Services/RepositoryLinks.cs).
|
||||
Every assembly since beta.14 (D50), not the App's alone: the two publishes build the same libraries into one
|
||||
out/app, and release.yml passes the same ref to both. -->
|
||||
<ItemGroup Condition="'$(FrameLedgerSourceRef)' != ''">
|
||||
<AssemblyMetadata Include="FrameLedgerSourceRef" Value="$(FrameLedgerSourceRef)" />
|
||||
</ItemGroup>
|
||||
|
||||
<!-- Test projects: documentation comments are noise, and xUnit's own
|
||||
analyzers already cover what matters there. -->
|
||||
<PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
|
||||
|
||||
@@ -25,6 +25,13 @@
|
||||
<PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.2" />
|
||||
<PackageVersion Include="ScottPlot.WPF" Version="5.1.59" />
|
||||
<PackageVersion Include="H.NotifyIcon.Wpf" Version="2.4.1" />
|
||||
<!--
|
||||
Markdig (Alexandre Mutel): Markdown rendered in the App (beta.12, owner request 4) - the Legal Gate, Help,
|
||||
About and the user guide show their documents rendered, not as raw text. BSD-2-Clause, no dependency on
|
||||
net10.0. The package ships no licence file, so its text is a reviewed override
|
||||
(tools/license-overrides/Markdig.txt). HTML is disabled in the pipeline (App/Markdown/MarkdownRenderer.cs).
|
||||
-->
|
||||
<PackageVersion Include="Markdig" Version="1.4.0" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Hosting and logging">
|
||||
@@ -68,8 +75,8 @@
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Analyzers (build-time only)">
|
||||
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.0" />
|
||||
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.266" />
|
||||
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.1" />
|
||||
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.299" />
|
||||
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.7.23" />
|
||||
</ItemGroup>
|
||||
|
||||
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
# Forking and redistributing FrameLedger
|
||||
|
||||
This page is for anyone who clones or forks FrameLedger — and above all for anyone who **gives builds of a modified
|
||||
FrameLedger to other people**. It says what the licence lets you do, what it asks of you when you distribute, and the
|
||||
practical things a fork has to change so that its users and FrameLedger's users do not get each other's updates, data
|
||||
or blame. It is written to be useful, not as legal advice; the texts that decide are `LICENSE` (the GNU GPL, version 3)
|
||||
and `NOTICE`.
|
||||
|
||||
## What the licence lets you do
|
||||
|
||||
FrameLedger is free software under the **GNU General Public License, version 3 only** (`GPL-3.0-only`). You may run it
|
||||
for any purpose, study and change its source, and share copies — changed or not — free of charge or for a fee. You do
|
||||
not need anyone's permission, and you do not have to accept the licence just to run the program (GPLv3 §9).
|
||||
|
||||
## What it asks when you distribute a build
|
||||
|
||||
"Distribute" here is the GPL's *convey*: giving a copy to someone else, including publishing an installer. Running
|
||||
FrameLedger yourself, or changing it for yourself, asks nothing of you.
|
||||
|
||||
- **The source goes with the build.** Whoever receives your binaries must be able to get the complete source code
|
||||
that builds them, under the same licence (GPLv3 §6) — the C++ and C# sources, the build scripts (`build.ps1`,
|
||||
`src/native/CMakeLists.txt`, the workflows) and everything else needed to rebuild them. Publishing the exact source
|
||||
tree at the tag you built from, next to the release, is the simplest way. An installer such as the Velopack
|
||||
`Setup.exe` counts as a binary.
|
||||
- **Keep the notices.** Ship `LICENSE`, `NOTICE` and the third-party licences with every copy. The release workflow
|
||||
already does this: the App's publish step copies them into `licenses\` beside the executables (`licenses\NOTICE.txt`,
|
||||
`licenses\FrameLedger-GPL-3.0.txt`, `licenses\THIRD_PARTY_NOTICES.md`, `licenses\nuget\`), and
|
||||
`.github/workflows/release.yml` refuses a published tree without them. Do not remove the copyright and licence
|
||||
headers from the source files.
|
||||
- **Say that it is changed.** A modified version must carry prominent notices that you modified it, and when
|
||||
(GPLv3 §5(a)).
|
||||
- **Add no restrictions.** You may not impose terms that take away the rights the GPL gives your users (GPLv3 §10) —
|
||||
an end-user agreement that forbids what the GPL permits is not allowed. FrameLedger's own EULA says that nothing in
|
||||
it limits those rights.
|
||||
|
||||
### The additional terms in `NOTICE`
|
||||
|
||||
FrameLedger's own material is licensed with three additional terms of the kinds GPLv3 §7 permits. In short:
|
||||
|
||||
- **(b)** keep the copyright line and the attribution *"Based on FrameLedger by poli0981 —
|
||||
https://github.com/poli0981/frameledger"* in your build's Appropriate Legal Notices (FrameLedger shows them under
|
||||
Help ▸ About);
|
||||
- **(c)** do not name a modified version "FrameLedger" alone, say in its notices and documentation that it is modified
|
||||
and by whom, and do not present its builds, installers or update feed as the original project's;
|
||||
- **(e)** no rights are granted in the name "FrameLedger" or the project's logo and icon, beyond saying truthfully
|
||||
where your work comes from ("based on FrameLedger", "a fork of FrameLedger").
|
||||
|
||||
`NOTICE` has the exact wording. These terms cover material written by FrameLedger's developer; how far they reach
|
||||
depends on the copyright in that material — parts of FrameLedger were written with AI assistance under the developer's
|
||||
direction. If the difference matters to you, ask a lawyer, not this page.
|
||||
|
||||
## What a fork that ships builds has to change
|
||||
|
||||
FrameLedger installs into the user's profile, keeps one database there, runs a background agent and registers a few
|
||||
system-wide names. A fork that keeps them **collides with an installed FrameLedger**: the two would update each other,
|
||||
share — and migrate — one database, and fight over the same pipe and shared memory. Change all of these together:
|
||||
|
||||
| What | Where | Why |
|
||||
|---|---|---|
|
||||
| Product name, icon, title | the App's resources, `--packTitle` in `release.yml`, `Strings.resx` | NOTICE (c) and (e) |
|
||||
| Update feed | `VelopackUpdateClient.RepositoryUrl` (`src/FrameLedger.App/Update/VelopackUpdateClient.cs`) | otherwise your users are offered FrameLedger's releases, and FrameLedger's users yours |
|
||||
| Install folder | `--packId` in `release.yml` (today `FrameLedger.App`) | Velopack installs into `%LOCALAPPDATA%\<packId>` and **deletes that folder on uninstall** — never choose a packId that equals any data folder |
|
||||
| Data folder | `LedgerPaths` (`src/FrameLedger.Infrastructure/Persistence/LedgerPaths.cs`) and the other `%LOCALAPPDATA%\FrameLedger` paths (`DetectionRulesFile`, `VkLayerLaunchEnvironment`, the Overlay's log folder, and the guard's own `fl::guard::RulesFilePath` in `src/native/FrameLedger.Injector/src/fl_ac_rules.cpp`) | a newer schema migrates the database in place and an older build cannot open it again |
|
||||
| Agent pipe | `IpcProtocol.PipeName` (`src/FrameLedger.Shared/Ipc/IpcProtocol.cs`) | the App talks to whichever agent owns the pipe |
|
||||
| Shared memory and mutex names | `Local\FrameLedger.*` (the ring, the tolerance channel, `SingleInstance`, the agent's instance lock) — in C# and in `src/native` | two programs must not open each other's ring |
|
||||
| Vulkan layer | `VK_LAYER_FRAMELEDGER_overlay`, its `HKCU\SOFTWARE\Khronos\Vulkan\ImplicitLayers` registration, and its `FRAMELEDGER_ENABLE_VK_LAYER` / `DISABLE_FRAMELEDGER_VK_LAYER` variables (the manifest template in `src/native/FrameLedger.VkLayer/` and `VkLayerLaunchEnvironment`) | one implicit layer per name — and a fork that keeps the variables is switched on by every FrameLedger launch |
|
||||
| Start with Windows | `RunAtLogon.DefaultValueName` (`src/FrameLedger.Infrastructure/Startup/RunAtLogon.cs`) | one `HKCU\…\Run` value per name |
|
||||
| Logon task | `LogonTask` (the Agent's maintenance verbs) | one task per name |
|
||||
| Issue and help links | `IssueLink.Repository` (`src/FrameLedger.App/Services/IssueLink.cs`) — `RepositoryLinks` builds every document link in the App from it and the source ref `release.yml` passes — plus the Releases link in `guide/01-install.md` and `.github/ISSUE_TEMPLATE/` | your users' reports belong in your tracker |
|
||||
| Who the documents name | `legal/EULA.md`, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md` name poli0981 as the Developer, with a contact | the person who distributes a build is the one its users deal with; review every claim they make, too — they describe FrameLedger's builds, not yours |
|
||||
| Version information | `FL_COMPANY_NAME` / `FL_PRODUCT_NAME` / `FL_COPYRIGHT` in `src/native/CMakeLists.txt`; `Company` / `Product` / `Authors` / `Copyright` / `Description` / `RepositoryUrl` in `Directory.Build.props` and the `AssemblyTitle` / `Description` of the App's and the Agent's csproj (since beta.14); and the names `tools/versioninfo-check.ps1` and the two `AssemblyIdentityTests` require | anti-cheat vendors and users identify the DLLs loaded into games and the processes beside them by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project, and the copyright line must be one line on every binary — the check compares them |
|
||||
| Checksums | your own `SHA256SUMS.txt` | users verify what *you* built |
|
||||
|
||||
The detection rules and the anti-cheat blocklist (`rules/detection-rules.json`) ship with each build; keeping them
|
||||
current for your users becomes your job.
|
||||
|
||||
## What we ask, and cannot require
|
||||
|
||||
The GPL does not allow adding restrictions, so the following is a request, not a condition. FrameLedger is built
|
||||
around a few rules (`CLAUDE.md`, *Non-negotiable rules*), and the reason is the people who use it:
|
||||
|
||||
- the anti-cheat guard is a hard gate with no override switch;
|
||||
- injection is opt-in, per game, and never automatic;
|
||||
- nothing is hidden from security software — no manual mapping, no header erasure, no renamed or obfuscated binaries;
|
||||
- the game's memory is never read or written outside the hooked calls;
|
||||
- no telemetry and no silent network requests.
|
||||
|
||||
A build that drops any of these can get its users' accounts banned. It is not FrameLedger, must not say it is
|
||||
(NOTICE (c)), and the original developer is not responsible for it.
|
||||
|
||||
## See also
|
||||
|
||||
`NOTICE` · `LICENSE` · `CONTRIBUTING.md` (if you would rather send your change upstream) ·
|
||||
`legal/TRADEMARKS.md` · `legal/THIRD_PARTY_NOTICES.md` · `docs/12_BUILD.md` (building from source)
|
||||
@@ -0,0 +1,34 @@
|
||||
<Project>
|
||||
|
||||
<!--
|
||||
Ships FrameLedger.ProcessStats.dll beside the importing project's output (beta.12, owner decision D43).
|
||||
|
||||
The third P/Invoke facade after the guard's and the NVAPI bridge's (docs/18_GPU_VENDOR_APIS.md §L1, the game
|
||||
process's memory): NativeProcessStats loads it BY ABSOLUTE PATH from AppContext.BaseDirectory and never falls back
|
||||
to a search, so it has to actually be there. Read-only, and NEVER loaded into a game — the Agent (and the unshipped
|
||||
capture host) load it into their own process for the 1 Hz read of a game's dedicated/shared GPU memory (the
|
||||
GPU Process Memory counters) and its working sets (GetProcessMemoryInfo).
|
||||
|
||||
Imported by the same three projects as the bridge: FrameLedger.Agent, FrameLedger.CaptureHost and
|
||||
FrameLedger.Infrastructure.Tests (the mirror test and the real read P/Invoke into the real DLL).
|
||||
|
||||
Warn rather than fail when absent, as the bridge does: an absent reader is a missing measurement (every game-memory
|
||||
field reads N/A), not a safety hole.
|
||||
-->
|
||||
<PropertyGroup>
|
||||
<FlProcessStatsOutDir>$(MSBuildThisFileDirectory)build\native\x64-release\FrameLedger.ProcessStats\</FlProcessStatsOutDir>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<None Include="$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll" Condition="Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
|
||||
<Link>FrameLedger.ProcessStats.dll</Link>
|
||||
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
|
||||
</None>
|
||||
</ItemGroup>
|
||||
|
||||
<Target Name="FlWarnOnMissingProcessStats" AfterTargets="Build"
|
||||
Condition="!Exists('$(FlProcessStatsOutDir)FrameLedger.ProcessStats.dll')">
|
||||
<Warning Text="FrameLedger.ProcessStats.dll was not found at $(FlProcessStatsOutDir). Run build.ps1 native first; the game's memory will read N/A." />
|
||||
</Target>
|
||||
|
||||
</Project>
|
||||
+77
-8
@@ -5,7 +5,7 @@ hooking on for — and reading the graphics calls the game makes. That is why it
|
||||
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
|
||||
page lists them in plain words; each item links to the document that has the details.
|
||||
|
||||
*Beta software: this page describes version 0.1.0-beta.10.*
|
||||
*Beta software: this page describes version 0.1.0-beta.21.*
|
||||
|
||||
## Games it will not measure
|
||||
|
||||
@@ -21,7 +21,8 @@ page lists them in plain words; each item links to the document that has the det
|
||||
- **32-bit games and Direct3D 9 games.** Only 64-bit Direct3D 11, Direct3D 12 and OpenGL games are measured
|
||||
from their own calls; a 32-bit or Direct3D 9 game is recorded without measurement.
|
||||
- **Vulkan games, unless FrameLedger starts them.** A Vulkan game is measured only when FrameLedger launches it
|
||||
with its Vulkan layer switched on; one started another way is not observed by the layer.
|
||||
with its Vulkan layer switched on — **Play** set to *Start directly* does; one started another way is not observed by
|
||||
the layer.
|
||||
- **Games that run as administrator,** unless you turn on *Run the agent as administrator* in Settings
|
||||
(off by default; Windows asks every time the agent starts). **A process Windows protects** stays closed
|
||||
either way.
|
||||
@@ -34,10 +35,23 @@ page lists them in plain words; each item links to the document that has the det
|
||||
## What an unmeasured session contains
|
||||
|
||||
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) and why nothing was measured.** Every
|
||||
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
|
||||
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))
|
||||
|
||||
## When a game crashed
|
||||
|
||||
- A session reads **crashed** when the game ended with an exception's code, when Windows logged a crash report of it,
|
||||
or — since 0.1.0-beta.14 — when it started its engine's crash reporter (Unreal's, CD PROJEKT RED's, Capcom's,
|
||||
BugSplat's) and exited within a minute. A game that handles its own crash quietly, starts no reporter and leaves no
|
||||
crash report reads **ended normally**, with its exit code.
|
||||
- A crash reporter is seen from a once-a-second look at running programs: one that opens and closes faster can be
|
||||
missed, and one started in the game's first 10 seconds is not counted (it could be a monitor that starts with the
|
||||
game). Unity's crash handler and Chromium's `crashpad_handler` start with every game that has them, so their presence
|
||||
says nothing. Sessions recorded before 0.1.0-beta.14 keep how they were stored — a few of them may read *crashed*
|
||||
because Windows logged a memory report about the game. ([details](docs/04_CAPTURE.md))
|
||||
|
||||
## Frame rate and frame generation
|
||||
|
||||
- **One inflated number is never shown.** When frame generation is measured, the page shows the game's own
|
||||
@@ -51,9 +65,18 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
|
||||
- **A session whose frame generation changed** (menus, loading, a settings change) shows the factor of the
|
||||
state it spent most of its time in, with the share of the session it covers — never an average of the two.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
- **Time below 30, 60 FPS and below the refresh rate** (since 0.1.0-beta.14) leaves out the small wobble of a game
|
||||
held at its limit: a frame counts as below 60 when it took 10 % longer than 1/60 s, or when the frames around it ran
|
||||
2 % slower. So a game running steadily just under the line — 59 FPS against 60 — reads partly as at it. Time below
|
||||
the refresh rate needs the monitor's rate, which a session saved after a crash does not have.
|
||||
- **VSync and tearing** (since 0.1.0-beta.14) are what the game *asked* for on each frame; the graphics driver or a
|
||||
variable-refresh display can override it, and FrameLedger cannot see which won. OpenGL and Vulkan games do not say,
|
||||
and read N/A. ([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Upscaling and ray tracing
|
||||
|
||||
- **The render scale chart** (since 0.1.0-beta.14) is drawn only where the render resolution was measured — the
|
||||
same games as *Render → output resolution* in the accuracy statement; elsewhere it says it was not measured.
|
||||
- The upscaler is read from the game's calls: DLSS and NIS through NVIDIA Streamline, and FSR through AMD's
|
||||
FidelityFX libraries. **Intel XeSS is not read** (its licence forbids it), FSR 2 and upscalers built into the
|
||||
game are not identified, and Vulkan and OpenGL games read N/A. Where no hook saw DLSS but the NVIDIA driver
|
||||
@@ -63,9 +86,21 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
|
||||
- **Ray tracing** is *Yes*, *No* or *N/A* — measured from the game's ray-tracing calls on Direct3D 12, and
|
||||
N/A where FrameLedger could not look. **Path tracing is never stated as a fact**: there is no API signal
|
||||
for it. You can correct any of these by hand, and your correction is labelled as yours.
|
||||
- HDR output, NVIDIA Reflex latency, each game's own video-memory use and shader-compilation stutter are
|
||||
**not measured yet** — they read N/A. Video memory in use on the whole graphics card is recorded.
|
||||
([Accuracy](legal/ACCURACY.md))
|
||||
- HDR output, NVIDIA Reflex latency, the video-memory budget Windows gives a game, and shader-compilation
|
||||
stutter are **not measured yet** — they read N/A. ([Accuracy](legal/ACCURACY.md))
|
||||
|
||||
## The game's memory
|
||||
|
||||
- **What is shown is what Task Manager's Details tab shows** for the game's process — *Dedicated GPU memory*,
|
||||
*Shared GPU memory* and *Memory* (the private working set) — read from Windows once a second, from outside
|
||||
the game. FrameLedger never looks inside the game's memory to get it.
|
||||
- **One process.** A measured game is its own process; for a game that is not measured, every process running
|
||||
the game's executable is added together. Launchers, crash reporters and other helper programs are not counted.
|
||||
- **The private working set needs a recent Windows**: Windows 10 22H2 or Windows 11 with the September 2023
|
||||
update or later. Without it the working set is shown instead, labelled as such.
|
||||
- A game that has not created anything on the graphics card yet (its first second, a launcher screen) reads
|
||||
N/A for video memory. AMD and Intel graphics cards have not been tested.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Display mode (full-screen, borderless, windowed)
|
||||
|
||||
@@ -83,16 +118,33 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
|
||||
|
||||
- The exact version is read for **Unreal Engine 4 and 5** games, from the game's executable file on disk.
|
||||
A studio can remove or rename what it is read from; then the page says the version was not found.
|
||||
**Unreal Engine 3 and older are not recognised.** Other engines show a version only where their files
|
||||
state one. ([Detection](docs/05_DETECTION.md))
|
||||
**Unreal Engine 3 and older are not recognised.**
|
||||
- Since beta.19 also **Unity**, **Godot** and **RPG Maker** (MV, MZ, XP, VX, VX Ace): from the engine's own files —
|
||||
Unity's player library or data file, Godot's data pack, RPG Maker's core script or the runtime library its `Game.ini`
|
||||
names. A Unity game whose data file is encrypted shows the version without its release letter (`2019.4.40`, not
|
||||
`2019.4.40f1`); an XP, VX or VX Ace game shows its runtime library's number, which is not the editor's.
|
||||
**RPG Maker 2000 and 2003 are not recognised.**
|
||||
- Since beta.20 also **Ren'Py**: from the engine's own version file (`renpy/vc_version.py`); a Ren'Py game whose engine
|
||||
names no version there shows none. Other engines show a version only where their files state one.
|
||||
([Detection](docs/05_DETECTION.md))
|
||||
|
||||
## Sensors
|
||||
|
||||
- GPU temperature, load, power and memory are best supported on **NVIDIA** GPUs. **AMD and Intel GPUs have
|
||||
not been tested** on real hardware yet.
|
||||
- **On a PC with more than one graphics card**, the GPU figures follow the card the game draws on once a Direct3D game
|
||||
has shown its first frame; before that, in an unmeasured session, and for OpenGL or Vulkan games they describe the
|
||||
first card Windows lists, and with two cards of one brand the temperature and load come from that brand's first card.
|
||||
The session's hardware details always name the first card. None of this has been tested on a machine with two cards.
|
||||
([Telemetry](docs/18_GPU_VENDOR_APIS.md))
|
||||
- **CPU temperature** needs *Run the agent as administrator* and the separately installed PawnIO driver, and
|
||||
has not been verified on real hardware yet. CPU load is the time the processor was busy — not Task
|
||||
Manager's "utility" figure, which can exceed 100%. ([Telemetry](docs/18_GPU_VENDOR_APIS.md))
|
||||
- **Whether the graphics card was held back by its power limit or by heat** (since 0.1.0-beta.14) is known only on
|
||||
NVIDIA cards, and only as it was at each once-a-second reading. On other cards it reads N/A.
|
||||
- **Frames per watt** (since 0.1.0-beta.14) counts the game's own frames — never generated ones — against the graphics
|
||||
card's power alone, not the processor's or the whole PC's. It reads N/A where the game's own frame rate is not known.
|
||||
([Metrics](docs/03_METRICS.md))
|
||||
|
||||
## Running the agent as administrator
|
||||
|
||||
@@ -112,6 +164,18 @@ you accept the prompt. Turn it on only if you trust everything that runs under y
|
||||
GeForce RTX 5080 with an Intel Core i7-14700KF on Windows 11); other hardware is untested.
|
||||
- **No real Vulkan or OpenGL game has been measured yet** — only FrameLedger's own test program.
|
||||
- There is **no in-game overlay**; everything is shown in the FrameLedger window.
|
||||
- **FrameLedger does not tell whether a game is safe to run.** It reads a game's files to find its engine and its
|
||||
anti-cheat, never to judge it, and recording or measuring a game vouches for nothing. Four itch.io downloads this
|
||||
project once used as examples turned out to carry malware ([details](docs/spike-notes.md)).
|
||||
|
||||
## Play
|
||||
|
||||
- **Through GOG GALAXY or itch, you finish in their app.** GOG GALAXY runs the game as its own shortcuts do, and the
|
||||
itch app asks which copy to launch. The Epic Games Launcher's link is the one its own shortcuts carry, and has not
|
||||
been tried on a real Epic game yet.
|
||||
- **FrameLedger never starts a game as administrator.** *Start directly* does not start a game that asks for it — start
|
||||
that one from its store or its own shortcut — nor a game whose recording is off: FrameLedger starts only what it
|
||||
records. While FrameLedger itself runs as administrator, Play starts every game directly, with your standard rights.
|
||||
|
||||
## Your data
|
||||
|
||||
@@ -128,3 +192,8 @@ you accept the prompt. Turn it on only if you trust everything that runs under y
|
||||
|
||||
FrameLedger's programs are **not code-signed**: Windows SmartScreen may warn when you install it, and the
|
||||
administrator prompt names an unknown publisher. Each release publishes SHA-256 checksums you can compare.
|
||||
|
||||
**An update waits while a game FrameLedger measured is still running.** The part of FrameLedger loaded into a game stays
|
||||
loaded until the game exits, and Windows will not let the update replace it; *Restart to update* says which file is held
|
||||
until you close that game ([details](docs/11_UPDATER.md)). Copies older than 0.1.0-beta.14 look only for stable
|
||||
releases unless you choose *Beta* in Settings ▸ Updates, and apply a downloaded update the next time they start.
|
||||
@@ -0,0 +1,45 @@
|
||||
FrameLedger
|
||||
Copyright (C) 2026 poli0981 <contact@poli0981.dev>
|
||||
|
||||
FrameLedger is free software: you can redistribute it and/or modify it under the terms of the
|
||||
GNU General Public License as published by the Free Software Foundation, version 3 of the
|
||||
License only (GPL-3.0-only).
|
||||
|
||||
FrameLedger is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
|
||||
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
||||
See the GNU General Public License for more details. Its full text is in the file LICENSE
|
||||
and at <https://www.gnu.org/licenses/gpl-3.0.html>.
|
||||
|
||||
|
||||
ADDITIONAL TERMS UNDER SECTION 7 OF THE GNU GENERAL PUBLIC LICENSE, VERSION 3
|
||||
|
||||
These terms apply to the material in this repository authored by poli0981. They do not
|
||||
apply to third-party components, which keep their own licences (legal/THIRD_PARTY_NOTICES.md).
|
||||
Every first-party source file points here with the line
|
||||
"Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE".
|
||||
|
||||
(b) Preservation of notices. You must preserve this notice, the copyright line above, and
|
||||
the attribution "Based on FrameLedger by poli0981 - https://github.com/poli0981/frameledger"
|
||||
in the Appropriate Legal Notices displayed by any work that contains this material
|
||||
(in FrameLedger itself: Help > About).
|
||||
|
||||
(c) Marking of modified versions. A modified version you convey must be marked in
|
||||
reasonable ways as different from the original version: it must not be named
|
||||
"FrameLedger" alone, it must say in its Appropriate Legal Notices and in its
|
||||
documentation that it is modified and by whom, and it must not present its builds,
|
||||
installers or update feed as those of the original project.
|
||||
|
||||
(e) Trademarks. These terms grant no rights under trademark law to use the name
|
||||
"FrameLedger", or the project's logo and icon, beyond describing the origin of a work
|
||||
truthfully (for example "based on FrameLedger").
|
||||
|
||||
Section 7 of the GPL permits additional terms of the kinds its paragraphs (a) to (f) list;
|
||||
the three above are of the kinds named in paragraphs (b), (c) and (e).
|
||||
|
||||
|
||||
SEE ALSO
|
||||
|
||||
FORKING.md what a redistributor of a modified version is asked to change
|
||||
legal/TRADEMARKS.md third-party names and marks
|
||||
legal/THIRD_PARTY_NOTICES.md the third-party components and their licences
|
||||
LICENSE the GNU General Public License, version 3
|
||||
@@ -4,9 +4,15 @@
|
||||
|
||||
> No telemetry. No accounts. All data stays on your machine.
|
||||
|
||||
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
|
||||
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
|
||||
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User
|
||||
guide, Help ▸ Limitations), and on the project's [wiki](https://github.com/poli0981/frameledger/wiki) with the developer
|
||||
pages.
|
||||
|
||||
<!-- accuracy-block:begin -->
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-10-13.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.21`** (2026-10-13), an unsigned installer built from that tag with its
|
||||
> checksums published beside it. The source holds the desktop app
|
||||
> (library, store import, charts, settings) and the background Agent, which records a session when a
|
||||
> game in the library runs (unless you switched its recording off), injects only into games you enabled
|
||||
@@ -15,8 +21,9 @@
|
||||
>
|
||||
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
|
||||
> OpenGL titles FrameLedger injects into. Vulkan titles are measured only when FrameLedger itself
|
||||
> starts the game with its Vulkan layer enabled, which today only the Agent's command-line launch
|
||||
> does. A Vulkan title started any other way is not observed by the layer; FrameLedger injects its
|
||||
> starts the game with its Vulkan layer enabled, which the Play button set to *Start directly* (since
|
||||
> beta.21) and the Agent's command-line launch do. A Vulkan title started any other way is not
|
||||
> observed by the layer; FrameLedger injects its
|
||||
> Direct3D component into it instead, and what that records on a Vulkan title has not been
|
||||
> verified. Direct3D 9 and every 32-bit title are not measured.
|
||||
> - **Which upscaler is running:** measured from the API a Direct3D title calls — DLSS or NIS through
|
||||
@@ -57,12 +64,29 @@
|
||||
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
|
||||
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
|
||||
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
|
||||
> files state.
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
|
||||
> player library or its data file — without the release letter where only the library's number is readable),
|
||||
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
|
||||
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
|
||||
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
|
||||
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
|
||||
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
|
||||
> once a second from Windows' own counters, from outside the game, in every session: a game
|
||||
> FrameLedger injects into through the handle it already holds, any other by opening it briefly with
|
||||
> the least access Windows offers (and adding up every process running its executable). Shown with
|
||||
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
|
||||
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
|
||||
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
|
||||
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
|
||||
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
|
||||
> measured from frame times.
|
||||
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
|
||||
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
|
||||
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
|
||||
> differs from the next; for Direct3D titles, how many frames asked to wait for the display and how many allowed
|
||||
> tearing — what the game asked, not what the driver did; the graphics card's clock speeds, fan speed and memory
|
||||
> 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.
|
||||
> - **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
|
||||
@@ -98,7 +122,7 @@ Most tools tell you your frame rate. FrameLedger tells you **what produced that
|
||||
- **Which upscaler is running** — DLSS / FSR, read from the API the game calls, not guessed from files on disk. Intel XeSS is not read: its SDK licence forbids it.
|
||||
- **Frame Generation, measured** — native and generated frames counted separately. Shown as `62 → 118 FPS (×1.9 FG)` when both are counted, and as a qualified Presented FPS when they are not — 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).
|
||||
- **The game's own VRAM and RAM** — Task Manager's figures for the game's process, read from outside the game in every session, with mean, median and peak (since beta.12). ~~and whether the driver was exceeding its budget~~ — the video-memory budget is not measured yet.
|
||||
- **Shader-compilation stutter attribution** — which frame spikes were pipeline compiles.
|
||||
- **PC latency** when the game uses Reflex.
|
||||
|
||||
@@ -115,7 +139,7 @@ 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**<br><br>**One narrow exception since beta.9 (owner decision D33):** 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 — and that FrameLedger has measured successfully at least twice may be hooked under a user-mode exception. 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. |
|
||||
| **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 |
|
||||
| **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 |
|
||||
@@ -127,32 +151,23 @@ FrameLedger is built to keep that risk small and to be honest about it:
|
||||
| Tier | How | What you get |
|
||||
|---|---|---|
|
||||
| **1** | Injected hooks (opt-in, per game) | Everything above |
|
||||
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
|
||||
| **2** | None — nothing is injected | **Session duration, whatever hardware telemetry your machine can provide, the game's own memory use (read from Windows, outside the game; since beta.12), and why there is nothing else** (which check refused, or that the hook failed, was not enabled, or the game is 32-bit). On NVIDIA that telemetry is measured to be GPU temperature, load, power, clocks, VRAM in use and fan speed, with no elevation; AMD and Intel are untested. Everything else reads `N/A` |
|
||||
|
||||
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.
|
||||
|
||||
> **This ladder used to have three rungs and a middle one that measured frame times without injecting.** It was to be built on Intel PresentMon; that was dropped on 2026-08-27 after measurement, and no replacement was chosen. **So frame times, FPS and the lows are now Tier-1-only.** Said plainly because the previous README promised them without injection, and a reader who remembers that would otherwise assume it still holds.
|
||||
|
||||
## Architecture
|
||||
|
||||
| Component | Runs as | Role |
|
||||
|---|---|---|
|
||||
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
|
||||
| `FrameLedger.Agent.exe` | Standard user — as administrator only when you turn that on in Settings, and Windows asks at every start (beta.10) | 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 everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and 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.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10 (22H2) or Windows 11, 64-bit
|
||||
- A 64-bit DirectX 11/12 or OpenGL game, or a Vulkan game FrameLedger starts, for hooked (Tier-1) capture. **32-bit games — including most DirectX 9 titles — cannot be measured at all**: the component FrameLedger loads is x64 and an x64 DLL cannot enter a 32-bit process. Such a title records duration and hardware telemetry and nothing else. *(This line previously said "supported at Tier 2 only", which meant frame times without injection. That tier no longer exists.)*
|
||||
- Optional: [PawnIO](https://pawnio.eu/) for CPU temperature, read only when the Agent runs as administrator (since 0.1.0-beta.3; not yet checked on real hardware). CPU load, memory in use and all GPU telemetry work without it
|
||||
|
||||
Elevation is **optional — for everything.** Hooked capture is the normal path and runs as a standard user, and there is no longer any tier that needs more than that. Elevation unlocks exactly two extras: CPU temperature sensors (~~not read yet~~ read with PawnIO, not yet checked on real hardware — see the block above), and 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.~~ — there is no ETW fallback to rely on. **Since beta.10 it is a choice in Settings** — *Run the agent as administrator*, off by default: Windows asks every time the agent starts, games you start from FrameLedger still run as you, and `LIMITATIONS.md` says what it does not change.
|
||||
|
||||
## Install
|
||||
|
||||
> **The latest pre-release is `v0.1.0-beta.10` (2026-09-28); before it `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
|
||||
> **The latest pre-release is `v0.1.0-beta.21` (2026-10-13); before it `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
|
||||
|
||||
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
|
||||
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**.
|
||||
@@ -164,13 +179,7 @@ Everything lives locally in `%LOCALAPPDATA%\FrameLedger`. The only network calls
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0-only. See `LICENSE`. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](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 (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
|
||||
|
||||
## Documentation
|
||||
|
||||
Developer/AI-facing docs in [`docs/`](docs/). Start with `CLAUDE.md`, then `docs/19_SAFETY_AND_ANTICHEAT.md` (which constrains everything else), then `docs/01_ARCHITECTURE.md`.
|
||||
GPL-3.0-only (see `LICENSE`), with the additional terms in [`NOTICE`](NOTICE) that GPLv3 section 7 permits: keep the copyright line and the attribution, mark a changed version as changed and do not call it "FrameLedger" alone, and no trademark rights in the name ([`legal/TRADEMARKS.md`](legal/TRADEMARKS.md)). In the app: Help ▸ About. Third-party components: [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
|
||||
|
||||
## Reporting a safety gap
|
||||
|
||||
@@ -178,6 +187,33 @@ If you find a game with anti-cheat that FrameLedger fails to detect, please open
|
||||
|
||||
**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.
|
||||
|
||||
## For developers and forks
|
||||
|
||||
FrameLedger is GPL-3.0-only free software, and you are welcome to build it, change it and redistribute it.
|
||||
|
||||
- **Build it:** [`docs/12_BUILD.md`](docs/12_BUILD.md) — `./build.ps1 check` is the whole quality gate, the same one CI runs.
|
||||
- **Contribute:** [`CONTRIBUTING.md`](CONTRIBUTING.md) — the definition of done, what will not be merged, and that a
|
||||
contribution is licensed GPL-3.0-only with the [`NOTICE`](NOTICE) terms (no CLA). Conduct:
|
||||
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md).
|
||||
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
|
||||
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
|
||||
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
|
||||
links to the document it summarises ([`wiki/`](wiki/) is their source).
|
||||
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
|
||||
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
|
||||
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
|
||||
|
||||
### Architecture
|
||||
|
||||
| Component | Runs as | Role |
|
||||
|---|---|---|
|
||||
| `FrameLedger.exe` | Standard user | Fluent desktop UI (WPF + [WPF UI](https://github.com/lepoco/wpfui)), charts, library, settings |
|
||||
| `FrameLedger.Agent.exe` | Standard user — as administrator only when you turn that on in Settings, and Windows asks at every start (beta.10) | 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) |
|
||||
|
||||
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 (telemetry and the driver's DLSS record today; Reflex latency is not read yet). No Intel or AMD GPU *telemetry* SDK is bundled — see `docs/18_GPU_VENDOR_APIS.md` for why. The one AMD component in the tree is five MIT headers from the FidelityFX SDK, used for types only so the upscaler hook can read an FSR title's own dispatch descriptor; nothing AMD-built is linked or redistributed.
|
||||
|
||||
---
|
||||
|
||||
**Status:** pre-release (beta). Ten tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
|
||||
**Status:** pre-release (beta). Twenty-one tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
|
||||
@@ -1,3 +1,6 @@
|
||||
# SPDX-License-Identifier: GPL-3.0-only
|
||||
# Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
#Requires -Version 7.0
|
||||
<#
|
||||
.SYNOPSIS
|
||||
@@ -317,13 +320,27 @@ function Invoke-ProjectGates {
|
||||
# Being plainly identifiable to anti-cheat is a requirement, not packaging
|
||||
# polish (docs/19_SAFETY_AND_ANTICHEAT.md). Reads the built binary, because
|
||||
# what ships is what an anti-cheat vendor sees.
|
||||
#
|
||||
# beta.14 (D50): BOTH HALVES. The rules prove themselves first (ten cases,
|
||||
# nine RED, each for its own reason), then the live pass reads the native five
|
||||
# and the managed eight from the App's and the Agent's build output, whose
|
||||
# ProductVersion is the VERSION file's here (release.yml passes the tag's).
|
||||
# Under -SkipNative the managed half still runs.
|
||||
Write-Step 'versioninfo-check'
|
||||
$versionTool = Join-Path $repo 'tools/versioninfo-check.ps1'
|
||||
if ((Test-Path $versionTool) -and -not $SkipNative) {
|
||||
Invoke-Checked 'versioninfo-check' { & $versionTool -BuildDir (Join-Path $repo "build/native/x64-$($Configuration.ToLower())") }
|
||||
}
|
||||
elseif ($SkipNative) {
|
||||
Skip-Gate 'versioninfo-check' 'native build skipped, so there is no binary to inspect'
|
||||
if (Test-Path $versionTool) {
|
||||
Invoke-Checked 'versioninfo-check (self-test)' { & $versionTool -SelfTest }
|
||||
$managedDirs = @('FrameLedger.App', 'FrameLedger.Agent' | ForEach-Object { Join-Path $repo "src/$_/bin/$Configuration" })
|
||||
$productVersion = (Get-Content (Join-Path $repo 'VERSION') -Raw).Trim()
|
||||
if ($SkipNative) {
|
||||
Invoke-Checked 'versioninfo-check (managed)' { & $versionTool -ManagedOnly -ManagedDir $managedDirs -ExpectedProductVersion $productVersion }
|
||||
Skip-Gate 'versioninfo-check (native)' 'native build skipped, so there is no binary to inspect'
|
||||
}
|
||||
else {
|
||||
Invoke-Checked 'versioninfo-check' {
|
||||
& $versionTool -BuildDir (Join-Path $repo "build/native/x64-$($Configuration.ToLower())") -ManagedDir $managedDirs -ExpectedProductVersion $productVersion
|
||||
}
|
||||
}
|
||||
}
|
||||
else {
|
||||
Skip-Gate 'versioninfo-check' 'tools/versioninfo-check.ps1 not implemented yet'
|
||||
@@ -406,7 +423,7 @@ function Invoke-ProjectGates {
|
||||
Write-Step 'license-check'
|
||||
$licenseTool = Join-Path $repo 'tools/license-check.ps1'
|
||||
if (Test-Path $licenseTool) {
|
||||
# P4 PR-6: the NuGet half's generator proves itself first (fourteen cases, five that must be RED), then
|
||||
# P4 PR-6: the NuGet half's generator proves itself first (sixteen cases since beta.12, six that must be RED), then
|
||||
# license-check runs its live -Check over this build's restore output as its section 3.
|
||||
Invoke-Checked 'license-gather (self-test)' { & (Join-Path $repo 'tools/license-gather.ps1') -SelfTest }
|
||||
Invoke-Checked 'license-check' { & $licenseTool }
|
||||
@@ -439,6 +456,23 @@ function Invoke-ProjectGates {
|
||||
Skip-Gate 'accuracy-check' 'tools/accuracy-check.ps1 not implemented yet'
|
||||
}
|
||||
|
||||
# beta.12 (D45): GPLv3 section 7 wants additional terms named "in the relevant source files", so every
|
||||
# first-party source file opens with the SPDX line and the NOTICE pointer. Self-test first (seven cases, both
|
||||
# directions), then the live pass over the tracked tree; ./tools/notice-check.ps1 -Fix writes a missing header.
|
||||
Write-Step 'notice-check'
|
||||
$noticeTool = Join-Path $repo 'tools/notice-check.ps1'
|
||||
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
|
||||
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
|
||||
|
||||
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/ and LIMITATIONS.md, and wiki.yml publishes it when a
|
||||
# release is made. A link or a section that leads nowhere, a page nothing leads to, a sidebar out of the guide's
|
||||
# order, a path that names nothing or a version written into a page is red here, not on the published wiki.
|
||||
# Self-test first (nine cases, both directions), then the live assembly into a temporary folder.
|
||||
Write-Step 'wiki-check'
|
||||
$wikiTool = Join-Path $repo 'tools/wiki-build.ps1'
|
||||
Invoke-Checked 'wiki-check (self-test)' { & $wikiTool -RepoRoot $repo -SelfTest }
|
||||
Invoke-Checked 'wiki-check' { & $wikiTool -RepoRoot $repo -Check }
|
||||
|
||||
Write-Step 'changelog-check'
|
||||
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
|
||||
if (Test-Path $changelogTool) {
|
||||
@@ -454,6 +488,12 @@ function Invoke-ProjectGates {
|
||||
Write-Step 'release-notes'
|
||||
Invoke-Checked 'release-notes (self-test)' { & (Join-Path $repo 'tools/release-notes.ps1') -SelfTest }
|
||||
|
||||
# beta.18: the build id a release hands CMake (read from the clean checkout before the date substitution edits
|
||||
# legal/*.md) is read back out of the published native binaries by release.yml. Self-test only here — the live
|
||||
# pass needs that id, which only a release has (12_BUILD §Release-time token substitution).
|
||||
Write-Step 'buildid-check'
|
||||
Invoke-Checked 'buildid-check (self-test)' { & (Join-Path $repo 'tools/buildid-check.ps1') -SelfTest }
|
||||
|
||||
# 09_I18N's gate, built with the first .resx family (P3 PR-2, 2026-09-13): every key in en/vi/ja, ja
|
||||
# Safety_* marked for human review, the generated accessor current. Self-test first (at least four
|
||||
# cases must go red), then the live pass; a tree with no family is red, not skipped.
|
||||
|
||||
+20
-9
@@ -23,11 +23,18 @@
|
||||
│ ├ upscaler hooks: NGX · Streamline · FFX · XeSS │
|
||||
│ ├ RT hooks: CreateStateObject · DispatchRays · BuildRaytracingAS │
|
||||
│ ├ PSO hooks: pipeline creation (stutter attribution) │
|
||||
│ ├ per-process VRAM: IDXGIAdapter3::QueryVideoMemoryInfo │
|
||||
│ ├ (per-process VRAM via QueryVideoMemoryInfo: never built — D43 reads │
|
||||
│ │ the game's memory from outside, in the Agent's ProcessStats.dll) │
|
||||
│ └ ring writer (allocation-free, lock-free, SEH-guarded) │
|
||||
└───────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
> **Corrected 2026-10-04 — the game-process box names hooks that were never built.** ~~NGX · XeSS ·
|
||||
> CreateStateObject · PSO hooks~~: NGX is licence-blocked, XeSS stops at the runtime census by licence, and
|
||||
> `CreateStateObject` and pipeline creation are unwritten rows of `17_HOOK_ENGINE` §Hook inventory. What the Overlay
|
||||
> does install: the DXGI present path, `wglSwapBuffers`, the Streamline and FidelityFX entry points, the two
|
||||
> `ID3D12GraphicsCommandList4` ray-tracing methods, and the `LoadLibraryExW` wake.
|
||||
|
||||
> `*` **`AntiCheatGuard` is a facade, not an implementation.** The guard is
|
||||
> native (`20_OPEN_QUESTIONS` §S13(a)); the box above is the P/Invoke wrapper
|
||||
> in `Infrastructure` that the Agent calls. Nothing managed parses rules or
|
||||
@@ -57,8 +64,8 @@
|
||||
|
||||
| Tier | Mechanism | Gets you | When used |
|
||||
|---|---|---|---|
|
||||
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT/PT evidence, per-process VRAM, PSO stutter attribution, Reflex latency, present flags | Offline/single-player titles the user opted in |
|
||||
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every measured field reads `N/A` (FR-4.9) | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
|
||||
| **1** | Injected hooks (default when the user enabled it and the guard passed) | Everything: exact render/output res, upscaler + quality, FG ground truth, RT ~~/PT~~ evidence, ~~per-process VRAM, PSO stutter attribution, Reflex latency,~~ present flags *(corrected 2026-10-04: path tracing, the in-game VRAM, PSO attribution and Reflex latency have no producer — `05_DETECTION` §Runtime facts)* | Offline/single-player titles the user opted in |
|
||||
| **2** | None | **Session duration, whatever hardware telemetry this machine can provide, and the REASON there is nothing else** — which check refused, or that the hook failed, was not enabled, or the target is 32-bit. Every ~~measured~~ frame field reads `N/A` (FR-4.9) *(corrected 2026-10-04: two facts are measured from outside the game in both tiers — the display mode (beta.10) and the game process's memory (beta.12, D43))* | Guard refused, hook failed, user chose not to hook, or a target the Overlay structurally cannot enter |
|
||||
|
||||
Tier is recorded per session (`sessions.capture_tier`) and shown in the UI, because metric availability differs and comparing across tiers must be explicit.
|
||||
|
||||
@@ -90,7 +97,7 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
|
||||
- Agent idles at ~0% CPU: 1 Hz process poll. No capture machinery exists until a tracked game launches.
|
||||
- Session ends when the process tree exits, or on safety unhook, or on user stop.
|
||||
- The DLL is **not unloaded** from a live process after unhooking (threads may still be inside trampolines). It disables its hooks, stops writing, and goes dormant until the process exits. Documented, deliberate.
|
||||
- UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.
|
||||
- ~~UI exit does not stop the Agent when background capture is enabled; otherwise UI sends `Shutdown`.~~ *(Corrected 2026-10-04: closing the UI never stops the Agent. `Shutdown` is sent only for an update, by the uninstall hook and for the admin mode's restart; the background-capture setting was read by nothing, and its switch is gone since beta.12 — `06_DATA_MODEL` §Settings registry.)*
|
||||
- Single instance via named mutexes; the ring name is per-PID so multiple games can be captured simultaneously (rare but supported).
|
||||
|
||||
> **The single instance was specified here and not built until 2026-09-17**, and 0.1.0-beta.1 ran four Agents: an
|
||||
@@ -110,12 +117,12 @@ Guard re-runs every 30 s for the life of the session; anti-cheat appearing late
|
||||
| Anti-cheat detected pre-injection | Refuse, explain which signal fired, offer Tier 2 |
|
||||
| Anti-cheat detected mid-session | Immediate clean unhook, `exit_status = unhooked_safety`, prominent notice |
|
||||
| Injection API fails (access denied, protected process) | Log, no retry loop, offer Tier 2 + "run Agent elevated" hint — elevation here is about *attaching to an elevated target*, not about reaching a tier; Tier 2 needs none |
|
||||
| Hook faults 3× | DLL self-disables, sets fault flag in handshake block, Agent finalizes session as `degraded` |
|
||||
| Hook faults 3× | DLL self-disables, sets ~~fault flag in handshake block~~ `FlWriterState.status` to `SELF_DISABLED` *(corrected 2026-10-04)*, Agent finalizes session as `degraded` |
|
||||
| Game crashes ≤ 60 s after injection, twice | Hooking auto-disabled for that game, Tier 2 takes over |
|
||||
| Ring overflow (Agent stalled) | Overwrite-oldest; dropped count published in the ring header → session flagged with a data-quality warning |
|
||||
| Ring overflow (Agent stalled) | Overwrite-oldest; ~~dropped count published in the ring header~~ the Agent counts drops from its own read index *(corrected 2026-10-04: the writer keeps no reader index and publishes no count — `04_CAPTURE` §Ring draining)* → session flagged with a data-quality warning |
|
||||
| Layout/version mismatch DLL ↔ Agent | Agent refuses to attach, tells user to restart the game after update |
|
||||
| Vendor API unavailable (no NVAPI etc.) | GPU telemetry degrades to `N/A`; frame metrics unaffected |
|
||||
| DB locked/corrupt | Integrity check + backup-and-recreate in Tools |
|
||||
| DB locked/corrupt | Integrity check + backup~~-and-recreate~~ in Tools ▸ Database maintenance *(corrected 2026-10-04: there is no recreate action)* |
|
||||
|
||||
## Data directory
|
||||
|
||||
@@ -126,11 +133,15 @@ ledger.db SQLite (WAL)
|
||||
rules\detection-rules.json engine/platform/feature + anticheat blocklist
|
||||
logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session end, never mid-frame)
|
||||
crashdumps\*.dmp
|
||||
breadcrumbs\<pid>.json pre-injection breadcrumb (19_SAFETY §Crash safety)
|
||||
breadcrumbs\<pid>.json (corrected 2026-10-04: never created — the breadcrumb is the .partial file's header and notes)
|
||||
tmp\<sessionGuid>.partial crash-safety flush of raw buffers, every 60 s (04_CAPTURE §Ring draining)
|
||||
covers\*.jpg
|
||||
covers\*.jpg (corrected 2026-10-04: never created — nothing writes games.cover_path)
|
||||
```
|
||||
|
||||
*(beta.15, D52: `FrameLedger.exe --data-dir <folder>` reads a COPY of this folder instead — a viewer that starts and
|
||||
contacts no Agent and changes nothing on the PC, with its own `logs\` and `crashdumps\` beside the copy; `08_UI` §Shell.
|
||||
The profile's own folder is refused there.)*
|
||||
|
||||
## Key design decisions (ADR)
|
||||
|
||||
- **ADR-1 (superseded):** ~~Passive ETW only; injection out of scope.~~ Replaced by ADR-7.
|
||||
|
||||
+11
-7
@@ -10,6 +10,9 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable.
|
||||
- FR-1.4 Remove game (asks whether to keep or delete its sessions).
|
||||
- FR-1.5 "Supports" row shows shipped-capability hints (DLSS/FSR/XeSS/FG) — visually distinct from measured per-session values (`05_DETECTION` §Capability hints).
|
||||
- FR-1.7 Delete all sessions (beta.11, owner decision D40): of one game from its page, or of every game from Settings ▸ Data, after a confirmation that says how many — with their frame and sensor series and notes; the library, the settings and every consent stay. The Agent deletes them (the rows are its, `06_DATA_MODEL` §Writer ownership) and refuses while a session it would delete under is being recorded.
|
||||
- FR-1.8 Uninstalled games leave the library by themselves (beta.19, owner decision D55, amending D41): an entry whose executable has been gone for ten minutes — its drive connected and the folder it was installed in still there, so an unplugged or re-lettered drive never counts, and neither does a folder Windows will not list (`ExecutablePresenceProbeTests`) — and that has no session (stored, being recorded or waiting to be recovered) is removed by the Agent, behind Settings ▸ Data ▸ *Remove uninstalled games* (on by default). Never an entry carrying an anti-cheat block, an exception or a failed-trial mark (FR-2.2, rule 2). The App is told (`GameRemoved`).
|
||||
- FR-1.9 Play (beta.21, owner decision D59): a game's page and each library entry start the game — through the app of the store whose own records name its folder (Steam, the Epic Games Launcher, GOG GALAXY, itch), or by the agent's launch mode (FR-3.2), as Settings ▸ Games says; never as administrator, and never in a viewer (`08_UI` §Games).
|
||||
- FR-1.6 Recording switch per entry (2026-09-23, HANDOFF D29): off, the program is not watched at all — no session, no measurement, no injection — and a session of it that is running stops. On by default; entries an old import made for Steam's own tools start with it off. The library card says "Not recorded".
|
||||
|
||||
### FR-2 Hooking consent & control (new, safety-critical — see `19_SAFETY`)
|
||||
@@ -24,12 +27,12 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
|
||||
### FR-3 Session capture
|
||||
- FR-3.1 Watcher detects tracked exe launches (1 Hz) and captures automatically at the highest permitted tier.
|
||||
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init).
|
||||
- FR-3.2 Launch mode: start the game from FrameLedger for suspended-launch injection (catches startup-time upscaler init). *(The App reaches it since beta.21: Play set to Start directly sends `LaunchGame` — FR-1.9.)*
|
||||
- FR-3.3 Attach mode for games launched externally; sessions flagged `late_attach`.
|
||||
- FR-3.4 Track the process tree; capture the descendant that actually presents.
|
||||
- FR-3.5 Per-frame records for the whole session; telemetry at 1 Hz (configurable 0.5–2 s).
|
||||
- FR-3.6 Session ends on process-tree exit, safety unhook, or user stop. Sessions under the minimum length (default 30 s) are discarded.
|
||||
- FR-3.7 Crash detection: nonzero exit code or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
|
||||
- FR-3.7 Crash detection: ~~nonzero exit code~~ an exception's exit code *(corrected 2026-10-04: since beta.8, `ExitStatusMapper.IsExceptionCode` — End task's exit code 1 is `normal`, the code kept in `capture_notes`; `04_CAPTURE` §Crash & exit classification)* or matching Application Error 1000 / WER 1001 events → `exit_status = crashed`.
|
||||
- FR-3.8 Post-session toast with summary + "View".
|
||||
- FR-3.9 Pause/resume capture globally from tray.
|
||||
|
||||
@@ -38,9 +41,9 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-4.2 **Native vs Displayed FPS + FG factor**, always shown together (`62 → 118 FPS (×1.9 FG)`).
|
||||
- FR-4.3 *(Tier 1)* Measured upscaler identity, quality preset, render resolution, output resolution, upscale ratio; mid-session changes captured as segments.
|
||||
- FR-4.4 *(Tier 1)* Measured RT activity (`rt_frame_pct`, `rays_per_pixel`, RT PSO count); RR from the NGX feature; PT as a confidence-scored suggestion only.
|
||||
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage.
|
||||
- FR-4.5 *(Tier 1)* Per-process VRAM usage/budget and budget-exceeded percentage. *(beta.12, owner decision D43: the **usage** half is met for **both tiers** from outside the game — the game process's dedicated and shared GPU memory, Task Manager's columns — with its private working set, working set and commit beside it, mean / median / peak (`03_METRICS` §Game process memory). The budget and its exceeded percentage stay unmeasured, `20_OPEN_QUESTIONS` §M11.)*
|
||||
- FR-4.6 *(Tier 1)* PSO-compilation stutter attribution; *(Tier 1 + Reflex)* PC latency avg/p95.
|
||||
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM.
|
||||
- FR-4.7 Telemetry aggregates: CPU/GPU temp, hotspot, loads, power, throttle %, RAM. *(beta.12: every stored series also has its median and minimum, in `sensor_stats_json`.)*
|
||||
- FR-4.8 Sufficiency guards: 0.1% Low needs ≥ 10,000 app frames, 1% Low ≥ 1,000; else `N/A`.
|
||||
- FR-4.9 Any metric unavailable at the session's tier renders `N/A` — never an estimate presented as measurement.
|
||||
|
||||
@@ -55,6 +58,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-6.1 Sessions table per game: date, duration, tier badge, Native, Displayed, FG×, lows, resolution + upscaler, RT/PT/RR chips, crash badge, tags.
|
||||
- FR-6.2 Compare 2–5 sessions; **mixed-tier comparisons require explicit acknowledgement** and are marked on the chart.
|
||||
- FR-6.3 Hardware snapshot per session; trend charts mark changes ("GPU driver 572.16 → 576.02").
|
||||
- FR-6.6 Charts across a game's sessions (beta.11, owner decision D39): the Sessions tab opens with an overview of every hooked session's rate and lows (Presented FPS, or Native and Displayed where frame generation was measured; 1% and 0.1% lows), a click selecting the session; and the Trend draws more metrics beside the selected one, two units at most (the second against the right axis).
|
||||
- FR-6.4 Sessions with mid-session settings changes are excluded from trends by default, with a toggle.
|
||||
- FR-6.5 Session tags and notes.
|
||||
|
||||
@@ -62,7 +66,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
- FR-7.1 Static: engine, engine version, store platform, store id, publisher, game version (`05_DETECTION`; the Unreal Engine version since 2026-09-27, §Engine version).
|
||||
- FR-7.2 Runtime: API, present mode, swap effect, HDR, upscaler, FG, RT — all Tier 1, all measured. (Present mode and HDR have no writer yet, `05_DETECTION` §Runtime facts; swap effect is written since beta.10 from the display-mode sample.)
|
||||
- FR-7.4 Display mode (beta.10, owner request 2026-09-27): how each session's game was shown — exclusive fullscreen, borderless, windowed, minimised, or *fullscreen or borderless* where nothing could tell the two apart — as a share of the session's time, with the window, back buffer and monitor sizes; both tiers (Tier 2 from the window alone); shown on the session summary, the game page, the Trend (three share metrics) and Compare, and exported (`03_METRICS` §Display mode).
|
||||
- FR-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.**
|
||||
- FR-7.3 Rules ship as `detection-rules.json`, updatable independently of releases; **anticheat-block updates apply regardless of the user's rules auto-update preference.** *(Unmet — corrected 2026-10-04: there is no rules feed and no auto-update preference. Rules change only with a release: `RulesSeeder` installs them, Tools ▸ Update detection rules re-seeds them — `20_OPEN_QUESTIONS` §S20 feed half.)*
|
||||
|
||||
### FR-8 Tri-state flags
|
||||
- FR-8.1 `Yes / No / N/A` for Ray Tracing, Path Tracing, Ray Reconstruction, per session, with source (`measured | manual | inherited`).
|
||||
@@ -79,10 +83,10 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
> **beta.10 (D34):** "Agent elevation (optional — explains what it unlocks)" is the admin mode — *Run the agent as
|
||||
> administrator*, off by default, a disclosure before it turns on, Windows' prompt at every Agent start (`01_ARCHITECTURE`
|
||||
> ADR-9, `08_UI` §Settings).
|
||||
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, online metadata opt-in, reopen legal documents.
|
||||
Language (en/vi/ja), theme, start with Windows, minimize to tray, background capture, **global hooking kill switch**, min session length, telemetry interval, retention, Agent elevation (optional — explains what it unlocks), Vulkan layer registration state, update channel, ~~online metadata opt-in,~~ reopen legal documents *(corrected 2026-10-04: the opt-in has had no row since 2026-09-16 because no store request exists, and the background-capture switch — read by nothing — is gone since beta.12; `06_DATA_MODEL` §Settings registry)*. **beta.11 (owner request 2026-10-03: no row without a control):** Delete all sessions (FR-1.7, a *Data* section); the elevation state is a line of the admin mode's own row, not a row of its own; the hook-enabled list shows only while a game has hooking on; the language row carries no separate note.
|
||||
|
||||
### FR-11 Legal Gate
|
||||
First run blocks until the user accepts EULA, GPLv3 notice, Disclaimer, Privacy Policy. Re-shown when a document version increments. The injection risk is stated in the Disclaimer *and* repeated at per-game consent (FR-2.1) — once is not enough for something that can cost an account.
|
||||
First run blocks until the user accepts ~~EULA, GPLv3 notice, Disclaimer, Privacy Policy~~ the EULA, the Disclaimer and the Privacy Policy; **the GPLv3 is shown beside them for information and needs no acceptance** (GPLv3 §9 — "You are not required to accept this License in order to receive or run a copy of the Program"; changed beta.12, owner decision D45, `08_UI` §First-run flow). Re-shown when a document version increments. The injection risk is stated in the Disclaimer *and* repeated at per-game consent (FR-2.1) — once is not enough for something that can cost an account.
|
||||
|
||||
### FR-12 Updates
|
||||
Velopack against GitHub Releases; silent startup check, manual check in Help; error dialogs mapped per `11_UPDATER`. **Updates never apply while a game is hooked** — deferred to session end (the DLL on disk must not change under a running game).
|
||||
|
||||
+128
-11
@@ -1,6 +1,6 @@
|
||||
# 03 — Metrics
|
||||
|
||||
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).
|
||||
**Single source of truth** for every number FrameLedger displays. ~~Implement in `FrameLedger.Domain.Metrics` with golden tests (`14_TESTING`).~~ **Implemented in `FrameLedger.Domain.Metrics` since 2026-09-09 (P2 PR-A), with the goldens `14_TESTING` names:** `FrameTimeSeries` (frame times from QPC, gaps excluded), `Percentile` (linear), `FrameStatistics` (median / lows / min / max / σ with the sufficiency guards), `RollingMedian` + `StutterDetector`, `FgWindow` + `FgRefusal` (the factor and every refusal, as facts — the English lives with the report), `UpscaleExtent`, `SegmentBuilder`, `RtVerdict` / `HdrVerdict` (the tri-states), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates`. They consume `FrameSample` and `WriterFacts` — Domain's own types, since Domain references nothing — and `Application.Metrics.FrameSampleMapper` is the one place a shared-memory record becomes one; the Domain enums are pinned to `FrameLedger.Shared`'s in both directions by `MetricEnumMirrorTests`. The frame-generation LADDER (rung 0 / 1 / 3 / 4 as a verdict, and the withheld `none`) ~~is not yet a Domain type: it is still the capture host's prose in `MeasuredFacts`, and lands with the recorder that stores `fg_mode` (PR-D).~~ *(Corrected 2026-10-04: it landed with PR-D on 2026-09-10 as `Application.Recording.FgLadder` — in Application, not Domain. The session row (`SessionAggregator`), the live card (`SessionProgressCalculator`) and the capture host's report all read it; `MeasuredFacts` keeps only the host's strings.)*
|
||||
|
||||
Every metric declares which **capture tier** it requires (`01_ARCHITECTURE` §Capture tiers). A Tier-2 session simply has `N/A` where Tier-1 data is missing — never a silently degraded estimate presented as fact.
|
||||
|
||||
@@ -38,6 +38,9 @@ Let `D` = session duration (first → last present), `F_app` = frames the *game*
|
||||
| **Stutter time %** | `Σ ft_app[stutter] / Σ ft_app × 100` | 1 |
|
||||
| **PC latency** | mean/p95 of `reflexLatencyUs` when Reflex reports it | **1 only** |
|
||||
| **PSO stutter %** | share of stutter frames with `psoCreatedThisFrame > 0` | **1 only** |
|
||||
| **Time below 30 / 60 FPS** (beta.14) | share of `Σ ft_app` in frames that count as below X — `ft > 1.10 × 1000/X`, or the nine-frame rolling median `> 1.02 × 1000/X` (§Pacing) | 1 |
|
||||
| **Time below refresh** (beta.14) | the same over **presents**, X = `display_monitor_hz` — the display's rate, so over what the display received | 1 |
|
||||
| **Frame to frame** (beta.14) | mean `\|ft_app[k] − ft_app[k−1]\|` over neighbouring intervals, ms | 1 |
|
||||
|
||||
**Percentile method:** sort ascending, linear interpolation between closest ranks (NumPy `linear` / Excel `PERCENTILE`). Document it, test it — tools differ and users will compare numbers.
|
||||
|
||||
@@ -90,6 +93,41 @@ toward the session's data-quality warnings.
|
||||
|
||||
**Sufficiency guards (FR-4.8):** 0.1% Low needs ≥ 10,000 application frames, 1% Low ≥ 1,000; otherwise `N/A`.
|
||||
|
||||
## Pacing (beta.14, D49)
|
||||
|
||||
**Time below 30 / 60 FPS and below the refresh rate** are shares of the measured time — `Σ ft (counted) / Σ ft` — so a long
|
||||
hitch weighs what a player sits through, not one frame among many. **Frame to frame** is the mean change from one frame
|
||||
time to the next over neighbouring intervals (`FrameTimeSeries.FollowsBreak`: a pair with an interval left out between —
|
||||
a gap, a pause — is not a pair); it is low when pacing is even whatever the rate.
|
||||
|
||||
**Which frames count as below X — and why not "longer than 1000 / X".** The present-to-present interval of a game held
|
||||
at X jitters around `1000 / X` by a few tenths of a millisecond, half of it on the long side. Measured on a copy of the
|
||||
owner's ledger (2026-10-06): a GIRLS' FRONTLINE 2 session capped at 60 (median 16.63 ms, 296,380 frames) reads **50.0 %**
|
||||
of its time "below 60" under the plain rule, and a rolling mean does not help — the local average of a game held at 60
|
||||
sits on the threshold. So a frame counts when **it is itself more than 10 % longer** than `1000 / X` (a long frame, never
|
||||
jitter) **or the median of the nine frames around it** (`RollingMedian`, the stutter rule's centered window and edges) **is
|
||||
more than 2 % longer** (a rate that stays below X). The same session reads 9.6 % (its time below 30 alone is 4.7 %); with
|
||||
a 0.4 ms jitter a steady 58 FPS reads 93 %, a steady 60.2 reads 0.7 %, and a 100 ms hitch counts its own 100 ms and no
|
||||
neighbour's. **The cost, stated:** a rate less than 2 % under X (58.8–60 FPS for 60) reads partly as at X — a steady 59
|
||||
reads 40 %. `Domain.Metrics.FramePacing`; `FramePacingTests` pins each of these.
|
||||
|
||||
**Which series.** 30, 60 and frame to frame are over `ft_app` — application frames where generated frames were counted
|
||||
(rule 6: generated frames do not make a game run at 60), the presents otherwise, labelled `(presented)` as every
|
||||
present-only statistic is. **The refresh share is over the presents**, generated ones included: it is the display's rate,
|
||||
and what matters there is what the display received — a ×4 frame-generation session on a 240 Hz display reads near 0 %,
|
||||
and over its application frames it would read 100 % whatever the pacing. It needs `display_monitor_hz` (the display
|
||||
tally's, §Display mode): a session recovered from its crash file has none, and reads N/A. **Sufficiency:** the 1 % low's
|
||||
1,000 frames; below it every value is N/A.
|
||||
|
||||
## Sync — what the presents asked for (beta.14, D49)
|
||||
|
||||
`vsync_present_pct` is the share of the dominant stream's presents with a sync interval of one or more (the game asked
|
||||
to wait for the display), `tearing_allowed_pct` the share with `DXGI_PRESENT_ALLOW_TEARING`. Both arguments were in every
|
||||
Direct3D record since P1 (`FL_MEASURED_PRESENT_ARGS`) and read by nothing; `sessions.sync_interval_mode` (0001) gets its
|
||||
first writer with them — `on` (every present), `off` (none), `mixed`. **Asked, not obtained:** a driver setting or a
|
||||
variable-refresh display can override the request, and nothing in the process says which won. OpenGL's
|
||||
`wglSwapBuffers` and Vulkan's `vkQueuePresentKHR` carry neither argument: N/A, never 0 %. Tier 1 only.
|
||||
|
||||
## Frame Generation — ground truth (Tier 1)
|
||||
|
||||
This is the metric the rewrite exists for. Resolution ladder, highest confidence first; the winning rung is stored in `fg_source`:
|
||||
@@ -428,8 +466,13 @@ F_app = Σ fgEvaluations (APPLICATION frames, counted at the
|
||||
> dividing them by presents dilutes each by the frame-generation factor — at ×4 a title that
|
||||
> path-traces every application frame reports 25%. Whoever writes the RT hooks must choose a
|
||||
> denominator and state it here.
|
||||
>
|
||||
> *(Settled 2026-08-20 with the RT hooks — §RT/PT/RR, "The denominator": `rt_frame_pct` is a share of presents
|
||||
> and says so, and the tri-state is unaffected. Marked here 2026-10-04.)*
|
||||
|
||||
`fgEvaluations` is recorded per present by the NGX/Streamline/FFX/XeSS FG hooks
|
||||
`fgEvaluations` is recorded per present by ~~the NGX/Streamline/FFX/XeSS FG hooks~~ the `slGetNewFrameToken`
|
||||
detour; where Streamline never issued a token, by the FidelityFX dispatches — new PREPARE `frameID`s, else UPSCALE
|
||||
dispatches, the FSR 3.0 host's included *(corrected 2026-10-04: NGX and XeSS have no hook)*
|
||||
(`17_HOOK_ENGINE` §Upscaling / frame generation). `fg_factor = F_disp / F_app`.
|
||||
|
||||
> **`fgEvaluations` counts EVALUATIONS, not generated frames — owner ruling, 2026-08-14 —
|
||||
@@ -512,7 +555,7 @@ carries the three shapes.
|
||||
|
||||
From the upscaler hooks we get, per frame:
|
||||
|
||||
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`) — from the API that was called, not from a DLL sitting on disk.
|
||||
- `upscaler`: the technology **actually executing** (`dlss`, `fsr2`, `fsr3`, `fsr4`, `xess`, `nis`, `none`; **`fsr`** since 2026-09-04 — FSR through the SDK 2.x upscaler DLL, version not named) — from the API that was called, not from a DLL sitting on disk. *(Corrected 2026-10-04: `fsr` was missing here; `fsr4` is reserved and no writer produces it.)*
|
||||
|
||||
> **`dlss_rr` is NOT a value of this field, and this line listed it until 2026-08-06.** Layout
|
||||
> v3 retired it and **reserved** the slot rather than reusing it, because it made Ray
|
||||
@@ -597,6 +640,12 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
|
||||
> bookkeeping is per process, not per settings change. **Nothing native changed and no NGX hook was added**: the
|
||||
> licence bar in `20_OPEN_QUESTIONS` stands.
|
||||
|
||||
**The render scale over time (beta.14, D49).** The session summary draws `100 × √(render pixels / output pixels)` — the
|
||||
per-axis scale, `100 / upscale_ratio` — as steps over the session: from the `render_res` blob where the resolution
|
||||
varied (the finalizer stores it only then), a flat line at the row's extent where it did not, and a sentence where the
|
||||
upscaler's parameters were never measured (`App.Charts.RenderScaleSeries`). The Trend and Compare read the row's
|
||||
`upscale_ratio`, the dominant extent.
|
||||
|
||||
## RT / PT / RR — evidence-based tri-state
|
||||
|
||||
Tri-state `Yes | No | N/A` per session with `source` (`measured | manual | inherited`).
|
||||
@@ -745,15 +794,79 @@ its Sessions column, three Trend metrics — *Exclusive fullscreen share %*, *Bo
|
||||
tier, and a mode switch is not a mid-session change for them (switching resizes the swap chain; the share is what that
|
||||
switch was) — three Compare rows, never ranked, and the CSV's `# display:` line (§Export schema) and the JSON's aggregates.
|
||||
|
||||
## Per-process VRAM (Tier 1)
|
||||
## Game process memory — both tiers (beta.12, owner decision D43)
|
||||
|
||||
`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).
|
||||
**What is measured since 2026-10-03:** the game process's own memory, read from OUTSIDE the game once a second by the
|
||||
Agent through `FrameLedger.ProcessStats.dll` (`18_GPU_VENDOR_APIS` §The game process's memory) — never from the game's
|
||||
memory (CLAUDE.md rule 4):
|
||||
|
||||
| Figure | Source | What it is |
|
||||
|---|---|---|
|
||||
| **Dedicated GPU memory** (`game_vram_dedicated`) | PDH `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated Usage`, every instance naming the pid summed | the number Task Manager's Details tab shows under that name |
|
||||
| Shared GPU memory (`game_vram_shared`) | the same counter set's `Shared Usage` | system memory the GPU uses on the game's behalf |
|
||||
| **Memory — private working set** (`game_ram_private`) | `GetProcessMemoryInfo`, `PROCESS_MEMORY_COUNTERS_EX2.PrivateWorkingSetSize` | Task Manager's "Memory" column; N/A on a Windows that predates EX2 (Windows 10 22H2 / 11 22H2 without the September 2023 update) |
|
||||
| Working set (`game_ram_ws`) | `WorkingSetSize` | the whole working set, shared pages included; what the card falls back to where the private working set is N/A |
|
||||
| Commit (`game_commit`) | `PrivateUsage` | private memory committed, resident or not |
|
||||
|
||||
**Which process.** A hooked session — and any session refused after the loop pinned the process — reads the pinned pid
|
||||
through the handle the session already holds (`SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION`). An unpinned Tier-2 hold
|
||||
(hooking off, blocked, unresolved, cannot pin) reads **every process running the game's executable** in the watcher's
|
||||
snapshot, each opened for the read with `PROCESS_QUERY_LIMITED_INFORMATION` and closed after it, and SUMS them; a process
|
||||
whose creation time is not the snapshot's (a reused pid), or that refuses even that right, is left out of both halves.
|
||||
`game_memory_processes` says how many were summed. Child processes of another executable (a launcher, a crash handler, a
|
||||
web view) are not counted.
|
||||
|
||||
**Dedicated is not the DXGI budget model's "local usage".** dwm.exe read 858 MB dedicated against 310 MB local at an idle
|
||||
desktop, and a test process holding a buffer read 4.5 MiB more dedicated than its own `QueryVideoMemoryInfo(LOCAL)` at
|
||||
both 8 MiB and 512 MiB (`spike-notes` §16, M3) — a constant per-device amount, not one that grows with the game's
|
||||
allocations. So dedicated is defined as Task Manager's column and is **never compared with a budget**: the budget and
|
||||
`budget_exceeded_pct` stay unmeasured (`20_OPEN_QUESTIONS` §M11), and `vram_proc_*` / `vram_budget_exceeded_pct` /
|
||||
`FlFrameRecord.vramUsedMb` stay reserved for that in-process figure.
|
||||
|
||||
**Aggregates** (schema 0018): dedicated avg / median / max, shared max, private working set avg / median / max, working
|
||||
set max, commit max, the process count, the sources (`counters,ex2,ex,held,opened`), and every series' n / mean / median /
|
||||
min / max in `sensor_stats_json` (§Sensor aggregates). MiB stored; shown in GB as Task Manager does (1 GB = 1024 MiB).
|
||||
|
||||
> **The paragraph below is the design that was never built, kept as it stood** (struck 2026-10-03: the Overlay never
|
||||
> called `QueryVideoMemoryInfo` — `dllmain.cpp` lists `FL_MEASURED_VRAM` as unproduced, §H10 never settled where in the
|
||||
> game to call it — and D43 chose the outside read instead).
|
||||
|
||||
~~`vramUsedMb` from `IDXGIAdapter3::QueryVideoMemoryInfo(LOCAL)` inside the game = **this game's** usage and budget. **MiB, truncating, and it must use the same divisor as `vramBudgetMb`** — the two are compared, and mismatched rounding would put a systematic bias into `budget_exceeded_pct`. Residual: a flip within 1 MiB of the budget, 0.004% of a 24 GiB card. Stored as its own series and clearly labelled apart from the adapter-wide figure from `18_GPU_VENDOR_APIS`. Aggregates: avg, max, and `budget_exceeded_pct` (share of samples where `CurrentUsage > Budget`, i.e. the driver was likely evicting — a genuinely useful stutter explanation).~~
|
||||
|
||||
## Sensor aggregates
|
||||
|
||||
Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline aligned to the frame timeline via the shared QPC epoch captured at session start. Fields with no data are `N/A`, never 0.
|
||||
Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since beta.12 the `median` (the linear-interpolation
|
||||
50th percentile: the middle sample of an odd count, the mean of the two middle ones of an even count) and the `min`
|
||||
(`Domain.Metrics.SeriesAggregates`). Every stored series' n / mean / median / min / max is written once at finalize to
|
||||
`sessions.sensor_stats_json`, so the summary's statistics read stored values and outlive a retention sweep of the raw
|
||||
series. Sensor timeline aligned to the frame timeline via the shared QPC epoch captured at session start. Fields with no
|
||||
data are `N/A`, never 0.
|
||||
|
||||
## Accuracy budget (shown in Help → About metrics)
|
||||
**The card's clocks and limits (beta.14, D49), both tiers.** The core and memory clock (MHz), the fan (RPM) and the
|
||||
memory temperature were in the samples before (L2 reads them, L3 too) and stored nowhere; they are series now
|
||||
(`gpu_core_clock`, `gpu_mem_clock`, `gpu_fan`, `gpu_mem_temp`) with `avg_gpu_core_clock_mhz`, `avg_gpu_mem_clock_mhz`,
|
||||
`avg_gpu_fan_rpm` and `max_gpu_mem_temp`. **What held the card back** is NVAPI's perf-decrease reasons
|
||||
(`GpuSample.ThrottleReasons`, L3 only): `gpu_power_limit` / `gpu_thermal_limit` read 100 on a tick whose reasons include
|
||||
the power limit (`0x2`) / thermal slowdown (`0x1`) and 0 on one whose reasons do not, so their mean — `power_limit_pct`,
|
||||
`thermal_limit_pct` — is the share of ticks held back. A card no layer reports reasons for (every card but NVIDIA's) has
|
||||
no answer: N/A, never "not limited". `throttle_pct` (any reason) is unchanged.
|
||||
|
||||
## Efficiency (beta.14, D49)
|
||||
|
||||
`app_frames_per_joule` = the application frame rate ÷ the card's average board power — FPS per watt, frames per joule.
|
||||
**Never the displayed rate** (rule 6): a generated frame costs the card a fraction of a rendered one, and counting it would
|
||||
sell frame generation as efficiency. The application rate is known when frame generation was counted over the session
|
||||
(Native FPS; a counted `none` makes it the presented rate), or when no frame-generation runtime was loaded
|
||||
(`presented_qualifier = no_fg_runtime`). **Null** for `census_not_run`, `fg_runtime_loaded` and `none_withheld`, for a
|
||||
session whose generation changed state (its steady state covers a share of the session, and the power is the whole
|
||||
session's), without a power reading, and at Tier 2 (no frames). The power is the **graphics card's** — not the
|
||||
processor's, not the whole PC's — averaged over the session's sensor ticks. `Domain.Metrics.EnergyEfficiency`,
|
||||
`SessionAggregator.ApplyEfficiency`.
|
||||
|
||||
## Accuracy budget ~~(shown in Help → About metrics)~~
|
||||
|
||||
*(Corrected 2026-10-04: no such page exists. Users read these limits in `LIMITATIONS.md` (Help ▸ Limitations) and in
|
||||
`legal/ACCURACY.md`, which it links.)*
|
||||
|
||||
| Quantity | Tier 1 | Tier 2 |
|
||||
|---|---|---|
|
||||
@@ -762,10 +875,14 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max`. Sensor timeline
|
||||
| Upscaler + render resolution | **exact** (vendor API arguments) | not available |
|
||||
| RT active | measured per frame | not available |
|
||||
| Path tracing | heuristic, confidence-scored, never asserted | not available |
|
||||
| Per-process VRAM | exact | not available |
|
||||
| ~~Per-process VRAM~~ Game process memory (beta.12) | ~~exact~~ dedicated / shared GPU memory as Task Manager counts it — a known 512 MiB allocation read +512.0 MiB (`spike-notes` §16); private working set equal to Windows' own counter; read from outside the game | ~~not available~~ the same, from outside; an unpinned hold sums the executable's processes |
|
||||
| PC latency | as reported by Reflex | not available |
|
||||
| Display mode (beta.10) | per 100 ms sample: exclusive fullscreen as the swap chain answers it (DXGI; OpenGL and Vulkan cannot say), borderless, windowed, minimised; the window's size from user32 | per 1 s sample, from the window alone: windowed, minimised, or *fullscreen or borderless* — never split |
|
||||
| GPU temp / load / power | vendor API accuracy, ±1 s sampling | same |
|
||||
| GPU clocks / fan / memory temperature (beta.14) | vendor API accuracy, ±1 s sampling | same |
|
||||
| GPU power / thermal limit (beta.14) | NVAPI's perf-decrease reasons once a second — a limit that came and went between two ticks is not seen; NVIDIA only, N/A on every other card | same |
|
||||
| Time below 30 / 60 / refresh (beta.14) | from the frame times above, with the margins of §Pacing — a rate less than 2 % under the threshold reads partly as at it | **not available** |
|
||||
| Efficiency (beta.14) | the application rate's accuracy over the board-power sensor's; N/A wherever the application rate is not known | **not available** |
|
||||
| CPU temperature | sensor-inherent ±1–2 °C, needs LHM + PawnIO + elevation. **Read since 2026-09-21** (`Telemetry.LhmCpuTemperatureReader`: the package sensor, else the hottest core) and **unmeasured on real hardware** — no elevated run with PawnIO has been taken (`20_OPEN_QUESTIONS` §CPU) | same |
|
||||
| CPU load | **time busy over elapsed, every logical processor** (`GetSystemTimes`, 1 Hz, unprivileged; since 2026-09-21). Not Task Manager's "utility", which is frequency-scaled and exceeds 100 under turbo — the two are different numbers and this one is stated as what it is. Null on a session's first tick (no interval yet), never 0 | same |
|
||||
| System memory in use | physical memory in use machine-wide, MiB (`GlobalMemoryStatusEx`, 1 Hz, unprivileged; since 2026-09-21). The machine's, not the game's | same |
|
||||
@@ -788,13 +905,13 @@ Per-column sources, and what a *Tier-2* export does instead:
|
||||
| Column | Tier-1 source | Tier 2 |
|
||||
|---|---|---|
|
||||
| `frame_index`, `qpc_ms`, `frametime_ms` | `frametimes` blob + session `qpcEpoch` | ~~from CSV~~ — no Tier-2 CSV exists; a Tier-2 session exports no per-frame rows at all |
|
||||
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | `FrameType` (2.x) |
|
||||
| `native_or_generated` | `frame_flags` generated bit — set where `fgEvaluations == 0`, i.e. the presents that carried **no** application-frame evaluation. Inverted from the pre-2026-08-14 reading, and accurate to one frame per the note in §Frame Generation | ~~`FrameType` (2.x)~~ — no Tier-2 CSV *(corrected 2026-10-04)* |
|
||||
| `render_w/h`, `output_w/h` | `render_res` blob — **two `uint16` pairs per frame**, not one; `ResizeBuffers` is hooked precisely because output resolution changes mid-session | `N/A` |
|
||||
| `upscaler`, `upscaler_quality`, `fg_mode` | segment table, joined by frame index | `N/A` |
|
||||
| `rt_flags` | `rt_flags` blob, **one byte per frame** preserving all three bits (`asBuildObserved`, `dispatchObserved`, `psoCreatedEver`) — collapsing them to a single "rt-active" bit loses the inline-RayQuery distinction this project exists to measure. The third was `rtPsoAlive` until layout v3 renamed it: creation is observed at `CreateStateObject` and destruction is COM `Release`, which is not in the hook inventory and must not be added, so the bit latches and could only ever mean "created ever" | `N/A` |
|
||||
| `dispatch_rays` | `dispatch_rays` blob (`uint32[]`, the volume) | `N/A` |
|
||||
| `pso_created` | `pso_created` blob (`uint16[]`, the **count**, not a flag) | `N/A` |
|
||||
| `vram_mb` | `vram_proc` per-frame blob. Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so | `N/A` |
|
||||
| `vram_mb` | `vram_proc` per-frame blob. ~~Note the value is refreshed at 1 Hz (`17_HOOK_ENGINE` §Memory) so it is a held sample, not a per-frame measurement — the header block says so~~ **Corrected 2026-10-03: the Overlay never produced it, so the column has always been empty.** It stays in the list — the schema is fixed — and the header's note says so; the game's memory is the `# game_memory:` header line (beta.12, §Game process memory) | `N/A` |
|
||||
| `reflex_latency_us` | `latency_us` blob; **finalize must write it** | `N/A` |
|
||||
|
||||
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, swap effect, **the display line** (beta.10: `# display:` with each mode's milliseconds, the changes, the source and the window / back buffer / monitor sizes, or `N/A` for a session recorded before — §Display mode; a mode is the session's, not a frame's, so it is not a column), hardware snapshot, segment list, the tri-state flags with their sources, and the note that `vram_mb` is 1 Hz-sampled. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
|
||||
Plus a `#`-prefixed header block: game, date, **capture tier**, api, present mode, swap effect, **the display line** (beta.10: `# display:` with each mode's milliseconds, the changes, the source and the window / back buffer / monitor sizes, or `N/A` for a session recorded before — §Display mode; a mode is the session's, not a frame's, so it is not a column), hardware snapshot, segment list, the tri-state flags with their sources, ~~and the note that `vram_mb` is 1 Hz-sampled~~ **the game's memory** (beta.12: `# game_memory:` with the dedicated GPU memory's mean / median / max, the shared max, the private working set's mean / median / max, the working set's and the commit's max — MiB, invariant — the process count and the sources, or `N/A` for a session recorded before or one where nothing answered; the session's figure, read once a second, so a header line like the display's), and the note that `vram_mb` is the in-game figure this build does not produce. The tier belongs in the header because a Tier-2 export is missing whole columns and anyone reading it later must know why.
|
||||
+48
-11
@@ -22,6 +22,7 @@ public interface IFrameSource : IAsyncDisposable
|
||||
> {
|
||||
> FlWriterState WriterState { get; } FlShmHandshake Handshake { get; }
|
||||
> long TotalDropped { get; } long TotalGaps { get; }
|
||||
> FlDisplayState? DisplayState { get; } // region 4, beta.10 (added to this sketch 2026-10-04)
|
||||
> DrainResult Drain(Span<FlFrameRecord> into, IList<ulong> gapIndices);
|
||||
> void PublishGuardResult(uint completedEvaluations, bool unhookRequested);
|
||||
> void SetPaused(bool paused); void RequestLogFlush();
|
||||
@@ -86,7 +87,11 @@ it still holds.
|
||||
> watcher's own 1 Hz snapshot** (`ITargetResolver.IsRunning` over `LatestProcessSnapshot`, 2026-09-23; a process
|
||||
> whose path could not be read still counts by its name; the console verbs, where nothing polls, keep the name
|
||||
> list) when it never opened the process — by name, another game's `Game.exe` held an RPG Maker game's session
|
||||
> open. Nothing about the hold touches the target, and no process is opened for it. **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
|
||||
> open. Nothing about the hold touches the target, and no process is opened for it. *(Corrected 2026-10-03, beta.12, D43:
|
||||
the hold now reads the game's own memory, once a second, by opening each process running the executable with
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` for the read and closing it after — the right the watcher's own snapshot already uses
|
||||
on every process each second; nothing is held, nothing is injected, and the memory's contents are never read. Its video
|
||||
memory comes from performance counters that need no handle at all; `03_METRICS` §Game process memory.)* **And hooking-off is decided before the process is opened**: `RunAsync` reads the consent record
|
||||
> first, and a row whose hooking is off — merely added, blocked by a finding, auto-disabled — goes straight to
|
||||
> the hold with `RefusedHookNotEnabled` (its verdict is the row's block when it has one, `PreviouslyBlocked`).
|
||||
> The resolver used to run first, and a hooking-off utility that runs elevated (Borderless Gaming, imported from
|
||||
@@ -127,7 +132,7 @@ which makes the notification more important than it was, not less.
|
||||
## Process watcher
|
||||
|
||||
- 1 Hz snapshot via `CreateToolhelp32Snapshot` (CsWin32): pid, ppid, exe path (`QueryFullProcessImageName`).
|
||||
- Watchlist match on normalized full path (`GetFinalPathNameByHandle` — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
|
||||
- Watchlist match on normalized full path (~~`GetFinalPathNameByHandle`~~ `File.ResolveLinkTarget` *(corrected 2026-10-04 — `ExecutableIdentity` says why)* — junctions/symlinks), ~~filename fallback with a stale-path warning badge~~ **and a file name alone never starts a session (2026-09-23, HANDOFF D25): it can only be the entry's own executable on a drive that changed its letter (the relocator's rule), or it is not in the library.**
|
||||
- Process tree assembled from ppid chains; the **capture target** is the descendant that actually presents. In launch mode we know it; in attach mode we wait for the first ring handshake. ~~or (Tier 2) elect the PID with the most presents in the first 10 s~~ — there is no Tier-2 present stream to elect from. Re-elect if the presenting PID dies while the tree lives (level-transition relaunches).
|
||||
|
||||
> **Built 2026-09-10 (P2 PR-F), in `Application.Watch` with one adapter.** `ToolhelpProcessSnapshotSource`
|
||||
@@ -149,7 +154,13 @@ which makes the notification more important than it was, not less.
|
||||
> row's path with its drive letter changed (an RPG Maker `Game.exe` has the same bytes in every game); and the
|
||||
> running-session table is keyed by the executable's path, so a re-imported or merged entry's new id cannot start a
|
||||
> second session for the same executable. The launch election registers its session there too, and skips a child the
|
||||
> watcher already records. **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
|
||||
> watcher already records. *(beta.15, 2026-10-06:)* a process turned away by that rule — "one at a time" — was never
|
||||
> recorded, because the watcher reports a pid once: **a game started again while its last session was still finalizing**
|
||||
> (the driver profile, a crash reporter waited for, the transaction — seconds) got no session at all. The orchestrator
|
||||
> now remembers the newest such process per executable and starts its session when the running one ends, if that one
|
||||
> ended on its own (not cancelled with the host), the process is the same (pid and start time) and it is then the
|
||||
> executable's ONLY process — a helper of a game still running has the game beside it and stays turned away, as before
|
||||
> (`CaptureOrchestratorTests`: the restart recorded, the helper not, a process that left meanwhile not). **Behaviour change:** a game whose folder moved (not its drive letter) records nothing until
|
||||
> *Change executable* points its entry at the new file. `ProcessTree` reads ppid chains with the one rule that defeats pid
|
||||
> reuse: a child that started before its parent is not its child. `DescendantElection` picks the newest-started
|
||||
> descendant whose image is tracked — a launcher's consent does not extend to what it spawns, so the elected image
|
||||
@@ -175,7 +186,7 @@ which makes the notification more important than it was, not less.
|
||||
|
||||
## Launch mode vs attach mode
|
||||
|
||||
**Launch mode (preferred).** User starts the game from FrameLedger (or FrameLedger is set as the launch wrapper): `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
|
||||
**Launch mode (preferred).** User starts the game from FrameLedger ~~(or FrameLedger is set as the launch wrapper)~~ *(corrected 2026-10-04: no wrapper exists, and no App button sends `LaunchGame` yet — the pipe command has no caller; launch mode runs from the Agent's developer verb `--console launch --exe`. Since beta.21 one does: **Play** set to *Start directly* — D59, `08_UI` §Games)*: `CreateProcess(CREATE_SUSPENDED)` → guard → inject → `ResumeThread`. Catches swapchain creation and upscaler init, which attach mode can miss entirely — a game that creates its DLSS feature during startup will otherwise report `upscaler = unknown` for the whole session.
|
||||
|
||||
> **An elevated Agent starts the game as a standard user (beta.10, the admin mode, D34).** `ProcessLauncher` checks its
|
||||
> own token: elevated, it starts the game with the desktop shell's token (`Infrastructure.Startup.UnelevatedProcess` —
|
||||
@@ -203,6 +214,11 @@ which makes the notification more important than it was, not less.
|
||||
> that spawns the real game and quits lands on the first, and re-electing the descendant is the Agent's
|
||||
> (P2, §Process watcher) — **built 2026-09-10 (PR-F)**: the Agent's `--console launch` hands either
|
||||
> answer to `DescendantElection` and runs an attach-mode session against the newest tracked descendant.
|
||||
> *(Corrected 2026-10-06, beta.15: **it never ran until beta.15.** The refused outcome carried no `TargetPid`, and
|
||||
> `CaptureOrchestrator.ElectAfterLaunchAsync` returned at `TargetPid == 0` — before its own `election:` log line — on every
|
||||
> launch since #150; the orchestrator's tests built the outcome by hand, pid included, so nothing saw it. The refused
|
||||
> outcome carries the launcher's pid and exit code now (`CaptureSessionLaunchTests` pins it), and an outcome without
|
||||
> one is logged rather than silent. A real launcher run is still owed: HANDOFF, owner-only.)*
|
||||
> **The host never terminates what it launched**: any refusal after the start
|
||||
> leaves the title running unhooked, which is Tier 2.
|
||||
>
|
||||
@@ -221,13 +237,13 @@ which makes the notification more important than it was, not less.
|
||||
|
||||
**Attach mode.** Game launched from Steam/GOG/Epic normally; watcher sees it, guard runs, inject. Feature hooks install late, so early-init facts may be missed; the Overlay compensates by re-reading state on the first `EvaluateFeature` call it does observe, and the session is flagged `late_attach = true` so the UI can note that startup-time settings may be incomplete.
|
||||
|
||||
Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).
|
||||
~~Steam users can also set FrameLedger as a launch option wrapper; documented in the UI rather than automated (never modify a user's Steam config for them).~~ *(Corrected 2026-10-04: not built — there is no wrapper entry point and no UI text; a game started from Steam is recorded in attach mode. The parenthesis still holds: never modify a user's Steam config for them.)*
|
||||
|
||||
## The guard
|
||||
|
||||
The guard is **native** (`20_OPEN_QUESTIONS` §S13(a)) and the Agent reaches it through `IAntiCheatGuard`, a **thin P/Invoke facade over the single implementation** — never a second one. Two blocklist matchers that can disagree is a fail-open by construction: the day they diverge, one is wrong and nothing says which. Nothing managed parses rules or matches a blocklist, and a test asserts it (§S15 item 1).
|
||||
|
||||
The facade exposes exactly two operations, and neither hands out a clearance:
|
||||
The facade exposes ~~exactly two operations~~ four *(corrected 2026-10-04: `GuardedInjectWhenReadyAsync`, launch mode's waiting entry, and `PreScanGameAsync`, the advisory checks 3–4 behind FR-2.2 and the library pre-scan, joined the two below; since D33 each takes `toleratedFamily`, a family name the guard resolves itself)*, and none hands out a clearance:
|
||||
|
||||
- `GuardedInjectAsync(pid, payload)` — runs every pre-injection check and, only on a pass, injects. There is no overload that skips the checks and no way to supply evidence; the guard collects its own, so a caller can ask but only the guard answers (§S13(b)).
|
||||
- `EvaluateAsync(pid)` — the same checks with no injection, for the 30 s in-session re-scan. It cannot be used to pre-authorise anything: it takes no payload and returns no token, so acting on a pass means calling `GuardedInjectAsync`, which re-collects.
|
||||
@@ -312,7 +328,7 @@ What the Agent checks **before** asking the guard is the thing the native side s
|
||||
> published at attach are counted separately as `RecordsBeforeAttach`; that is not
|
||||
> a stall and must not raise this warning.
|
||||
- **A torn record is a gap, not a skipped frame.** Silently dropping it merges two frame times into one double-length interval, i.e. fabricates a stutter. Record an explicit gap at that index; `03_METRICS` excludes gap-adjacent intervals from frame-time statistics.
|
||||
- Records go into an in-memory buffer (`ArrayPool<FlFrameRecord>` segments). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
|
||||
- Records go into an in-memory buffer (~~`ArrayPool<FlFrameRecord>` segments~~ a `List<FlFrameRecord>` — corrected 2026-10-04). Every 60 s, a crash-safety flush writes raw buffers to `%LOCALAPPDATA%\FrameLedger\tmp\<sessionGuid>.partial`.
|
||||
|
||||
## Threading model
|
||||
|
||||
@@ -345,7 +361,7 @@ the pipe's tasks touches the ring or the recorder, and the session loop never wa
|
||||
|
||||
## Telemetry poller
|
||||
|
||||
1 Hz 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. 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). Never called from the game process, never faster than 500 ms. Samples carry the session QPC epoch for timeline alignment.
|
||||
|
||||
## Session recorder — state machine
|
||||
|
||||
@@ -432,8 +448,29 @@ because a layer cannot leave a running game's loader chain.
|
||||
## Crash & exit classification
|
||||
|
||||
- Normal: presenting PID exit code 0 — **and since beta.8 any exit code that is not an exception's** (End task and taskkill leave 1; a program's own error exit; Ctrl+C's `0xC000013A`), kept in `capture_notes` and said as what it is.
|
||||
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record naming the exe within `[start, end + 30 s]`.
|
||||
- `unhooked_safety`: the guard fired mid-session.
|
||||
- `crashed`: ~~nonzero exit code~~ **an exception's exit code** (`ExitStatusMapper.IsExceptionCode`: NTSTATUS `0xC0000000–0xC0FFFFFF` but `0xC000013A`, `0xE06D7363` C++, `0xE0434352` .NET, `0x80000003` breakpoint), **or** an Application Error (1000) / WER (1001) event log record ~~naming the exe~~ **that is a crash report of this game** within `[start, end + 30 s]`, **or** (beta.14) an engine's crash reporter the game started before it left.
|
||||
|
||||
> **Corrected 2026-10-05 (beta.14, the crash-reporter question): the event-log witness was too broad, and one engine's
|
||||
> crashes had no witness at all.** A record counted when any of its strings *contained* the executable's name: on the
|
||||
> owner's machine a WER 1001 `RADAR_PRE_LEAK_64` — Windows' memory-leak detector — named `witcher3.exe` and a session
|
||||
> that ended with exit code 0 was stored `crashed` (2026-10-04, read from a copy of the ledger and the event log); a hang
|
||||
> report, another program whose name contains this one's, or a crash of a same-image child would have done the same.
|
||||
> `CrashEventMatcher` now takes a 1000 from `Application Error` only when its application name equals the executable's,
|
||||
> its path (when given) is the executable's and its process id is the session's, and a 1001 from `Windows Error
|
||||
> Reporting` only when it is a crash report (`APPCRASH`, `BEX`, `BEX64`, `CLR20r3`, `MoAppCrash`, `MoBEX`) whose first
|
||||
> parameter is the executable's name. And Unreal handles its own crash — it starts `CrashReportClient.exe` and exits
|
||||
> with code 3, no exception code and no event — so it read `normal`. The watcher's once-a-second snapshots now record
|
||||
> every **on-crash** reporter a process starts (`Watch.CrashReporterCatalog`: Unreal's `CrashReportClient.exe`,
|
||||
> REDengine's `CrashReporter.exe`, RE Engine's `CrashReport.exe`, BugSplat's `BsSndRpt(64).exe`) with its parent by pid,
|
||||
> image and start (`CrashReporterWitness` — a pid reused by a later process is not the parent); the recorder asks at the
|
||||
> end, after two more polls when the game just left. It counts (`CrashReporterRule`) when it started at least 10 s after
|
||||
> the game and the game left within 60 s of it: `crashed`, with `crash_reporter=<image>` in the notes. A reporter whose
|
||||
> game kept running is a note (`crash_reporter_seen=`). **Always-on handlers never count** — Unity's
|
||||
> `UnityCrashHandler64.exe` and `crashpad_handler.exe` start with their game. No process is opened for any of this.
|
||||
> Sessions stored before beta.14 keep their status.
|
||||
- `unhooked_safety`: the guard fired mid-session. *(Since beta.14, D48: a re-scan that refused only because it could not
|
||||
read the game's tree, concluded after the game itself had exited, is the game's exit instead — `normal` or `crashed` by
|
||||
its exit code — with `scan_at_exit=<reason>` in `capture_notes`; `19_SAFETY` §During a session.)*
|
||||
- `degraded`: Overlay self-disabled after faults, or ring layout mismatch mid-session.
|
||||
- `interrupted`: Agent died mid-session; recovered from `.partial` on next start.
|
||||
- A **user stop** (FR-3.6; `StopSession` over the pipe, P3 PR-1b) is `normal`: the loop ends as `SessionEndReason.StoppedByUser` at its next tick, drains once more and finalizes; the target keeps running, unhooked from here. It is the session's own stop token, not the host's cancellation — the latter leaves a `.partial`.
|
||||
@@ -468,7 +505,7 @@ Crash-within-60s-of-injection happening twice for the same game ⇒ **hooking au
|
||||
|
||||
## Live progress
|
||||
|
||||
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, per-process VRAM, elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
|
||||
`SessionProgress` at 1 Hz to the UI (`07_IPC`): rolling 5 s Native FPS, Displayed FPS, FG factor, current render→output resolution, upscaler + quality, RT active flag, GPU/CPU temp, ~~per-process VRAM~~ the game process's dedicated GPU memory and private working set (beta.12, from the newest telemetry tick — `SessionHeld` carries the same two for a held session), elapsed. Suppressed when no UI client is connected. This is what makes the Dashboard live card genuinely useful — it is showing *measured* settings, not guesses.
|
||||
|
||||
> **Built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D13): `Application.Ipc.SessionProgressCalculator`**, over the last 5 s of the
|
||||
> ring's records through the same calculators the row uses — `FrameTimeSeries` for the presented rate, `FgWindow` + the FG ladder for
|
||||
|
||||
+111
-13
@@ -36,6 +36,10 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
> **2026-09-27 (beta.10):** the first row's *swap effect* has a writer since schema 0016 — region 4's `GetDesc`, stored
|
||||
> in `sessions.swap_effect` as a name (`flip_discard`, …) — and the display-mode row is new. **Present mode has none**,
|
||||
> and the block above did not list it: `sessions.present_mode` is null on every row, and the pages say N/A.
|
||||
>
|
||||
> **2026-10-04 (beta.12, D43):** the per-process VRAM row's *usage* is measured — not by `QueryVideoMemoryInfo` but
|
||||
> from outside the game, in both tiers, with the game's RAM beside it (`game_vram_*`, `game_ram_*`; `03_METRICS`
|
||||
> §Game process memory). The in-game figure, its budget and `vram_proc_*` stay unbuilt.
|
||||
|
||||
> **"present-count delta" is removed from the FG row, and it was not merely unreliable —
|
||||
> it was structurally zero.** `03_METRICS` §Frame Generation retired that rung on
|
||||
@@ -47,11 +51,11 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
> stale-by-not-being-touched failure this project keeps recording; `06_DATA_MODEL`'s
|
||||
> `fg_source` enum carried the same value and is corrected in the same pass.
|
||||
|
||||
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **The one exception since beta.10 is how its window was shown** (the display-mode row), which the Agent reads from outside the game in either tier.
|
||||
~~Tier-2 sessions have `upscaler = unknown`, resolutions `N/A`, RT `N/A`, and an FG mode only if cadence resolves it.~~ **Simpler since 2026-08-28: a Tier-2 session detects NOTHING.** It has no frames, so cadence has nothing to run over. `upscaler`, resolutions, RT and FG all read `N/A`, and the static-hint tier (below) is the only thing that says anything about such a title — which it labels *inference*, never measurement. **The ~~one exception~~ exceptions** *(corrected 2026-10-04)* are how its window was shown (the display-mode row, beta.10) and the game process's memory (beta.12), which the Agent reads from outside the game in either tier.
|
||||
|
||||
## Static hints — rules engine
|
||||
|
||||
Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check). Schema:
|
||||
Rules are **data, not code**: `rules/detection-rules.json`, bundled ~~and updatable from the repo (raw GitHub URL, ETag-cached; manual "Update detection rules" in Tools + weekly auto-check)~~ *(corrected 2026-10-04: nothing fetches. The rules ship with the build and `RulesSeeder` installs them in `%LOCALAPPDATA%\FrameLedger\rules\`; Tools ▸ Update detection rules re-seeds from the copy beside the binary and wakes the detection and anti-cheat sweeps. A rules change reaches users with a release — `20_OPEN_QUESTIONS` §S20 feed half)*. Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -64,7 +68,7 @@ Rules are **data, not code**: `rules/detection-rules.json`, bundled and updatabl
|
||||
}
|
||||
```
|
||||
|
||||
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. **Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.
|
||||
The `anticheat` block is the same file that feeds the hard guard in `19_SAFETY` — shipping it as updatable data is what lets a newly-protected game be blocked without waiting for an app release. ~~**Rules updates that touch the `anticheat` block are treated as security updates:** applied on next check regardless of the user's auto-update preference for other rules.~~ *(Corrected 2026-10-04: there is no feed and no auto-update preference, so today a newly-protected game waits for a release; the sentence is what a feed must do once built, §S20.)*
|
||||
|
||||
Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`, `sibling_glob`, **`path_contains`**, `pe_company_contains`, `pe_product_contains`, `strings_contains` (bounded 8 MB scan), `manifest_field`. Combine with `all` / `any` — **not nested**, which schemaVersion 2 forbids. Version extractors: `pe_file_version` (of the sibling its `from` names, not of the executable), `pe_product_version_regex`, **`strings_regex`**, `manifest_field`, and since 2026-09-27 **`unreal_build`** (no parameter; decided in code, §Engine version). A regex extractor must capture exactly **one** group — the evaluator returns the first — and `rules-validate.ps1` refuses any other count and any pattern that does not compile (both promised by the rules file's `$comment` and enforced by nothing until beta.10).
|
||||
|
||||
@@ -88,7 +92,10 @@ Signal types evaluated by `RuleEvaluator` (Domain): `file_exists`, `dir_exists`,
|
||||
|
||||
### Trust and staleness of the rules feed
|
||||
|
||||
`20_OPEN_QUESTIONS` §S4. The file is fetched over HTTPS from a raw GitHub URL.
|
||||
> **Specified, not built (corrected 2026-10-04):** there is no feed (§S20 feed half, §S4); these rules apply once one
|
||||
> exists. Today the seeder validates the packaged copy with the guard's parser and keeps `detection-rules.json.bak`.
|
||||
|
||||
`20_OPEN_QUESTIONS` §S4. The file ~~is~~ would be fetched over HTTPS from a raw GitHub URL.
|
||||
Three rules, because a gate whose data can silently go stale is a gate with an
|
||||
expiry date nobody sees:
|
||||
|
||||
@@ -136,15 +143,15 @@ Recorded as a residual risk, not as a solved problem.
|
||||
|
||||
| Engine | Signals | Version |
|
||||
|---|---|---|
|
||||
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | FileVersion of `UnityPlayer.dll` |
|
||||
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | `unity_build` (since 2026-10-12, §Engine version — Unity, Godot, RPG Maker): the player library's ProductVersion, the data file's header, the library's numeric version. ~~FileVersion of `UnityPlayer.dll`~~ — the string as it is, `2022.3.39.5118735`, the build number where the release letter belongs |
|
||||
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | `unreal_build` (since 2026-09-27, §Engine version): the shipping executable's numeric file version and the engine's branch name inside it. ~~ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)`~~ — two capture groups, of which the evaluator returns the first, so every Unreal version it ever stored was a bare `4` or `5` |
|
||||
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
|
||||
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | `godot_build` (since 2026-10-12): a data pack's header, beside the executable or appended to it. ~~strings regex `Godot Engine v(\d+\.\d+[\.\d]*)`~~ — the string sits 57–78 MB into a real export, past the 8 MiB scan, so it never read one |
|
||||
| GameMaker | `data.win` | `N/A` |
|
||||
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `N/A` — the `.js` header needs a `from` that `strings_regex` lacks |
|
||||
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `N/A` — one rule, the variant unnamed |
|
||||
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the core script's header, which also names the maker (MZ or MV). ~~`N/A` — the `.js` header needs a `from` that `strings_regex` lacks~~ |
|
||||
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the RGSS library `Game.ini` names — its generation names the maker (XP, VX, VX Ace), its version is the library's. ~~`N/A` — one rule, the variant unnamed~~ |
|
||||
| RE Engine (Capcom) | `re_chunk_000.pak` sibling, the exact name (since 2026-09-23) | `N/A` |
|
||||
| FromSoftware | a `*.bhd` **and** a `*.bdt` sibling (since 2026-09-23) | `N/A` |
|
||||
| Ren'Py | `renpy/` dir **or** `*.rpa` | `renpy/__init__` strings / `log.txt` first line |
|
||||
| Ren'Py | `renpy/` dir **or** `*.rpa` | ~~`renpy/__init__` strings / `log.txt` first line~~ `N/A` *(corrected 2026-10-04: no extractor — `strings_regex` reads only the executable)* |
|
||||
| CryEngine | `CrySystem.dll` | FileVersion |
|
||||
| Source | `gameinfo.txt` + `bin/engine.dll` | `N/A` |
|
||||
| Unknown | fallback | — |
|
||||
@@ -239,13 +246,75 @@ numbered release lines to report. A version the user typed is never overwritten
|
||||
`2026.09.6` change the key, so every library entry is read again once; schema 0015 removes the bare `4`/`5` the old rule
|
||||
wrote, where detection wrote it.
|
||||
|
||||
### Engine version — Unity, Godot, RPG Maker (beta.19, 2026-10-12, rules 2026.10.2)
|
||||
|
||||
The owner asked for the version of RPG Maker, Unity and Godot games ("if possible"). What the rules gave: Unity's
|
||||
`pe_file_version` stored `UnityPlayer.dll`'s FileVersion string as it is (`2022.3.39.5118735`, the build number where the
|
||||
release letter belongs); Godot's `strings_regex` scanned the executable's first 8 MiB, and in both Godot exports on the
|
||||
owner's disk the `Godot Engine v…` string sits 57–78 MB in, so it never read one; both RPG Maker rules had `version: null`.
|
||||
**Measured before anything was written, read-only, on 23 installs** (`spike-notes` §17), and decided in code as Unreal's
|
||||
is — three extractor types that take no parameter (`unity_build`, `godot_build`, `rpgmaker_build`; the schema's enum),
|
||||
one second read by `StaticGameDetector` for the engine that matched, a decider in `Domain.Detection` and the witness in
|
||||
`games.engine_version_source`:
|
||||
|
||||
| Engine | Witness, strongest first | Source id | On the owner's disk |
|
||||
|---|---|---|---|
|
||||
| Unity | `UnityPlayer.dll`'s ProductVersion is an editor version (`2022.3.39f1 (4e1b…)` → `2022.3.39f1`) | `unity_player` | 13 of 15 |
|
||||
| | the header of `<Game>_Data\globalgamemanagers` (first 256 bytes) names one | `unity_data` | A Space for the Unbound, 2019.4.1f1 |
|
||||
| | the library's numeric file version, MAJOR.MINOR.PATCH and no release letter — Unity's own binary, so the engine's, only shorter | `unity_player_file` | GIRLS' FRONTLINE 2 (data file encrypted), 2019.4.40 |
|
||||
| Godot | the 20-byte header of the data pack beside the executable (`<exe>.pck`, else the only `.pck` there): `GDPC`, format, MAJOR, MINOR, PATCH | `godot_pck` | both: 4.2.2, 4.4.1 |
|
||||
| | the same header of a pack appended to the executable, found through its 12-byte trailer (size + `GDPC`) | `godot_pck_embedded` | none (synthetic files only) |
|
||||
| | the executable's ProductVersion while its ProductName is still `Godot Engine` (a project that set its own carries the game's: 衔蝶 `0.1.0.3`) | `godot_exe` | — |
|
||||
| RPG Maker MV/MZ | line 2 of the core script: `js/rmmz_core.js` → MZ, `www/js/rpg_core.js` or `js/rpg_core.js` → MV (first 4 KiB) | `rpgmaker_mz_core`, `rpgmaker_mv_core` | MZ 1.10.0; MV 1.6.2, 1.6.2, 1.6.1 |
|
||||
| RPG Maker XP/VX/VX Ace | the RGSS library `Game.ini`'s `Library=` names: RGSS1 → XP, RGSS2 → VX, RGSS3 → VX Ace; its numeric version when it is its generation's, else the one its name carries (`RGSS301` → 3.0.1) | `rgss1_library`, `rgss2_library`, `rgss3_library` | VX Ace 3.0.1, twice |
|
||||
|
||||
A Godot version leaves out a zero patch, as Godot names its releases (4.3, 4.2.2). The App names the maker from the
|
||||
witness — the two RPG Maker rules each cover several makers — and says that an RGSS number is the runtime library's, not
|
||||
the editor's: *RPG Maker MZ 1.10.0*, *RPG Maker VX Ace (RGSS 3.0.1)* (`Formats.Engine(id, source)`,
|
||||
`Formats.EngineWithVersion`); the game page's *Engine version* row says what each version was read from, and *Not found in
|
||||
the game's files* once the sweep has read a row of these engines and found none.
|
||||
|
||||
**Where it is read.** Beside the row's executable first: `UnityPlayer.dll` (else the shallowest one the walk listed) and
|
||||
`<exe>_Data` (else a `*_Data` beside that player); `<exe>.pck`. RPG Maker's files are looked for beside the executable and
|
||||
up to two folders above it, as `RpgMakerTitle` already looked for a title — a launcher-fronted game keeps its runtime in
|
||||
a subfolder (A Doll's Locket's `css\`, HELLO, HELLO WORLD!'s `swiftshader\` — *both "launchers" are malware, D57,
|
||||
`spike-notes.md` §20*); a `Library=` that points outside the ini's
|
||||
folder is named and not read. Version resources and at most a few kilobytes of any file; the whole detection of one entry
|
||||
measured 24 ms to 4.1 s on the owner's USB drive, nearly all of it the install's walk, once per executable and rules
|
||||
version. The Privacy Policy says so since 2.8 (§4).
|
||||
|
||||
**What it is not.** RPG Maker 2000/2003 is not detected at all (no install to measure, no rule). XP and VX libraries are
|
||||
read by the VX Ace rule's reader unmeasured. A Unity build older than 2019 keeps its player in the executable (no
|
||||
`UnityPlayer.dll`): its data file's header is the only witness. Rules `2026.10.2` change the detection key, so every
|
||||
library entry is read again once; a Unity row keeps the old raw string only if none of its witnesses can be read now.
|
||||
|
||||
### Engine version — Ren'Py (beta.20, 2026-10-12, rules 2026.10.3)
|
||||
|
||||
The owner asked for the version of Ren'Py games once beta.19's were on screen. The `renpy` rule had no version extractor
|
||||
(`version: null`). Ren'Py ships its engine as Python beside the game's launcher, and `renpy/vc_version.py` names its
|
||||
release — `version = '8.5.0.25111603'`, beside `branch`, `nightly`, `official` and `version_name`. Measured 2026-10-12 on
|
||||
the owner's one Ren'Py install, Bound Between Desks (Steam): 109 bytes, and the game's own `log.txt` printed
|
||||
`Ren'Py 8.5.0.25111603` at its last start; the launcher carries no version resource (`spike-notes` §18).
|
||||
|
||||
**What is read and how it is decided.** `renpy_build` (`RenPyBuildReader`): the first 4 KiB of `renpy/vc_version.py`
|
||||
beside the row's executable, its `version` line only (`version_name` is not it). `RenPyVersion.Decide` keeps
|
||||
MAJOR.MINOR.PATCH — Ren'Py names its releases by those three; the fourth is the build — and records `renpy_vc_version`.
|
||||
The page says *Ren'Py 8.5.0* and that it was read from the engine's version file; a Ren'Py row whose file names no
|
||||
version says *Not found in the game's files*. Through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`)
|
||||
Bound Between Desks read `8.5.0` in 79 ms, and the Unity, Godot and RPG Maker installs read as before. The Privacy
|
||||
Policy names the file since 2.9 (§4). Rules `2026.10.3` change the detection key, so every library entry is read again
|
||||
once.
|
||||
|
||||
**What it is not.** Nothing else is guessed from: a Ren'Py game whose `vc_version.py` names no version, or that ships its
|
||||
engine compiled only, reads as not found. One Ren'Py install was measured.
|
||||
|
||||
### Platform signatures & metadata
|
||||
|
||||
| Platform | Signals | Metadata |
|
||||
|---|---|---|
|
||||
| Steam | `steam_api64.dll`/`steam_api.dll` sibling, or path contains `steamapps\common` | nearest `steamapps/appmanifest_<id>.acf` (walk up): `appid`, `name`, `buildid` → version |
|
||||
| GOG | `goggame-<id>.info` sibling, or `Galaxy64.dll` | `.info` JSON: `gameId`, `name`, `version` |
|
||||
| Epic | `EOSSDK-Win64-Shipping.dll`, or path under an Epic install | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
|
||||
| Epic | `EOSSDK-Win64-Shipping.dll`~~, or path under an Epic install~~ *(corrected 2026-10-04: the rule has no path signal)* | `%ProgramData%\Epic\EpicGamesLauncher\Data\Manifests\*.item` matched by `InstallLocation` |
|
||||
| itch.io | `.itch\receipt.json.gz` | **`%APPDATA%\itch\db\butler.db`** (`install_locations` + `caves`, butler's `verdict` names the executable) since 2026-09-16, then the receipt JSON: title, id |
|
||||
| None/Manual | fallback | PE VersionInfo |
|
||||
|
||||
@@ -286,6 +355,35 @@ wrote, where detection wrote it.
|
||||
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
|
||||
> step 4 now points at File ▸ Import library… rather than saying "later build".
|
||||
|
||||
> **beta.19 (owner report 2026-10-12): a store's own pick can be a helper, and a launcher is not the game.** The owner's
|
||||
> A Doll's Locket - Remake (itch 5085165, RPG Maker MZ) was imported as `Dolls Locket\notification_helper.exe` — NW.js's
|
||||
> toast helper. The pick was **butler's verdict**, taken as is: butler stores a *filtered* verdict (the shallowest
|
||||
> candidates, minus those whose manifest asks for elevation) and does not rank what is left, and on that install the
|
||||
> 213 MB `DollsLocket.exe` launcher asks for administrator while the NW.js runtime sits a level deeper in `css\`, so the
|
||||
> helper was the whole verdict (read from the owner's `butler.db`, read-only). *(Corrected 2026-10-13, owner decision
|
||||
> D57: that "launcher" — the same 213 MB program HELLO, HELLO WORLD!, City of Bones and Träumerei put in front of their
|
||||
> runtime — is malware: it ships a registry file that switches off Windows' script scanning and adds Microsoft Defender
|
||||
> exclusions (`spike-notes.md` §20). Do not run it. The admin-mode sentence below is withdrawn; the three changes stand
|
||||
> as rules about helpers and NW.js layouts, and the import still takes a store's own pick when it is not a helper.)*
|
||||
> Three changes:
|
||||
> **(1)** a verdict candidate whose whole name is a runtime helper (`ExecutableLocator.RuntimeHelperNames`:
|
||||
> `notification_helper`, `crashpad_handler`, `UnityCrashHandler64/32`, `CrashReportClient`, NW.js's `nwjc` and
|
||||
> `chromedriver`) or that sits in a Unity plugin folder is skipped, and with nothing left the locator guesses and the
|
||||
> review marks the row *guessed* — whole names, because the locator's fragments are inside real games' names (`node` in
|
||||
> *Nodebuster*) and a store's pick is overruled only when it cannot be the game; the locator's `HelperFragments` gain the
|
||||
> same three NW.js names. **(2)** The locator ranks **an executable beside `nw.dll` + `package.json`** — the `rpgmaker_mv`
|
||||
> rule's own signal — as an NW.js runtime (owner decision D56), below the Unity and Unreal layouts (an NW.js folder can
|
||||
> be a tool shipped beside such a game) and above a name match (the launcher in front of the runtime is named after the
|
||||
> install): the install's guess is `css\Game.exe`, the process that draws, as D28 pointed HELLO, HELLO WORLD!'s entry at
|
||||
> its runtime by hand. ~~That runtime starts elevated (its launcher asks for administrator), so it is measured with the
|
||||
> admin mode on (D34).~~ *(Withdrawn 2026-10-13, D57: it starts elevated because the malware in front of it asks for
|
||||
> administrator.)* **(3)** Discovery matches a store title to an entry by **platform + store id** as well as by
|
||||
> path: the entry an earlier import made at another executable is "already in the library" (the log names its path),
|
||||
> so a corrected guess never adds the same game a second time — that entry is re-pointed with Change executable…, and
|
||||
> nothing rewrites it by itself (D25/D27). Tests: `ExecutableLocatorTests.AnNwjsRuntimeBeatsTheLauncherNamedAfterTheInstallAndItsHelpersAreDropped`,
|
||||
> `StoreLibrarySourcesTests.ItchSkipsAVerdictCandidateThatIsARuntimeHelper` (the verdict as stored),
|
||||
> `LibraryImporterTests.AStoreTitleAlreadyInTheLibraryAtAnotherExecutableIsNotOfferedAgain`.
|
||||
|
||||
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
|
||||
|
||||
## Capability hints (explicitly labelled as such)
|
||||
@@ -343,13 +441,13 @@ it does not claim who loaded it.
|
||||
|
||||
Before a game is ever launched with hooking enabled, the static scan checks for anti-cheat SDKs shipped alongside it (`EasyAntiCheat/` directory, BattlEye binaries, EOS anti-cheat components, etc.). A hit **disables the hooking toggle for that game entirely** in the UI, with an explanation — the user cannot enable it, so the guard never even has to fire at launch. Prevention beats interception.
|
||||
|
||||
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1).
|
||||
**Implemented in the native guard, not here** (`fl_prescan.cpp`, exposed as ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` since 2026-09-25, which takes the executable, resolves the install root itself and runs check 3 as well). It uses the same `MatchName` and the same rules file as the injection guard, matching directory names against the `anticheat.directories` group and file names against `anticheat.files`. Nothing managed matches a blocklist (§S15 item 1). **It walks two folders since 2026-10-13:** the install root and, when the executable lives below it, the executable's own folder — each three levels deep. The root alone missed Wuthering Waves' `Client\Binaries\Win64\AntiCheatExpert\`, which sits beside the executable and four levels under the root (`19_SAFETY` §Pre-injection checks, item 4; `spike-notes.md` §19).
|
||||
|
||||
Three things this section previously implied that are not true, and are worth stating:
|
||||
|
||||
- **The UI answer is advisory.** It decides whether the toggle is *offered*; it does not gate injection. The same scan runs a second time inside the guard's chokepoint against a directory derived from the target's own pid, so "prevention beats interception" is a convenience, not the enforcement.
|
||||
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past a bound, or behind a reparse point — is *neither* a hit nor a pass. It must surface as "could not verify", distinct from "anti-cheat found": disabling the toggle on it would be a false refusal with no appeal, and clearing it would be a fail-open.
|
||||
- **The token list is thin.** `directories` and `files` carry three tokens today. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
|
||||
- **A hit disables the toggle; "could not scan" must not.** The scan is tri-state. `Reason::kPreScanFailed` — directory absent, unlistable, past the entry bound, or behind a reparse point — is *neither* a hit nor a pass. *("Past a bound" until 2026-10-13: the depth bound is a reach, not a refusal — a folder at the last level is named and never opened, and the walk still reads as complete.)* It must surface as "could not verify", distinct from "anti-cheat found": disabling the toggle on it would be a false refusal with no appeal, and clearing it would be a fail-open.
|
||||
- **The token list is thin.** `directories` and `files` ~~carry three tokens today~~ *(corrected 2026-10-04: rules 2026.10.1 carry 9 directory families (12 names) and 18 file families (55 names), and since 2026-09-25 any `*.sys` in the install tree is a finding by code, not data)*. Widening needs verified names; a guessed token fails closed by never firing, which is a silent hole (`19_SAFETY` §Blocklist seed).
|
||||
|
||||
## Caching & privacy constraints
|
||||
|
||||
|
||||
+104
-28
@@ -2,7 +2,7 @@
|
||||
|
||||
`%LOCALAPPDATA%\FrameLedger\ledger.db`. Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`. `Microsoft.Data.Sqlite` + Dapper; all writes in explicit transactions.
|
||||
|
||||
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; never a `hook_*` column), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
|
||||
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It was the one Agent write that deletes a `games` row until beta.19; it never touches a consent column. **And since beta.19 (2026-10-12, D55) the Agent removes an entry whose game is no longer installed** (`IGamePrune`, `SqliteGamePrune`, asked by the detection sweep through `UninstalledEntryPrune`): one `DELETE` that holds every stored condition in the same statement — the same row at the same path, `removed_at` NULL, no session stored (`NOT EXISTS` on `sessions` — nothing cascades), no `hook_blocked_reason`, `hook_prescan_state` not `blocked`, no `ac_exception_at` and no `ac_exception_trial_failed_at` — behind `retention.remove_uninstalled_games`; a block, a grant and D38's mark are never removed with their entry (`19_SAFETY` §What a finding does to the game, *What clears it*). **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ DeLine truncated
|
||||
|
||||
## Schema (v2 — hook architecture)
|
||||
|
||||
@@ -47,8 +47,11 @@ CREATE TABLE games (
|
||||
store_id TEXT,
|
||||
engine TEXT, engine_version TEXT,
|
||||
-- (schema 0015, ALTERed last) engine_version_source TEXT: where engine_version came from — a
|
||||
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version, or the rule's
|
||||
-- extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
|
||||
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version; since beta.19
|
||||
-- unity_player | unity_data | unity_player_file | godot_pck | godot_pck_embedded | godot_exe | rpgmaker_mz_core |
|
||||
-- rpgmaker_mv_core | rgss1_library | rgss2_library | rgss3_library — the RPG Maker ids also name the maker; since
|
||||
-- beta.20 renpy_vc_version; or the
|
||||
-- rule's extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
|
||||
publisher TEXT, game_version TEXT,
|
||||
cover_path TEXT, notes TEXT,
|
||||
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
|
||||
@@ -123,15 +126,18 @@ CREATE TABLE games (
|
||||
> human's typed value as auto-detected is a lie they cannot see through; failing to
|
||||
> badge a detected value merely costs a badge on something they can still edit. The
|
||||
> rule it exists to support — *detection never overwrites a `user` field* — is in
|
||||
> `05_DETECTION` §Caching and is enforced by `StaticDetectionResult.ShouldWrite`,
|
||||
> which is tested even though nothing persists yet.
|
||||
> `05_DETECTION` §Caching and is enforced by ~~`StaticDetectionResult.ShouldWrite`,
|
||||
> which is tested even though nothing persists yet~~ `SqliteGameRepository.FieldProvenance.Resolve`
|
||||
> *(corrected 2026-10-04: applied per field since P4 PR-1, and it also fills an empty field that has no entry;
|
||||
> `ShouldWrite` keeps its tests but has no production caller)*.
|
||||
>
|
||||
> ~~No migration is written here. There is no SQLite layer at all, and §Migrations
|
||||
> forbids editing an applied script — so guessing the shape into `0001_init.sql`
|
||||
> before its consumers exist maximises the chance of baking in a wrong guess that
|
||||
> can only be appended to.~~ **Written 2026-09-09 (P2 PR-B), with its first consumer:** the
|
||||
> column exists in `0001_init.sql`; the writer (the detection cache, P4) and the reader (the
|
||||
> library card, P3) are still unbuilt, so it is decided, created, and empty.
|
||||
> column exists in `0001_init.sql`; ~~the writer (the detection cache, P4) and the reader (the
|
||||
> library card, P3) are still unbuilt, so it is decided, created, and empty~~ *(corrected 2026-10-04: written since
|
||||
> 2026-09-14 by the detection sweep, the store import and Edit…; read for the Edit dialog's badges and the game page)*.
|
||||
|
||||
> **The three hook-state columns have a consumer before they have a table, and two
|
||||
> fields it needs are not here.** Added 2026-08-06 with `IGameConsentStore`, whose
|
||||
@@ -142,7 +148,8 @@ CREATE TABLE games (
|
||||
> anything else — so a record could carry a consent time that nothing had ever
|
||||
> disclosed anything for. `ConsentProvenance`'s zero value means *no disclosure was
|
||||
> shown*, and it deliberately has **no FR-2.1 member**: that dialog needs reviewed
|
||||
> `Safety_*` wording in en/vi/ja and no `.resx` exists anywhere in this tree.
|
||||
> `Safety_*` wording in en/vi/ja and ~~no `.resx` exists anywhere in this tree~~ *(superseded: the dialog shipped in
|
||||
> P3 PR-4 as `ConsentDialog`, below — corrected 2026-10-04)*.
|
||||
> - **A disclosure/wording version.** `legal_acceptance` carries `(doc, version,
|
||||
> accepted_at)` while this column carries a timestamp alone, so nothing could mark
|
||||
> existing per-game consent stale when the reviewed wording changes. It is carried
|
||||
@@ -164,7 +171,10 @@ CREATE TABLE games (
|
||||
> shipped producer, still not FR-2.1, stamped by the Agent's clock; the store writes the NAME the
|
||||
> acknowledgement carries and refuses `NotRecorded`.
|
||||
>
|
||||
> **Still unanswered, and it is an owner decision rather than a coding one:** who
|
||||
> ~~**Still unanswered, and it is an owner decision rather than a coding one:**~~ **Answered by the owner on
|
||||
> 2026-09-22: nothing clears it** *(corrected 2026-10-04)*. A clean re-scan, *Change executable*, a re-import and a twin
|
||||
> merge all leave it, and the toggle stays disabled (`19_SAFETY` §What a finding does to the game); D33's exception
|
||||
> sits on top of the block and never clears it. The question as it stood: who
|
||||
> clears `hook_blocked_reason` when a re-scan comes back clean. `19_SAFETY` §A game
|
||||
> already enabled can become blocked later makes a non-null value mean "toggle
|
||||
> disabled" and makes re-enabling "a user action" — but if nothing clears the column
|
||||
@@ -190,7 +200,9 @@ CREATE TABLE sessions (
|
||||
started_at INTEGER NOT NULL, ended_at INTEGER NOT NULL, duration_s REAL NOT NULL,
|
||||
|
||||
capture_tier INTEGER NOT NULL, -- 1 = hooked, 2 = not hooked; CHECK (capture_tier IN (1,2))
|
||||
capture_notes TEXT, -- why tier degraded, late_attach, etc.
|
||||
capture_notes TEXT, -- why tier degraded, late_attach, etc.; beta.14 adds crash_reporter= /
|
||||
-- crash_reporter_seen= (an engine's crash reporter the game started) and
|
||||
-- scan_at_exit= (D48: a re-scan that could not read as the game exited)
|
||||
late_attach INTEGER NOT NULL DEFAULT 0,
|
||||
telemetry_source TEXT, -- composite descriptor, e.g. 'l1+lhm+nvapi' (18_GPU_VENDOR_APIS)
|
||||
overlay_build_id TEXT, -- native DLL build that produced this data
|
||||
@@ -214,10 +226,11 @@ CREATE TABLE sessions (
|
||||
-- presentation
|
||||
api TEXT, present_mode TEXT, swap_effect TEXT,
|
||||
hdr_flag TEXT NOT NULL DEFAULT 'na', hdr_source TEXT, -- tri-state, like rt/rr beside it
|
||||
sync_interval_mode TEXT, -- observed vsync behavior
|
||||
sync_interval_mode TEXT, -- observed vsync behavior: on|off|mixed — first written in beta.14 (0019's
|
||||
-- §Sync), NULL where no present carried its arguments (OpenGL, Vulkan, Tier 2)
|
||||
|
||||
-- upscaling / FG (measured at tier 1)
|
||||
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown
|
||||
upscaler TEXT, -- none|dlss|fsr2|fsr3|fsr4|xess|nis|unknown, and fsr since 2026-09-04 (FL_UPSCALER_FSR_UNVERSIONED; added 2026-10-04)
|
||||
upscaler_quality TEXT,
|
||||
upscaler_sharpness INTEGER, -- percent; NULL when the API reports none
|
||||
render_w INTEGER, render_h INTEGER, -- dominant segment
|
||||
@@ -278,6 +291,26 @@ CREATE TABLE sessions (
|
||||
avg_gpu_load REAL, avg_cpu_load REAL, avg_ram_mb REAL,
|
||||
avg_gpu_power_w REAL, throttle_pct REAL,
|
||||
|
||||
-- schema 0018 (2026-10-03, beta.12, D43): the game process's own memory, read from outside it, both tiers
|
||||
-- (03_METRICS §Game process memory), MiB; and every sensor series' n/mean/median/min/max as JSON
|
||||
game_vram_dedicated_avg_mb REAL, game_vram_dedicated_median_mb REAL, game_vram_dedicated_max_mb REAL,
|
||||
game_vram_shared_max_mb REAL,
|
||||
game_ram_private_avg_mb REAL, game_ram_private_median_mb REAL, game_ram_private_max_mb REAL,
|
||||
game_ram_ws_max_mb REAL, game_commit_max_mb REAL,
|
||||
game_memory_processes INTEGER, -- processes summed: 1 pinned, every process of the executable for a held one
|
||||
game_memory_source TEXT, -- counters,ex2,ex,held,opened — the reads that answered
|
||||
sensor_stats_json TEXT, -- {"gpu_temp":{"N":…,"Mean":…,"Median":…,"Min":…,"Max":…}, …}
|
||||
|
||||
-- schema 0019 (2026-10-06, beta.14, D49): pacing (hooked), the present arguments (Direct3D), the card's clocks and limits
|
||||
-- (both tiers) and efficiency (hooked) — 03_METRICS §Pacing, §Sync, §Sensor aggregates, §Efficiency
|
||||
time_below_30_pct REAL, time_below_60_pct REAL,
|
||||
time_below_refresh_pct REAL, -- over presents, at display_monitor_hz; NULL without a rate
|
||||
frametime_delta_mean_ms REAL, -- mean |ft[k] - ft[k-1]| over neighbouring intervals
|
||||
vsync_present_pct REAL, tearing_allowed_pct REAL, -- shares of the presents that carried their arguments
|
||||
avg_gpu_core_clock_mhz REAL, avg_gpu_mem_clock_mhz REAL, avg_gpu_fan_rpm REAL, max_gpu_mem_temp REAL,
|
||||
power_limit_pct REAL, thermal_limit_pct REAL, -- shares of the ticks that carried reasons: NVIDIA (L3) only
|
||||
app_frames_per_joule REAL, -- application FPS / average GPU board power; never displayed frames (rule 6)
|
||||
|
||||
-- schema 0016 (2026-09-27, beta.10): the display mode, both tiers (03_METRICS §Display mode). Milliseconds per mode,
|
||||
-- each sample standing for the time until the next (100 ms hooked, 1 s at Tier 2), a pause not counted; nowindow is
|
||||
-- outside every share. NULL before, on a session recovered from its .partial file, and where the loop never sampled —
|
||||
@@ -329,7 +362,7 @@ CREATE TABLE frame_blobs (
|
||||
-- stored only when either varies
|
||||
dispatch_rays BLOB, -- uint32[] : ray volume per frame, tier 1 only
|
||||
pso_created BLOB, -- uint16[] : compile COUNT per frame, not a flag
|
||||
vram_proc BLOB, -- uint32[] MB per frame; held 1 Hz sample, see 03_METRICS
|
||||
vram_proc BLOB, -- uint32[] MB per frame; never written (corrected 2026-10-04: the Overlay never produced vramUsedMb)
|
||||
latency_us BLOB, -- uint32[], tier 1 + Reflex only
|
||||
first_present_ms REAL -- schema 0013 (beta.8): the dominant stream's first present, ms from qpc_epoch —
|
||||
-- the sensors' zero (t_ms) against the frames'. NULL before; the charts then
|
||||
@@ -343,6 +376,12 @@ CREATE TABLE sensor_blobs (
|
||||
-- schema 0008 (2026-09-22) DROPPED them with the feature (19_SAFETY §What a finding does to the game). Sessions that
|
||||
-- ran under it keep "guard-bypass=" in capture_notes.
|
||||
series TEXT NOT NULL, -- cpu_temp|gpu_temp|gpu_hotspot|gpu_load|gpu_power|vram_proc|vram_adapter|cpu_load|ram_mb
|
||||
-- (vram_proc was listed here from 0001 and never written); since schema 0018 (beta.12,
|
||||
-- D43) also game_vram_dedicated|game_vram_shared|game_ram_private|game_ram_ws|game_commit,
|
||||
-- MiB — the game process's own memory (Application.Recording.SensorSeriesCatalog); since
|
||||
-- beta.14 (D49) also gpu_core_clock|gpu_mem_clock (MHz), gpu_fan (RPM), gpu_mem_temp (°C)
|
||||
-- and gpu_power_limit|gpu_thermal_limit (100 or 0 per tick, NVIDIA only) — a series name
|
||||
-- needs no migration
|
||||
-- cpu_load / ram_mb / cpu_temp and sessions.avg_cpu_load, avg_cpu_temp, max_cpu_temp,
|
||||
-- avg_ram_mb were in schema 0001 with NO producer until 2026-09-21 (Telemetry.SystemTelemetrySource
|
||||
-- on the poller's tick). Rows before that date hold NULL, which is what they measured; no migration.
|
||||
@@ -372,6 +411,10 @@ CREATE TABLE legal_acceptance (doc TEXT PRIMARY KEY, version TEXT NOT NULL, acce
|
||||
> App at build (`GPL-3.0-only` for the licence text) — the App is the only writer, one row per document per
|
||||
> Accept, re-recorded when the embedded version differs from the row's. `20_OPEN_QUESTIONS` §G "Legal doc
|
||||
> versioning" closes on that.
|
||||
>
|
||||
> **Three rows since beta.12 (D45).** The GPL is shown for information and needs no acceptance (GPLv3 §9), so Accept
|
||||
> writes `eula`, `disclaimer` and `privacy` only, and the gate is not held open for `gpl`. A `gpl` row an earlier
|
||||
> version wrote stays, unread (`LegalGate`).
|
||||
|
||||
## Settings registry
|
||||
|
||||
@@ -391,14 +434,18 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
|
||||
| `ui.minimize_to_tray` | bool | `0` | | UI (PR-8) |
|
||||
| `ui.hide_anticheat_hooking` | bool | `1` | | UI (beta.8, 2026-09-25): the game page of an entry the guard found anti-cheat in shows the finding in place of its Hooking card (`08_UI` §Game detail) |
|
||||
| `ui.fps_decimals` | bool | `0` | | UI (beta.8, 2026-09-25): every FPS figure with two decimals ("62.40") instead of a whole number |
|
||||
| `capture.background` | bool | `1` | | Agent |
|
||||
| `ui.hide_scrollbars` | bool | `0` | | UI (beta.14, 2026-10-05): no scroll bar drawn anywhere; every scroller still scrolls with the wheel, the keyboard and touch (`App.Services.ScrollBarHiding`, `08_UI` §Settings) |
|
||||
| `ui.library_view` | choice `grid`\|`list` | `grid` | | UI (beta.11, 2026-10-03): the Games library as a grid of cards that fills the width, or as a list; written by the page's own switch, no Settings row (`08_UI` §Games) |
|
||||
| `ui.play_mode` | choice `store`\|`direct` | `store` | | UI (beta.21, owner decision D59): what Play does — `store` hands the game to the app of the store whose own records name its folder, and the agent starts it where none does; `direct` has the agent start it (`LaunchGame`, launch mode). Settings ▸ Games (`08_UI` §Games) |
|
||||
| `capture.background` | bool | `1` | | ~~Agent~~ nobody *(corrected 2026-10-04: no Agent code ever read it, so the watcher recorded every tracked game whatever it said; beta.12 removed its switch from Settings and reserved the key — `SettingsRegistry.CaptureBackground`. Since beta.21 the App can start a game (Play), and the key stays reserved: a game Play starts is recorded as any other start)* |
|
||||
| `hooking.kill_switch` | bool | `0` | | Agent (FR-2.4, since P2 PR-F) |
|
||||
| `hooking.usermode_ac_exceptions` | bool | `0` | | Agent, at every session start and command (FR-2.8, D33, 2026-09-26): off suspends every user-mode exception without deleting any; on, the user still grants each eligible game |
|
||||
| `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) |
|
||||
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
|
||||
| `update.channel` | choice | `stable` | `stable` · `beta` | UI (P4 PR-5 reads it: `beta` = GitHub pre-releases too) |
|
||||
| `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) |
|
||||
| `update.channel` | choice | ~~`stable`~~ `auto` (beta.14, D47) | `auto` · `stable` · `beta` | UI (P4 PR-5 reads it: `beta` = GitHub pre-releases too; `auto` follows the running copy, a pre-release asking for pre-releases — `11_UPDATER` §The update audit) |
|
||||
| `update.auto_check` | bool | `1` | | UI (P4 PR-5: the startup silent check, `11_UPDATER` §Flow "if enabled") |
|
||||
| `privacy.online_metadata` | bool | `0` | | *reserved* — no consumer and, since 2026-09-16, no toggle on Settings either: the store request it would enable has no code (CLAUDE.md rule 8), and PRIVACY_POLICY 2.2 removed the row that described it |
|
||||
| `log.debug` | bool | `0` | | UI |
|
||||
@@ -412,7 +459,7 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
|
||||
## Blob encoding
|
||||
|
||||
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip test
|
||||
`float32`/`uint16`/`uint32` little-endian arrays through `DeflateStream` (Optimal). One hour at 100 fps ≈ 360k frames ≈ 1.4 MB raw frametimes ≈ **≤ 0.7 MB stored**; flags compress far better; render-res only stored when it varies. Decode helpers in `Infrastructure.Blobs` with round-trip tests (NaN forbidden — assert).
|
||||
|
||||
> **Two rules the finalizer applies (2026-09-10, P2 PR-D).** `frametimes[i]` is the interval from the previous
|
||||
> record ON THE SAME SWAPCHAIN; the first record of a stream, and any record after a torn slot or an
|
||||
@@ -422,7 +469,7 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
> and the sensors from `qpc_epoch`, and nothing said how far apart the two zeros were. Gaps stay closed up on the frame
|
||||
> axis (a gap's interval is stored as 0), so a series still drifts ahead of its sensors past each gap.
|
||||
> Sensor series are aligned to `t_ms` (milliseconds from `qpc_epoch`) and a tick with no reading is stored as
|
||||
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.s (NaN forbidden — assert).
|
||||
> **−1** — never 0, which would be a reading — because temperatures, loads, power and memory are never negative.
|
||||
|
||||
## The `.partial` file
|
||||
|
||||
@@ -440,10 +487,11 @@ Because Tier-1 and Tier-2 sessions carry different fields, every query that comp
|
||||
> | 1 `Header` | UTF-8 JSON: format version, `session_guid`, `started_at`, `qpc_epoch`/`qpc_frequency`, `game_id`, `snapshot_id`, exe path, pid, tier, mode, Overlay build id, telemetry descriptor, launch wait | on create — the breadcrumb `19_SAFETY` §Crash safety asks for before injection |
|
||||
> | 2 `Records` | `i64` first ordinal, then N raw `FlFrameRecord` (64 B each); a chunk that does not continue the sequence is refused | each flush |
|
||||
> | 3 `Gaps` | N × `i32` gap-before record indices | each flush |
|
||||
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | each flush |
|
||||
> | 4 `Sensors` | N × one telemetry sample: QPC, wall clock, layer, presence mask, then only the fields that carry a value — null stays null | ~~each flush~~ read only since beta.12, so a beta.11 file still recovers *(corrected 2026-10-04)* |
|
||||
> | 5 `Tick` | drain/foreground ticks, dropped, gaps, guard ticks, wall clock, the raw `FlWriterState`; the last one wins | each flush |
|
||||
> | 6 `Note` | wall clock + UTF-8 text: a state transition | each transition |
|
||||
> | 7 `Touches` | N × `i64` QPC at which the host touched the target | each flush |
|
||||
> | 8 `SensorsWide` | the same samples under a 32-bit presence mask that carries the game process's memory (D43) | each flush, since beta.12 *(row added 2026-10-04)* |
|
||||
>
|
||||
> Recovery (`PartialRecovery`): a file whose guid is already a row is deleted (the finalize had landed);
|
||||
> one under the minimum session length is discarded; one with no readable header is dropped; the rest
|
||||
@@ -487,11 +535,6 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
|
||||
> `schema_migrations` row per script, so `LatestVersion` is 2.
|
||||
|
||||
> **`0002_annotation_overrides_and_removal.sql` (P3 PR-3, 2026-09-13) — the first append**, and the first
|
||||
> time the runner ran two scripts on a real file: `ALTER TABLE ADD COLUMN` only — the three override
|
||||
> columns on `session_annotations` and `games.removed_at`. `LedgerDatabaseTests` asserts one
|
||||
> `schema_migrations` row per script, so `LatestVersion` is 2.
|
||||
|
||||
> **`0003_fg_refusal.sql` (2026-09-14) — `sessions.fg_refusal`.** The owner's ledger held two hooked rows with
|
||||
> `fg_mode = 'dlssg'`, `fg_source = 'api'` and `fg_factor` NULL — the identity stood, the count refused — and
|
||||
> nothing recorded which refusal; every FG surface said N/A beside a detection that had succeeded. One
|
||||
@@ -525,6 +568,11 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> absence). "Never edit an applied script; only append" holds: 0007 stays as applied and 0008 is the append. The
|
||||
> data dropped is the override acknowledgements themselves, which is the decision. `LatestVersion` is 8.
|
||||
|
||||
> **`0009_record_sessions.sql` (2026-09-23, D29) — `games.record_sessions`** *(entry added 2026-10-04; it was
|
||||
> missing)*. FR-1.6's recording switch, `NOT NULL DEFAULT 1`; the App writes it, the Agent only reads it. Its one data
|
||||
> change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools` as of the
|
||||
> script). `LatestVersion` is 9; `LedgerDatabaseTests.ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly`.
|
||||
|
||||
> **`0010_prescan_key.sql` (2026-09-25) — `games.hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` /
|
||||
> `hook_prescan_exe_mtime_ms`.** The Agent pre-scans every library entry for anti-cheat since beta.8, and again
|
||||
> whenever the rules or the executable change, so it needs what each row was last scanned against — its own key, as
|
||||
@@ -550,6 +598,11 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> `FgPreset`, `FgMode` beside its masks (additive JSON fields; older rows lack them). `LatestVersion` is 12;
|
||||
> `LedgerDatabaseTests.ScriptTwelveAddsTheDriverProfileColumn`.
|
||||
|
||||
> **`0013_first_present.sql` (beta.8, 2026-09-25) — `frame_blobs.first_present_ms`** *(entry added 2026-10-04; it was
|
||||
> missing)*. The charted stream's first present, in milliseconds from `qpc_epoch`, written by the finalizer
|
||||
> (§Blob encoding); NULL before, and such a row's sensor overlay stays off rather than drawn out of step. `LatestVersion`
|
||||
> is 13; `LedgerDatabaseTests.ScriptThirteenAddsTheFirstPresentColumn`.
|
||||
|
||||
> **`0014_usermode_ac_exception.sql` (beta.9, 2026-09-26, owner decision D33) — the user-mode anti-cheat exception.**
|
||||
> Fourteen `games.ac_exception_*` columns in three groups — the Agent's eligibility answer about a blocked row and its
|
||||
> key, the user's grant, and how the last grant ended — and `sessions.ac_exception_family`, the family a HOOKED session
|
||||
@@ -591,6 +644,27 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> `SqliteGameConsentStoreTests.AnEndDuringTheTrialMarksTheGameAndNothingClearsIt`,
|
||||
> `SqliteGameMergeTests.AFailedExceptionTrialOnEitherTwinMarksTheSurvivor`.
|
||||
|
||||
> **`0018_game_memory.sql` (beta.12, 2026-10-03, owner decision D43) — the game process's own memory.** Twelve
|
||||
> columns, ADD COLUMN only: `game_vram_dedicated_{avg,median,max}_mb`, `game_vram_shared_max_mb`,
|
||||
> `game_ram_private_{avg,median,max}_mb`, `game_ram_ws_max_mb`, `game_commit_max_mb`, `game_memory_processes`,
|
||||
> `game_memory_source` and `sensor_stats_json`. Written by the recorder's aggregation for both tiers
|
||||
> (`SessionAggregator.WithSensorAggregates`); a session before it reads N/A. **Not `vram_proc_*`**: those name the
|
||||
> in-process DXGI figure compared with a budget (a different quantity, `03_METRICS` §Game process memory) and stay
|
||||
> reserved. The `.partial` gains chunk type 8 (`SensorsWide`, a 32-bit mask with the game fields); type 4 is still read,
|
||||
> so a beta.11 crash file recovers. `LatestVersion` is 18; `LedgerDatabaseTests.ScriptEighteenAddsTheGameMemoryColumnsAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`,
|
||||
> `PartialSessionFileTests.TheGameMemoryRoundTripsAndANarrowSensorsChunkFromBeta11StillReads`.
|
||||
|
||||
> **`0019_pacing_sync_gpu_limits.sql` (beta.14, 2026-10-06, owner decision D49) — pacing, sync, the card, efficiency.**
|
||||
> Thirteen REAL columns, ADD COLUMN only: `time_below_{30,60,refresh}_pct`, `frametime_delta_mean_ms`,
|
||||
> `vsync_present_pct`, `tearing_allowed_pct`, `avg_gpu_{core,mem}_clock_mhz`, `avg_gpu_fan_rpm`, `max_gpu_mem_temp`,
|
||||
> `power_limit_pct`, `thermal_limit_pct`, `app_frames_per_joule`. Written by the recorder's aggregation
|
||||
> (`SessionAggregator.ApplyPacing` / `ApplySync` / `ApplyEfficiency` for a hooked session, `WithSensorAggregates` for the
|
||||
> card on both tiers); `sync_interval_mode` (0001) gets its first writer beside them. A session before it reads N/A — no
|
||||
> value is computed after the fact. The `.partial` needs no change: the six new sensor series are fields every sample
|
||||
> already carried. `LatestVersion` is 19; `LedgerDatabaseTests.ScriptNineteenAddsThePacingAndCardColumnsAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`. **A beta.13 cannot open a ledger beta.14 migrated.**
|
||||
|
||||
> **Every open used to migrate, and one that should not have did — 2026-09-16.** The Agent's `--console sessions`,
|
||||
> a verb that prints, was run against the owner's ledger while the file on disk was at schema 2 and applied 0003 and
|
||||
> 0004 to it. `LedgerDatabase.OpenReadOnlyAsync` exists since that day: an existing file, `PRAGMA query_only`, no
|
||||
@@ -630,14 +704,16 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> insert leaves no session row behind (`SqliteSessionRepositoryTests`).
|
||||
|
||||
**`0001_init.sql` creates the schema above directly.** There is no v1 → v2
|
||||
upgrade path, because there is no released v1: nothing has shipped, so no
|
||||
FrameLedger database exists anywhere in the world. Writing and testing a
|
||||
upgrade path, because there is no released v1: ~~nothing has shipped, so no
|
||||
FrameLedger database exists anywhere in the world~~ *(corrected 2026-10-04: eleven pre-releases shipped from
|
||||
0.1.0-beta.1 on 2026-09-16, and the appended scripts carry their ledgers forward; no schema older than 0001 ever
|
||||
shipped, so there is still no v1 → v2 path)*. Writing and testing a
|
||||
migration from a schema that never existed is work with no user on the other end
|
||||
of it. The `schema_migrations` machinery still ships from day one — it is what
|
||||
makes the *next* migration safe, and `11_UPDATER` §Versioning already requires
|
||||
migrations to cover every released `MAJOR-1`. That obligation begins at the first
|
||||
release, not before it.
|
||||
migrations to cover every released `MAJOR-1`. ~~That obligation begins at the first
|
||||
release, not before it.~~ It began with 0.1.0-beta.1.
|
||||
|
||||
## Hardware change markers (FR-6.3)
|
||||
|
||||
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from the vendor API (`18_GPU_VENDOR_APIS`) rather than WMI, which makes it accurate enough to be worth charting.
|
||||
Snapshot captured per session, hashed, deduped. Trend queries join consecutive sessions' snapshots; differing fields emit a marker `{after_session_id, field, old, new}`. GPU driver version now comes from ~~the vendor API (`18_GPU_VENDOR_APIS`)~~ DXGI's four-part user-mode driver version (`HardwareSnapshotSource`; corrected 2026-10-04) rather than WMI, which makes it accurate enough to be worth charting.
|
||||
+16
-10
@@ -1,12 +1,14 @@
|
||||
# 07 — IPC
|
||||
|
||||
Three channels, each chosen for its constraints:
|
||||
~~Three~~ Four channels, each chosen for its constraints *(corrected 2026-10-04: §D, the tolerance mapping, arrived
|
||||
in beta.9 without a row here)*:
|
||||
|
||||
| Channel | Between | Transport | Why |
|
||||
|---|---|---|---|
|
||||
| **A. Frame ring** | Overlay DLL → Agent | Shared memory, lock-free SPSC | Hot path: no syscall allowed |
|
||||
| **B. Control block** | Agent ↔ Overlay DLL | Same shared memory, atomics | Tiny, infrequent, must work even if the game is unresponsive |
|
||||
| **C. Command pipe** | UI ↔ Agent | Named pipe, JSON | Rich, versioned, human-debuggable |
|
||||
| **D. Tolerance mapping** | Agent → Overlay DLL, once, before injection | Its own shared memory, read-only to the Overlay | Must exist before the Overlay's loader detour does (§D, D33) |
|
||||
|
||||
## A + B — shared memory (`Local\FrameLedger.Ring.<pid>`)
|
||||
|
||||
@@ -380,30 +382,34 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
|
||||
makes an additive field safe.)*
|
||||
- A request the Agent cannot answer gets `Error { code, message }` with the request's `id`: `UnknownType`,
|
||||
`Malformed` (no `id` when the envelope itself could not be read), `ProtocolMismatch`, `HandlerFaulted`. The
|
||||
connection survives all four.
|
||||
connection survives all four. *(Added 2026-10-04: `SetHookEnabled` and `SetAntiCheatException` also answer
|
||||
`Error UnknownGame` — no row has that id — and `Error ExecutableUnreadable` — nothing scanned, stamped or granted;
|
||||
the App branches on the second.)*
|
||||
|
||||
### Messages
|
||||
|
||||
| Type | Dir | Payload / notes |
|
||||
|---|---|---|
|
||||
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, elevationOutcome /* beta.10, D34: the admin mode's answer at this start — granted, declined, other-account, failed — or null when nobody asked */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. `vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered) and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
|
||||
| `Hello` | UI→A | `{ appVersion, protocol: 2 }` → `HelloAck { agentVersion, protocol, pid, elevated, overlayBuildId, vulkanLayerRegistered, telemetrySource /* composite, e.g. l1+lhm+nvapi */, cpuTempAvailable, disclosureVersion /* P3 PR-4, D14: the FR-2.1 text this Agent stamps against */, exceptionDisclosureVersion /* D33, 2026-09-26: the user-mode exception's disclosure this Agent grants against */, elevationOutcome /* beta.10, D34: the admin mode's answer at this start — granted, declined, other-account, failed — or null when nobody asked */, ~~etwAvailable~~ }` — `etwAvailable` struck 2026-09-13 with the tier it described (2026-08-28); `pid` added. ~~`vulkanLayerRegistered` is **false by construction** today (the layer is per-launch, never registered)~~ `vulkanLayerRegistered` is the HKCU implicit-layer registration as the Agent found it at start *(corrected 2026-10-04: since P3 PR-8b; true while `VkLayerReconciler` keeps the layer registered for a hook-enabled Vulkan game, P4 PR-2)* and `cpuTempAvailable` false unelevated; `telemetrySource` is the composite stood up once on the first `Hello` |
|
||||
| `GetStatus` | UI→A | → `StatusAck { state, activeSession?, tier? }` — and `activeSessions[]`, one `{ sessionGuid, gameId, gameName?, pid, tier, startedAt, hold? }` per running session. **`hold` added 2026-09-23, optional:** present on a session held unhooked (Tier 2), with the same words `SessionStarted.hold` carries; a session listed at tier 2 WITHOUT a `hold` has not attached yet — it is starting, not held. The App reads this list on every (re)connect (§Client behavior) |
|
||||
| `SetWatchlist` | UI→A | `{ entries: [{ gameId?, exePath }] }` — ~~full replace~~ **ensure, never remove** (built 2026-09-13, PR-1b): each entry's path is normalised by the Agent, its row ensured with hooking OFF when new, and the ack is `WatchlistAck { games: [{ gameId, exePath, name }], unreadable: [exePath] }`; `gameId` in a request is a hint and never trusted over the path. UI re-sends on connect. **Carries no hooking state** (see §The pipe is not a trust boundary). *Since the App writes `games` rows itself under `06_DATA_MODEL` §Writer ownership (HANDOFF §P3 D15), this is the pipe's way of adding a row, not the only one; the watcher reads the table at 1 Hz either way.* |
|
||||
| `LaunchGame` | UI→A | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
|
||||
| `LaunchGame` | UI→A *(the App sends it since beta.21: Play in its Start directly mode, and in the store mode where no store installed the game — `App.Services.GamePlayer`, D59)* | `{ gameId, arguments? }` → ~~suspended-launch~~ launch mode as built ("inject late", `04_CAPTURE` §Launch mode) → `LaunchAck { gameId, accepted, outcome, sessionGuid? }` — `outcome` is `Accepted` · `UnknownGame` · `SessionRunning` (one per game at a time) · `Unavailable` · `RecordingOff` (2026-09-23: the entry's recording switch is off, FR-1.6 — FrameLedger does not start what it will not record). *(Built 2026-09-13, PR-1b: `CaptureOrchestrator.LaunchAsync` over an `ILaunchRecorderFactory` the Agent composes with the Vulkan layer's environment — or none when FR-2.4's switch is on — and the launcher election runs after, as the console's `launch` does; the elected session is not addressable by the launch's guid.)* |
|
||||
| `SetHookEnabled` | UI→A | `{ gameId, enabled, disclosureVersion? }` — Agent re-runs the static AC pre-scan and may reply `Refused`. **The Agent stamps the consent timestamp itself.** *(Built 2026-09-13, PR-1b, as far as it can be: `enabled: false` → `RevokeAsync` → `HookEnabledAck { gameId, enabled: false, outcome }`; `enabled: true` → the pre-scan of the executable's directory, a refusal or a "could not verify" recorded through `RecordGuardBlockAsync` and answered `Refused { gameId, reason, family?, signal? }`; a clean scan → ~~**`Error DisclosureUnavailable`, nothing stamped** — the reviewed FR-2.1 text does not exist, and a client's `disclosureVersion` is a claim, not a disclosure shown. PR-4 replaces that last branch with the stamp~~ **since PR-4 (2026-09-13): the client's `disclosureVersion` compared with the Agent's own `SafetyDisclosure.Version`; equal → the stamp from the Agent's clock with `ConsentProvenance.ConsentDialog`, answered `HookEnabledAck { enabled, outcome, prescan: "clean" }`; anything else → `Error DisclosureVersionMismatch`, nothing written (D14). `DisclosureUnavailable` remains for a composition that wired no version, which `--serve` never is.)* **Since beta.8 (2026-09-25):** the pre-scan is of the executable (the guard resolves the install root, PR-2 of that train), and BEFORE it an executable known not to run as x64 is answered `Refused { gameId, reason: "ExecutableNotX64", signal: "x86" | "anycpu32" | "arm64" | "arm" }` with nothing scanned and nothing written — not a guard reason and not a block (`05_DETECTION` §What the files say about themselves). **Since D33 (2026-09-26):** for a blocked game whose user-mode exception is in force for the executable on disk (the option on, a grant made on these bytes, the block naming that family) the pre-scan NAMES the family, and a pass under it is stamped as ever and answered `prescan: "exception"`; a finding about the game under it also ends the exception. |
|
||||
| `SetAntiCheatException` | UI→A | **Added 2026-09-26 (D33).** `{ gameId, enabled, disclosureVersion? }` — grant or withdraw a game's user-mode anti-cheat exception (`19_SAFETY` §The user-mode exception). `enabled: false` → the exception ends (`Withdrawn`), hooking goes off while the block stands → `AntiCheatExceptionAck { gameId, granted: false, outcome, family? }`. `enabled: true` → `Error DisclosureVersionMismatch` unless `disclosureVersion` is the Agent's `AntiCheatExceptionDisclosure.Version`; `Error ExceptionsOff` while `hooking.usermode_ac_exceptions` is off; `Refused { reason: "BlockNotExceptionable" }` for a title list or an unreadable block; then the Agent's OWN facts — ~~the successful Tier-1 sessions (`Refused { reason: "TooFewSessions", signal: <count> }` under two)~~ *(D38, 2026-10-03: no session is needed)*; a game an exception of which ended during its trial is refused before anything is scanned (`Refused { reason: "TrialFailed", family, signal: <unix ms> }`); a tolerant pre-scan of the executable on disk naming the block's family (`Refused { reason, family, signal }` unless the guard let exactly that family through) — and the store writes the grant only over facts that make the game eligible, and never over a failed trial → `AntiCheatExceptionAck { granted, outcome, family }`. **A grant turns nothing on**: hooking is FR-2.1's `SetHookEnabled`, afterwards. Not answered (`UnknownType`) by an Agent composed without the exception. |
|
||||
| `PauseCapture` / `ResumeCapture` | UI→A | global → `PauseAck { paused }`; `StatusAck.paused` reports it. *(Built 2026-09-13, PR-1b: one in-memory flag, `CapturePause`, read by every session loop at its tick and told to the ring once per transition; supervision — the guard scan, the kill switch, the safety stop — never pauses. Not persisted: an Agent that restarts resumes.)* |
|
||||
| `StopSession` | UI→A | `{ sessionGuid }` — graceful ~~unhook~~ stop + finalize → `StopAck { sessionGuid, accepted, reason? }`. *(Built 2026-09-13, PR-1b: the orchestrator names every session it starts and cancels THAT session's stop token; the loop reads it at its next tick, drains once more, and ends as `SessionEndReason.StoppedByUser` — `exit_status = normal`, the row stored like any other, the target left running. A guid nobody runs is `accepted: false`. Distinct from the host's cancellation, which leaves a `.partial`.)* |
|
||||
| `UpdateRules` | UI→A | **no payload** — a trigger, not a source. The Agent re-reads only its own `%LOCALAPPDATA%\FrameLedger\rules\` copy → `UpdateRulesAck { outcome }`. *(Built 2026-09-13, PR-1b: the seeder's `EnsureSeededAsync` outcome; a payload naming a path is ignored, and a test sends one to prove it.)* |
|
||||
| `Shutdown` | UI→A | graceful stop → `ShutdownAck`, then the host stops (sessions finalize inside its grace window). *(Built 2026-09-13, PR-1b: `IAgentLifetime`, the host's under `--serve`, a logged no-op under `--console`.)* |
|
||||
| `DeleteSessions` | UI→A | **Added 2026-10-03 (beta.11, D40).** `{ gameId? }` — every session of that game, or of every game when it is null, with their segments, frame and sensor series and annotations (they cascade) → `DeleteSessionsAck { gameId?, games, sessions }`. `Error SessionRunning` and nothing deleted while a session of that game — of any game, for all — is being recorded (`CaptureOrchestrator.IsRecording` / `IsRecordingAny`). The client names no rows beyond the game: they are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the App says as "restart the agent". Carries no safety fact. |
|
||||
| `SweepRetention` | UI→A | **no payload** — a trigger, like `UpdateRules`: the Agent applies `06_DATA_MODEL` §Retention to every game with the `retention.raw_sessions_per_game` it reads itself → `SweepRetentionAck { keep, games, sessions }` (`keep` 0 = unlimited, and then nothing was swept). *(Built 2026-09-15, P4 PR-7, for Tools ▸ Database maintenance: `Application.Recording.RetentionSweep` over `ISessionRepository.SweepRetentionAllAsync`, composed into `AgentCommandHandler` under `--serve`. The client names no number because the rows are the Agent's (§Writer ownership). Additive: an older Agent answers `Error UnknownType`, which the dialog reads as "restart the Agent". Carries no safety fact.)* |
|
||||
| `SessionStarted` | A→UI | `{ sessionGuid, gameId, gameName, pid, tier, startedAt, hold? }` — **published once per session**: at the attach (tier 1, `startedAt` the attach), or — **since 2026-09-23** — at the first tick of a session held unhooked (tier 2, `startedAt` the session's start, `pid` 0 when the loop never opened the process, as a hooking-off hold never does). ~~a session that never attaches has no `SessionStarted`, only its `SessionCompleted` (tier 2)~~ — that was the beta.5 wire, and every hooking-off, refused or unreadable game read "Nothing is being captured." for as long as it ran. **`hold` (optional, tier 2 only)** is why nothing is measured: `{ reason, guardReason?, family?, signal?, hookingTurnedOff }` — the loop's `SessionEndReason` and, when the guard said anything but allow, its reason, family and signal: the same words the row's `capture_notes` will carry, so the live card and the summary read one sentence (`Formats.Tier2HoldReason` / `Tier2Reason`). The refusal's own event (`CaptureRefused` and the rest, below) goes out with this start rather than when the game exits, and is not repeated at the end |
|
||||
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct? }` — how long it has run and the machine's sensors. **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
|
||||
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus? }` — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
|
||||
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct?, gameVramDedicatedMb?, gameRamPrivateMb? }` — how long it has run and the machine's sensors (and since beta.12 the game process's own memory, read from outside it — optional, an older client ignores them). **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
|
||||
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus?, gameVramDedicatedMb?, gameRamPrivateMb? }` (the last two added 2026-10-03, beta.12, optional: the game process's dedicated GPU memory and private working set, MiB, from the newest telemetry tick; `vramProcMb` stays reserved for the in-process figure and has no producer) — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
|
||||
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff }` — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch` and `PreScanCouldNotVerify` — the last with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
|
||||
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff }` — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
|
||||
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff, guardReason? }` — **`guardReason` (beta.13, optional)** is the guard's own reason ~~when it named a family~~ **whenever it refused (beta.18; beside a family only until then)**: `BlockedService` / `BlockedDriver` is a finding on the PC, not in the game, and the notice says so (§S23-3), and a refusal no family names is said in the guard's words (`Formats.GuardSentence`) — it printed the end's name, "reason RefusedByGuard"; `reason` stays the session's end reason — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch`, `PreScanCouldNotVerify` and, since 2026-09-21 (beta.4), `TargetUnreadable` — a protected process the Agent could not open (added 2026-10-04) — `PreScanCouldNotVerify` with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
|
||||
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Since beta.18 it says the end in words, `Formats.EndReasonText`; it printed `reason` raw — "The hook stopped (WriterSelfDisabled); the session continues without measuring" — and a stop ends the session, it does not continue it.)* *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff, guardReason? }` — `guardReason` as on `CaptureRefused` (beta.13) — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
|
||||
| `GameRemoved` | A→UI | `{ gameId, gameName?, exePath, reason }` — **since beta.19 (D55):** the Agent removed a library entry by itself; `reason` is `uninstalled` (its executable gone for ten minutes from a folder that is still there, no session, no anti-cheat block or exception — `06_DATA_MODEL` §Writer ownership). Not a session event. The Games page on screen reloads and says so; a game page showing that entry reloads into its not-found state. Additive: a client that does not know the type ignores it (§Versioning). |
|
||||
| `HookingTurnedOff` | A→UI | `{ gameId, gameName?, reason, family?, signal? }` — **since 2026-09-25 (beta.8):** the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) found anti-cheat in a game whose hooking the user had turned on, and turned it off. Not a session event — no session is running — so the UI's notice carries no "record without measuring" action, only Dismiss (`SafetyNoticeKind.HookingOff`). A finding on a game whose hooking was already off sends nothing: its page and its library card change, nothing the user switched on did. Additive: a client that does not know the type ignores it (§Versioning). |
|
||||
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and ~~no `SessionCompleted` follows~~ a `SessionCompleted` with `finalize: faulted` follows since 2026-09-23). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
|
||||
| `Ping`/`Pong` | ~~both~~ UI→A | 15 s keepalive, **client-driven** (built 2026-09-13): the client pings, the Agent answers; the Agent initiates nothing on an idle connection |
|
||||
@@ -453,7 +459,7 @@ message, and that message always re-scans.
|
||||
own from the same status. Before this a Dashboard opened after a game started read "Nothing is being captured.",
|
||||
the tray stayed idle for a session that began before the App connected, and the updater held an update at
|
||||
*Deferred* on a status read hours earlier.
|
||||
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with Repair.
|
||||
- Connect with 250 ms × 8 backoff; on failure start the Agent, retry; then show an Agent status banner with ~~Repair~~ Retry *(corrected 2026-10-04)*.
|
||||
|
||||
> **Amended 2026-09-17: never a second Agent.** A round that ends without a connection starts one only when no
|
||||
> process holds the user's data folder (`AgentInstanceLock`, probed through `IAgentLauncher.RunningAgent`) and the
|
||||
|
||||
+342
-37
@@ -19,16 +19,74 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
|
||||
status: Agent state shown as a pill in TitleBar trailing content + Dashboard card
|
||||
```
|
||||
|
||||
> **A viewer over a copy, beta.15 (owner decision D52).** `FrameLedger.exe --data-dir <folder>` opens the ledger in
|
||||
> `<folder>` — a COPY of a data folder — and keeps its log and crash dumps beside it. It starts and contacts no Agent: the
|
||||
> pipe is one per user, and the Agent behind it records into the profile's ledger, so a request carrying the copy's game
|
||||
> ids would act on other games (a consent written for the wrong one is rule 1's failure). Its composition holds no pipe
|
||||
> client, no launcher, no update check and no Run-entry writer (`Services.MachineFacingServices`,
|
||||
> `ViewerModeTests`); the pill reads *Viewer — no Agent*, a persistent InfoBar names the folder, and every control that
|
||||
> would ask the Agent or change the PC is disabled — hooking, the exception's grant and withdrawal, re-enabling, Delete
|
||||
> all sessions, the kill switch, the admin mode, the logon task, the Vulkan layer, Start with Windows, the automatic
|
||||
> update check, Help ▸ Check for updates, Tools ▸ Update detection rules and the tray's Pause — and, since beta.18,
|
||||
> every setting the Agent reads (the user-mode exception option and the three Recording numbers had been missed, and a
|
||||
> change said the capture agent would read it) and the update channel beside the update check
|
||||
> (`ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer`). The profile's own folder
|
||||
> is refused however it is spelled (case, separators, a relative path, a junction), as is a folder that does not exist;
|
||||
> a refusal is a message box and exit 2. The viewer's folder is its own single-instance key, so it runs beside the
|
||||
> profile's App. D6 is unchanged: the Agent's `--data-dir` stays under `--console`.
|
||||
|
||||
**NavigationView items:** Dashboard · Games · Compare · Logs — `Settings` lives in `FooterMenuItems`. Icons from `SymbolIcon` (Fluent System Icons; pick from the `SymbolRegular` enum — see 16 §Icons).
|
||||
|
||||
**Menu bar**
|
||||
- **File:** Add game… · Import library (Steam / GOG / Epic / itch.io) · Export ▸ (Session CSV / Session JSON / Chart PNG) · Exit
|
||||
- **Tools:** Agent status… · Update detection rules · Vulkan layer registration… · Open data folder · Database maintenance…
|
||||
- **Help:** Check for updates · Report a bug… · Documentation · Limitations · About FrameLedger (App / Developer / Third-party licenses tabs)
|
||||
- **Help:** User guide (beta.12) · Check for updates · Report a bug… · ~~Documentation~~ Online documentation · Limitations · About FrameLedger (~~App / Developer / Third-party licenses tabs~~ — built beta.12 as *This app* / *Third-party licences* / *Legal documents*, below)
|
||||
|
||||
> **Help ▸ Limitations, beta.10 (D36):** `LIMITATIONS.md` as the build embeds it (`Services.LimitationsDocument`), in a
|
||||
> read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*. It is information, not one of FR-11's documents:
|
||||
> ~~read-only, scrolling WPF UI `MessageBox` with *Open on GitHub*~~ window of its own since beta.12 (`Windows/DocumentWindow`,
|
||||
> rendered — below; corrected 2026-10-04). It is information, not one of FR-11's documents:
|
||||
> nothing is accepted or recorded, and the Disclaimer points at it.
|
||||
>
|
||||
> **Help ▸ User guide, beta.12 (D44).** `guide/` — ~~eight~~ short English pages for players (install, record a game, read
|
||||
> your results, anti-cheat and safety, your data, questions and answers, the terms in plain words; *since beta.17, D54,
|
||||
> also the screens, every setting, what to do when something goes wrong and the words the App uses — twelve pages,
|
||||
> and the wiki's End-user part*) — embedded in the
|
||||
> App (`Services.EmbeddedDocuments.Guide`, titles from each page's first heading) and shown in a `Windows/DocumentWindow`
|
||||
> with a page list, Limitations last; a link between guide pages opens the page in the window. Help ▸ Documentation is
|
||||
> *Online documentation*: the README at this build's source. `GuideDocumentsTests` holds every page listed and titled and
|
||||
> every link leading somewhere — and since beta.17 every section link (against the anchors the App's renderer gives the
|
||||
> target), the contents in the App's order, and that *Every setting* and *The screens* name every setting the Settings
|
||||
> page shows and every page and menu item of the main window.
|
||||
>
|
||||
> **Documents are rendered, beta.12 (owner request 4, D45).** Every Markdown document the App shows — the Legal Gate's
|
||||
> three texts, Help ▸ Limitations, the update notes, About's documents — is drawn by `Markdown/MarkdownRenderer`
|
||||
> (Markdig 1.4.0, BSD-2-Clause) into a WPF `FlowDocument` inside `Controls/MarkdownView` (a read-only
|
||||
> `FlowDocumentScrollViewer`: selectable, Ctrl+C, Ctrl+wheel zoom): headings, emphasis and strikethrough, inline and
|
||||
> fenced code in monospace, quotes, nested and numbered lists, pipe tables with a header row, rules, links. **HTML is
|
||||
> off** — a tag is shown as the text it is; **no image is fetched** — its description stands in; a node the renderer
|
||||
> does not know is shown as its own source text, and `MarkdownRendererTests` proves for every embedded document that
|
||||
> no word of its plain text is lost and no table is left as `|---|` source. The GPL's `LICENSE` is not Markdown: it is
|
||||
> shown as written, monospace. Colours and the font are theme resources (`16_WPFUI_SYNTAX` §FlowDocument).
|
||||
> **The wheel and the render, beta.21 (owner request 2026-10-13: "scrolling the documents is slow"):** a notch moves
|
||||
> Windows' *lines to scroll* at a browser's line (100/3 DIP; three lines = 100 DIP, scaled by the zoom; a delta in
|
||||
> proportion, so a touchpad's small deltas move a little; Windows' *one screen at a time* a screen) and eases there in
|
||||
> about 120 ms unless Windows' animations are off — WPF moved a fixed 48 DIP per message, whatever its delta. At its ends
|
||||
> the view leaves the wheel to what holds it (the update notes' dialog), and Ctrl+wheel stays the zoom. A page is
|
||||
> rendered once (`MarkdownView.Show`; three bindings changing ask for one render, ahead of layout), and a view keeps the
|
||||
> last 16 documents it rendered, so going back to a page costs its layout only (`MarkdownViewTests`). Links
|
||||
> follow `Markdown/MarkdownLinks`: http, https and mailto through `IUrlOpener`; `#section` scrolls to the heading
|
||||
> (GitHub's anchors); a relative path resolves against the document's place in the repository and opens in the App
|
||||
> when the window holds that page, on GitHub otherwise — **at this build's own source** (`Services/RepositoryLinks`:
|
||||
> the release's tag, stamped by `release.yml`; `main` for a local build — every link said `blob/main` before); any
|
||||
> other scheme (`file:`, `javascript:`, a drive or UNC path) is not followed, its address shown beside its text.
|
||||
> **Help ▸ Limitations** is a window of its own (`Windows/DocumentWindow`, one page, *Open on GitHub*); **Help ▸ About**
|
||||
> is `Windows/AboutWindow`, three tabs: *This app* — the version, and the program's Appropriate Legal Notices (GPLv3
|
||||
> §0, §5(d)): the copyright line, no warranty, the licence with the NOTICE terms, this version's source, *View the
|
||||
> licence* / *View NOTICE* / *Open the source code*; *Third-party licences* — `legal/THIRD_PARTY_NOTICES.md` and the
|
||||
> package index, rendered, and *Open the licences folder* (the published `licenses\`; a development build says it has
|
||||
> none); *Legal documents* — EULA, GPL, Disclaimer, Privacy Policy, NOTICE, Trademarks. Asking again brings the open
|
||||
> window forward (`Services/DocumentWindows`). Tests: `MarkdownRendererTests`, `MarkdownLinksTests`,
|
||||
> `DocumentWindowsTests`.
|
||||
|
||||
The Menu sits in its own row **below** the TitleBar (never inside the drag region — 16 §Gotchas).
|
||||
|
||||
@@ -80,7 +138,7 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
|
||||
## Notifications policy
|
||||
|
||||
- **In-app, transient** (rules updated, export done, non-fatal capture warning): `ISnackbarService` snackbar, 4 s.
|
||||
- **In-app, persistent** (Agent offline, PawnIO missing, update downloaded): `ui:InfoBar` banner pinned above content with action button.
|
||||
- **In-app, persistent** (Agent offline, ~~PawnIO missing,~~ update downloaded, a viewer's folder, the safety notices): `ui:InfoBar` banner pinned above content with action button. *(Corrected 2026-10-07: no PawnIO banner was ever built — CPU temperature reads N/A, and Settings ▸ System says it needs the admin mode and PawnIO; the viewer's banner (D52) and the safety notices were missing from the list.)*
|
||||
- **System-level, app possibly minimized** (session saved with "View" action, capture error while in tray, update available): tray balloon/toast via H.NotifyIcon.
|
||||
- One event → exactly one channel; never duplicate the same event across snackbar *and* tray.
|
||||
|
||||
@@ -107,6 +165,38 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
|
||||
> `SafetyNoticesTests` (the three kinds, the sentence per refusal reason, the strip for errors, nothing for a
|
||||
> session event, dismiss only by the user).
|
||||
>
|
||||
> **On this PC, not in this game — beta.13 (§S23-3).** A driver or a service is found machine-wide: while Easy
|
||||
> Anti-Cheat's service runs for another title, every game refuses with `BlockedService`, and the notice said the
|
||||
> family "was detected in this game". The events carry the guard's own reason (`guardReason`, `07_IPC`), and a
|
||||
> `BlockedService` / `BlockedDriver` refusal reads `Safety_Refused_MachineWide_Format` ("… is running on this PC (…): a
|
||||
> driver or service, which may belong to another game or program …"), an unhook `Safety_Unhooked_MachineWide_Format`,
|
||||
> and the summary's Tier-2 reason `Summary_Tier2_Why_MachineWide_Format`; a module, a title list or a file in the game
|
||||
> still reads "in this game". `Safety_Unhooked_Format` lost "will not inject into this game again until you enable it
|
||||
> again", untrue both ways since 2026-09-22 (a machine-wide finding turns no hooking off; a finding about the game turns
|
||||
> it off for good, which `Safety_HookingTurnedOff` then says). Without a `guardReason` — an older Agent — the notice
|
||||
> reads as before. Tests: `SafetyNoticesTests.AServiceOrDriverIsOnThisPcAndAModuleIsInThisGame`,
|
||||
> `…AnUnhookSaysWhereTheFindingWasAndPromisesNoReEnable`, `Tier2ReasonTests`.
|
||||
>
|
||||
> **Every notice in words — beta.18** (found while writing the guide, beta.17). Three texts printed what only the code
|
||||
> knows. The gate's own refusals — *Disable all hooking*, a game blocked before — carry the gate's label where a finding
|
||||
> carries its family, and the kill switch's notice read *"kill switch was detected in this game (the global 'disable all
|
||||
> hooking' switch is on (FR-2.4); …). FrameLedger will not inject into it, and nothing overrides that."* They are said as
|
||||
> the session's end now (`Formats.EndReasonText`: "All hooking is switched off in Settings, so nothing was measured."),
|
||||
> never as a finding. A refusal no family names read *"The anti-cheat guard did not hook this game: reason
|
||||
> RefusedByGuard."*: the events carry the guard's own reason for every refusal since (`07_IPC`), and the sentence is its
|
||||
> words — "… the game is 32-bit, and the hook runs in 64-bit games only."; an older Agent's reads `End_RefusedByGuard`.
|
||||
> A 30 s re-scan that could not look while the game still ran read *"Capture stopped: Access is denied. was detected while
|
||||
> the game was running"*; it reads `Safety_Unhooked_Unnamed_Format` ("Capture stopped while the game was running — the
|
||||
> game's process could not be opened — and FrameLedger unhooked."). And `CaptureDegraded` printed its reason raw and said
|
||||
> the session went on — *"The hook stopped (WriterSelfDisabled); the session continues without measuring."* — where a stop
|
||||
> ends it: the notice is the end's own sentence ("The measuring hook turned itself off after repeated faults, so measuring
|
||||
> stopped."), and `Notice_Degraded_Unknown_Format` names only a reason this build has no words for. Tests:
|
||||
> `NoticesFromTheAgentTests` builds each event as the Agent does — the gate's verdicts, the native facade's
|
||||
> (`AntiCheatVerdict.FromNative`), `RecordedSessionEvents.PublishReason`, the wire's codec — walks every refusal and every
|
||||
> stop, and refuses an enum's name, a requirement's id or "reason X" in any notice; it went red on the unfixed code with
|
||||
> exactly the texts above. Until then the notices' tests raised events written by hand ("GuardBlocked", "HookFaulted", a
|
||||
> guard reason sent as the end), which no Agent sends.
|
||||
>
|
||||
> **Corrected 2026-09-14, after the owner saw a red bar with no way out.** WPF UI 4.3.0's `InfoBar` template has
|
||||
> **no `ContentPresenter`**, so the action button above — placed as the InfoBar's Content, the only dismissal once
|
||||
> `IsClosable="False"` removed the X — was never rendered. The view model was right and the screen was wrong.
|
||||
@@ -138,7 +228,7 @@ Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes):
|
||||
|
||||
## Tri-state feature chips (RT / PT / RR)
|
||||
|
||||
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
|
||||
`TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. ~~Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override~~ *(corrected 2026-10-04: the source is the chip's tooltip, and a click opens FR-8.3's dialog, `TriStateOverridePrompt` — no flyout exists)* (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header.
|
||||
|
||||
## Screens
|
||||
|
||||
@@ -146,7 +236,7 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
|
||||
### Dashboard
|
||||
- Agent status `ui:CardControl` (state, capability badges as `InfoBadge`: telemetry source, Vulkan layer, ~~ETW fallback~~, PawnIO/CPU-temp, elevation — Repair button on error).
|
||||
- **Live capture card** (visible during capture): game name, **tier badge**, elapsed, live `FpsReadout` (5 s rolling), **measured** `renderW×H → outputW×H` with upscaler + quality, RT-active dot, CPU/GPU temp, per-process VRAM, sparkline (last 120 s) fed by `SessionProgress`. Tier 1 shows measured settings — this is the payoff of hooking and should read as facts, not guesses.
|
||||
- **Live capture card** (visible during capture): game name, **tier badge**, elapsed, live `FpsReadout` (5 s rolling), **measured** `renderW×H → outputW×H` with upscaler + quality, RT-active dot, CPU/GPU temp, ~~per-process VRAM~~ the game's own VRAM and RAM (beta.12: read from outside the game, so a held session has them too), sparkline (last 120 s) fed by `SessionProgress`. Tier 1 shows measured settings — this is the payoff of hooking and should read as facts, not guesses.
|
||||
- Recent sessions list (last 10 across games) → click opens session summary.
|
||||
- Totals strip: games tracked, total playtime, sessions this week (`ui:Card` row).
|
||||
|
||||
@@ -154,11 +244,15 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> is `LiveCaptureViewModel` over the pipe's `SessionStarted` / `SessionProgress` / `SessionCompleted`
|
||||
> (marshalled through the captured `SynchronizationContext`): game, tier badge, elapsed, the `FpsReadout` at
|
||||
> 1 Hz under the display rule (Presented FPS with its census chip until frame generation is measured), the
|
||||
> measured `renderW×H → outputW×H` with upscaler + quality, the RT chip, GPU/CPU temperature, per-process VRAM.
|
||||
> The sparkline is PR-6's. Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed
|
||||
> measured `renderW×H → outputW×H` with upscaler + quality, the RT chip, GPU/CPU temperature, ~~per-process VRAM~~
|
||||
> (corrected 2026-10-03: that line read the Overlay's per-present VRAM, which nothing produced, so it was always empty;
|
||||
> since beta.12 it is "This game: VRAM … · RAM …" from the newest telemetry tick, `GameMemoryText.Live`).
|
||||
> ~~The sparkline is PR-6's.~~ Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed
|
||||
> session reloads the lists (the row is in SQLite, `07_IPC` §Client behavior). Totals = the library's games,
|
||||
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. Capability badges and the Repair button are
|
||||
> PR-8's with the Agent section.
|
||||
> `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. ~~Capability badges and the Repair button are
|
||||
> PR-8's with the Agent section.~~ *(Corrected 2026-10-04: PR-6 and PR-8 shipped without them. No sparkline exists,
|
||||
> here or on the Games cards; the Agent card shows its facts as text, and the Vulkan layer state and the logon
|
||||
> task's Repair are on Settings.)*
|
||||
>
|
||||
> **Amended 2026-09-23: the card shows every running session, measured or not.** A session held unhooked
|
||||
> (Tier 2 — hooking off, refused, unreadable) shows its name, the T2 badge, the elapsed time and the
|
||||
@@ -175,16 +269,45 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
|
||||
### Games (grid → detail)
|
||||
- `GridView`-style panel of cover cards (`ui:CardAction`): name, platform badge, engine badge, total playtime, last played, mini trend sparkline (avg Native FPS last 10 sessions). Sort/filter/`ui:AutoSuggestBox` search.
|
||||
> **The library, beta.11 (owner requests 2026-10-03).** *The empty band on the right:* the cards were 300 px in a plain
|
||||
> `WrapPanel`, so at ~1350 px three fitted and a card's width was left unused; the grid is now
|
||||
> `Controls.UniformWrapPanel` — as many columns as fit at 300 px or wider, every card an equal share of the width, each row
|
||||
> as tall as its tallest card — and the pill row wraps instead of cutting its last pill. **Grid or list** (owner's choice:
|
||||
> switch between the two): the button beside the sort shows the other view; the list is one row per game (name, store,
|
||||
> engine, status, sessions, played, last played; double-click or Enter opens it), and the choice is `ui.library_view`.
|
||||
> **The count** is in the title (*Games · 42*). **Refresh** reads the library again, then asks the stores for games installed
|
||||
> since (`ImportLibraryFlow.RunAsync(onlyNew: true)`: *No new games* and no checklist when there are none), and every entry
|
||||
> whose executable is not on disk carries a **Not installed** pill — its tooltip is the game page's own sentence for it,
|
||||
> the drive that is not connected or the path the file is gone from (`GameLibrary.ExecutableExists` and
|
||||
> `Formats.ExecutableMissingText`, asked off the UI thread on every listing, never stored; ~~nothing is removed for it~~
|
||||
> *since beta.19 (D55) the Agent removes such an entry by itself after ten minutes when it has no session and no
|
||||
> anti-cheat block or exception, and its drive is connected — Settings ▸ Data ▸ Remove uninstalled games, on by default; the
|
||||
> page on screen hears `GameRemoved`, reloads and says so in the snackbar (`Games_Removed_Format`); one with sessions keeps
|
||||
> its pill. One check removes its games in one event each, milliseconds apart: the page waits `GamesViewModel.RemovalSettle`
|
||||
> (one second) after the first, then reads the library once and says them all in one notice — the count, five names and
|
||||
> how many more, `Games_Removed_Many_Format`. It said each and reloaded each, and WPF UI 4.3.0's `SnackbarService` shows every
|
||||
> message at once in its one snackbar, so only the last name stayed on screen. And only the newest read of the library is
|
||||
> shown: reads overlap — a session that ends, an import, a removal — and the one that started first could finish last,
|
||||
> its executable checks waiting on a slow drive, and put back a removed game's card (`GamesViewModel.LoadAsync`,
|
||||
> `GamesViewModelTests.AnOlderReadThatFinishesLastIsNotShownOverANewerOne`)*). **The page reloads by itself** while it is on screen when a session ends (`SessionCompleted`) or an
|
||||
> import adds games (`LibraryChanges` — navigating to the page already on screen does nothing in WPF UI 4.3.0, so an
|
||||
> import from the menu never showed until the page was left). **Import** (FR-1.2): the games already in the library — at
|
||||
> this path or under another drive letter — are hidden by default (*Show the N games already in the library* brings them
|
||||
> back, dimmed), and a row that cannot be imported has its box disabled; the XAML comment said "cannot be ticked" while a
|
||||
> tick was taken and ignored. Tests: `GamesViewModelTests`, `ImportLibraryFlowTests.RefreshOffersOnlyNewGamesAndSaysWhenThereAreNone`,
|
||||
> `…GamesAlreadyInTheLibraryAreHiddenUntilAskedFor`, `PagesLoadTests.TheLibraryGridFillsItsWidthAndTheListViewReplacesIt`,
|
||||
> `…TheImportChecklistRendersWithTheExistingRowsShown`.
|
||||
>
|
||||
- **Game detail:**
|
||||
- Header: cover, name, publisher, version, platform, engine+version, API + Present Mode of last session, `FpsReadout` (lifetime avg), TriState chips, Edit button.
|
||||
- **Two clearly separated rows** (`05_DETECTION` §Capability hints — conflating these was the old design's core mistake):
|
||||
- **Supports** — greyed capability chips from files on disk ("Supports DLSS-G", "Supports XeSS"). Static inference.
|
||||
- **Supports** — greyed capability chips from files on disk ("Supports DLSS-G", "Supports XeSS"). Static inference. With none: *not scanned yet* until the Agent's sweep has read the executable, then *none found* (beta.21 — it read "not scanned yet" for every game that ships none of the files).
|
||||
- **Last session measured** — accent chips with real values ("DLSS Quality · 1440p → 2160p", "Frame Generation DLSS-G ×1.9", "Ray Tracing: Yes"). Measured.
|
||||
- **Hooking control** (`ui:CardControl` with `ToggleSwitch`): off by default. Turning it on opens the consent dialog (FR-2.1). When the static anti-cheat pre-scan blocked it, the switch is **disabled** with the reason shown inline and no way to force it. When auto-disabled after crashes, an `InfoBar` explains and offers manual re-enable.
|
||||
|
||||
> **Built 2026-09-14 (P3 PR-5): the grid, the detail page's header, the two rows, the hooking control and
|
||||
> the Sessions tab.** Grid: `ui:CardAction` cards with platform / engine / hooking badges, sessions, playtime,
|
||||
> last played (the sparkline is PR-6's); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
|
||||
> last played (~~the sparkline is PR-6's~~ no sparkline was built — corrected 2026-10-04); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
|
||||
> button, or an `.exe` dropped on the page (a `.lnk` needs the shell-link reader, later); FR-1.4 through
|
||||
> `Wpf.Ui.Controls.MessageBox` with **Keep sessions / Delete sessions too**, revoking consent over the pipe
|
||||
> FIRST when it was on. Detail: header (name, publisher · version · store · engine, last session's date and
|
||||
@@ -193,7 +316,10 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> fields), **the row's executable path under the subtitle and Change executable… since 2026-09-21** (a store import
|
||||
> guesses the executable and everything downstream is keyed on it; the pick re-points the row, which comes back
|
||||
> hooking-off and unconsented like a new game, consent revoked over the pipe first, a block never cleared —
|
||||
> `05_DETECTION` §Library import), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside
|
||||
> `05_DETECTION` §Library import; **since beta.19 the file dialog opens in the game's own folder** — `GameFolder.StartFolder`:
|
||||
> the store boundary's install folder (`InstallRoot`), an Unreal package's root above `<Project>\Binaries\Win64`, else
|
||||
> the executable's folder, and the nearest folder still there when that one is gone; nothing for a drive that is not
|
||||
> connected, where Windows opens its last folder; owner request 2026-10-12, `GameFolderTests`), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside
|
||||
> **Last session measured** (upscaler · resolution, frame generation, the non-N/A chips — accent pills, from the
|
||||
> hooks). Hooking: the toggle is `OneWay` from the row and its command runs `HookingConsent`; a refusal, a
|
||||
> mismatch or a failure is a persistent `InfoBar` on the page (never a toast); a blocked row disables the
|
||||
@@ -268,12 +394,33 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> `FormatsTests`, and the page renders in `PagesLoadTests`. **The Details card's *NVIDIA App override* row** (same day)
|
||||
> is the newest session that read a driver profile, in the same words; no row where none did. Tests:
|
||||
> `NvidiaOverridesTests`, `GameDetailViewModelTests.TheDetailsCardNamesTheNvidiaAppsOverridesFromTheNewestSessionThatReadThem`.
|
||||
> **The *Engine* row carries the version, and an *Engine version* row says what it was read from** (beta.10 for Unreal;
|
||||
> beta.19 for Unity, Godot and RPG Maker; beta.20 for Ren'Py — `05_DETECTION` §Engine version): the player library, the
|
||||
> data file's header, a data pack, a core script, the RGSS library `Game.ini` names or Ren'Py's `renpy/vc_version.py`, and
|
||||
> *Not found in the game's files* once the Agent has
|
||||
> read such a title and found none. RPG Maker's witness names the maker on the page, the subtitle and the library card
|
||||
> (*RPG Maker MZ 1.10.0*, *RPG Maker VX Ace (RGSS 3.0.1)*; `Formats.Engine(id, source)`). Tests:
|
||||
> `GameDetailViewModelTests.TheDetailsCardSaysWhatAUnityGodotOrRpgMakerVersionWasReadFrom`,
|
||||
> `FormatsTests.TheVersionsWitnessNamesTheMakerAndRgssSaysWhoseNumberItIs`.
|
||||
- Tabs (WPF `TabControl`, Fluent-styled):
|
||||
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. Multi-select → "Compare". Tier-2 rows render `—` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why.
|
||||
1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. ~~Multi-select → "Compare".~~ (not built; Compare's own picker chooses) Tier-2 rows render ~~`—`~~ `N/A` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why *(corrected 2026-10-04: as built — `—` means a measured none, §FPS display rule)*.
|
||||
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
|
||||
3. **Distribution** — FPS histogram + percentile curve of selected session(s).
|
||||
4. **Trend** — metric-over-date line (selector: Native avg / Displayed avg / 1% Low / 0.1% Low / max GPU temp), vertical **hardware-change markers** with tooltip "GPU driver 572.16 → 576.02" (FR-6.3).
|
||||
|
||||
> **Across sessions, beta.11 (owner decision D39, FR-6.6).** The **Sessions** tab opens with *Sessions at a glance*: a
|
||||
> `TrendChart` of every hooked session's Presented FPS (sessions that counted no generated frame), Native and Displayed
|
||||
> (sessions where frame generation was measured — rule 6, never one inflated line) and 1% / 0.1% lows, oldest first,
|
||||
> partial sessions hollow (`TrendSeriesBuilder.Overview`); a click near a session's points selects it in the grid and
|
||||
> scrolls to it (`TrendChart.SessionClicked`). Under it, **Delete all sessions…** (FR-1.7) for this game. The **Trend**
|
||||
> keeps its selector and adds *Also draw*: any other metric ticked is drawn on the same chart, its unit
|
||||
> (`TrendSeriesBuilder.UnitOf`: FPS, °C, %, W, MB, ×) on the left axis when it is the selected metric's and on the right
|
||||
> when it is a second one (marked ▸ in the legend); a metric in a third unit cannot be ticked, and when the selected
|
||||
> metric changes to a third unit only the first ticked unit in the list stays ticked, so every ticked box has its line;
|
||||
> the selected metric is not offered beside itself. One line alone keeps its name on the axis, as before. After any delete — here or in
|
||||
> Settings — a summary window still open on a deleted session closes, and File ▸ Export lets go of it (`SessionDeletion`;
|
||||
> ids are reused once the newest is gone). Tests: `SessionDeletionAndOverviewTests`.
|
||||
>
|
||||
> **The display mode, beta.10 (FR-7.4, `03_METRICS` §Display mode).** The **Last session measured** row adds how that
|
||||
> session was shown — the mode that lasted longest with its share and the window's size (`Display: Borderless 92% ·
|
||||
> 2560×1440`); the **Sessions** tab has a *Display* column for every session, Tier 2 included (the mode shown longest,
|
||||
@@ -282,7 +429,30 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> share %*, *Windowed share %* — over every session whatever its tier, never left out as a mid-session change (a mode
|
||||
> switch resizes the swap chain, and the share is what that switch was), with no exclusive or borderless point for a
|
||||
> session that had any time nothing could split (`Services.DisplayText`, `Charts.TrendSeriesBuilder.DisplayShare`).
|
||||
5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series.
|
||||
>
|
||||
> **The game's own memory, beta.12 (owner decision D43, `03_METRICS` §Game process memory).** Read from outside the game
|
||||
> once a second in either tier, it is shown wherever a session is (`Services.GameMemoryText`, from the stored columns and
|
||||
> `sensor_stats_json` — never recomputed). The **Sessions** tab has *VRAM (game)* and *RAM (game)*: the median · the
|
||||
> peak, in Task Manager's units (MB below 1 GB, GB to two decimals, 1 GB = 1024 MB, `Formats.Memory`), the tooltip
|
||||
> carrying the mean, the shared GPU memory's peak, the working set's and the commit's peaks, and how many processes were
|
||||
> added together where an unpinned hold summed more than one. Where Windows did not report the private working set, the
|
||||
> working set is shown and SAYS so ("(working set)") — never passed off as Task Manager's "Memory". The **Trend** replaces
|
||||
> *Max VRAM (game)* — which read `vram_proc_max_mb`, a column nothing ever wrote, so it never had a point — with *Median /
|
||||
> Peak VRAM (game)* and *Median / Peak RAM (game)* in GB, machine metrics that count Tier-2 sessions (the RAM lines are the
|
||||
> private working set only: a working-set-only session has no point there rather than another quantity on the line);
|
||||
> *Avg RAM in use* is the whole PC's, now in GB too. **Compare** adds the four as rows that rank nothing — a game that uses
|
||||
> more of a card it has is not worse. The **Sensors** tab and the summary's Sensors section draw two memory plots in GB:
|
||||
> *Video memory (VRAM)* — this game's dedicated and shared beside the whole graphics card's — and *Memory (RAM)* — this
|
||||
> game's private working set (or its working set, labelled) beside the whole PC's; this game is one colour on both. The
|
||||
> **summary** adds two cards, *VRAM (this game)* and *RAM (this game)* — the median, with "median · peak … · shared …" /
|
||||
> "… · commit …" beneath — and a table, **Statistics per series**: every stored series' mean, median, minimum, peak and
|
||||
> number of readings, each in its own unit (`Services.SensorStatsTable`); a session recorded before beta.12 shows one
|
||||
> sentence instead of the table. The **live card** shows "This game: VRAM … · RAM …" from the newest tick, a held session
|
||||
> included, and the CSV gains the `# game_memory:` header line. Tests: `GameMemoryTextTests`,
|
||||
> `SessionSummaryViewModelTests.TheGamesMemoryAndTheStoredStatisticsAreShownForASessionThatWasNotHooked`,
|
||||
> `TrendSeriesBuilderTests`, `CompareViewModelTests`, `ChartMathTests.TheMemoryPlotFallsBackToTheWorkingSetUnderItsOwnName`,
|
||||
> `LiveCaptureViewModelTests`, `SessionExporterTests`.
|
||||
5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series. Since beta.12 two memory plots in GB: *Video memory (VRAM)* (this game's dedicated and shared, the whole graphics card's) and *Memory (RAM)* (this game's private working set, the whole PC's).
|
||||
6. **Latency** *(Tier 1 + Reflex only)* — PC latency timeline, avg/p95.
|
||||
|
||||
> **Built 2026-09-14 (P3 PR-7): tabs 2–6.** Frametime and Distribution show the session selected in the
|
||||
@@ -293,10 +463,18 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> GPU °C), FR-6.4's exclusion of `settings_changed_midsession` sessions by default with the toggle and the
|
||||
> excluded count, and FR-6.3's markers — labelled dashed lines wherever two consecutive sessions' hardware
|
||||
> snapshots differ in GPU driver, GPU, CPU, display mode or OS ("GPU driver: 572.16 → 576.02"). **Sensors**:
|
||||
> GPU core / hotspot °C, load % and power W (right axis) on one plot; VRAM on another with the game's own
|
||||
> per-present `vram_proc` (a held 1 Hz sample) and the adapter-wide `vram_adapter` sensor as two
|
||||
> differently-labelled series. **Latency**: the `latency_us` blob with the stored avg / p95 lines, shown only
|
||||
> when Reflex reported (`reflex_active`); otherwise the tab says so.
|
||||
> GPU core / hotspot °C, load % and power W (right axis) on one plot; VRAM on another with ~~the game's own
|
||||
> per-present `vram_proc` (a held 1 Hz sample) and~~ the adapter-wide `vram_adapter` sensor ~~as two
|
||||
> differently-labelled series~~ (corrected 2026-10-03: the Overlay never produced `vram_proc`, so the game's line was
|
||||
> never drawn on any session; beta.12's two memory plots are described above). **Latency**: the `latency_us` blob with the stored avg / p95 lines, shown only
|
||||
> when Reflex reported (`reflex_active`); otherwise the tab says so. **Since beta.14 the tab itself is shown only when one
|
||||
> of the game's sessions measured latency** (`GameDetailViewModel.AnyLatency`): nothing measures Reflex today, and a tab
|
||||
> that could only say "no data" was noise.
|
||||
>
|
||||
> **Trend, beta.14 (D49):** nine more metrics — *Time below 60 FPS %*, *Display under refresh rate %*, *Frame to frame
|
||||
> ms*, *Render scale %* (`100 / upscale_ratio`), *VSync share %* and *Frames per watt* from hooked sessions; *Avg GPU core
|
||||
> clock MHz*, *Max GPU memory °C* and *Held back by power limit %* from every session's telemetry. Each has its own unit
|
||||
> (ms, MHz and FPS/W are new axes); a session recorded before beta.14 has no point (`TrendSeriesBuilderTests`).
|
||||
>
|
||||
> **Trend, corrected 2026-09-25 (beta.8, owner item 6: "does Trend really work?").** It did not, on first open: the
|
||||
> view model started loading before the page existed, and a load that finished first raised `TrendPresented` to nobody
|
||||
@@ -325,9 +503,47 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> rows rank nothing; the percentile axis is 0–100 again (`AutoScale` ran after `SetLimitsX` and undid it); exported
|
||||
> PNGs have an opaque background (`ChartTheme.SavePng`: the window's colour under the transparent figure).
|
||||
|
||||
### Session summary (secondary `FluentWindow`, also the post-session toast target)
|
||||
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration, **Display** — beta.10: the mode shown longest with its share and the window's size, both tiers), TriState chips, API/PresentMode/upscaler line, **the display line** (beta.10: every mode's share, the changes, the window on its monitor at its refresh rate, the back buffer and swap effect, and what the facts rested on — "the swap chain said whether it was exclusive" or "from the window alone: exclusive fullscreen cannot be told from borderless"; absent for a session recorded before), crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
|
||||
> **Play, beta.21 (owner decision D59: "1: press Play → the platform opens → it runs; 3: it runs at once; let me switch
|
||||
> between the two").** A **Play** button heads a game's page (before Edit…, Primary) and sits on each library card's
|
||||
> corner — over the card, not inside it, so the card stays one button — and in the list's first column. **Settings ▸
|
||||
> Games ▸ Play button** (`ui.play_mode`): *Through the store* (the default) hands the game to the app of the store whose
|
||||
> own records name its folder — the records the import reads (`Application.Play.StoreRecords`; the row's `platform` is not
|
||||
> trusted, detection may have rewritten it while `store_id` stayed the importer's) — Steam `steam://rungameid/<id>`, the
|
||||
> Epic Games Launcher `com.epicgames.launcher://apps/<ns>%3A<item>%3A<app>?action=launch&silent=true`, GOG GALAXY
|
||||
> `GalaxyClient.exe /command=runGame /gameId=<id> /path="<folder>"`, the itch app `itch://install?game_id=<id>&launch`
|
||||
> (`StoreLaunches`: the forms the stores' own shortcuts and code use, measured on the owner's PC except Epic's; every id
|
||||
> checked against its store's shape before the shell gets it). No store, GOG without GALAXY, or the App itself running as
|
||||
> administrator: the agent starts the game instead, and the notice says why. *Start directly* sends `LaunchGame` (launch
|
||||
> mode): recorded from the first frame, never as administrator, refused for a recording-off entry. A viewer's (D52) Play is
|
||||
> off and its composition holds no `ShellStarter`. Tests: `StoreLaunchesTests`, `StoreRecordsTests`, `GamePlayerTests`,
|
||||
> `ViewerModeTests`.
|
||||
|
||||
### Session summary (secondary `FluentWindow`, also the post-session toast target)
|
||||
Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration, **Display** — beta.10: the mode shown longest with its share and the window's size, both tiers; **VRAM (this game)** and **RAM (this game)** — beta.12: the median with the peak beneath, both tiers), **Statistics per series** (beta.12: every stored series' mean / median / minimum / peak), TriState chips, API/PresentMode/upscaler line, **the display line** (beta.10: every mode's share, the changes, the window on its monitor at its refresh rate, the back buffer and swap effect, and what the facts rested on — "the swap chain said whether it was exclusive" or "from the window alone: exclusive fullscreen cannot be told from borderless"; absent for a session recorded before), crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons.
|
||||
|
||||
> **beta.14 (D49): the new measurements, as cards and charts.** The cards come in three methods (`AddFrameCards`,
|
||||
> `AddPacingCards`, `AddMachineCards`), every value read from the row — never recomputed — and N/A on a row written before
|
||||
> beta.14:
|
||||
> - **Time below 60 FPS** with *below 30* and *display under {refresh} Hz* beneath it — the refresh share named for the
|
||||
> display because it is over the presents the display received (`03_METRICS` §Pacing) — and **Frame to frame**; both
|
||||
> carry *(presented)* where the session's statistics are over presents, as the lows do.
|
||||
> - **VSync** (*{share} of frames*, with *tearing allowed* beneath), **Ray tracing** (*{share} of frames* and rays per
|
||||
> pixel — the card appears only where ray tracing was measured), **Game in focus** (foreground ticks over drain ticks)
|
||||
> and **Capture quality** (gaps · lost records · faults).
|
||||
> - The **1% Low** card carries *displayed: {presents' 1% low}* beneath it where frames were generated (rule 6: beside the
|
||||
> game's own, never instead of it).
|
||||
> - **GPU clocks** (core · memory, with fan and memory temperature beneath), **GPU held back** (power · heat, NVIDIA only)
|
||||
> and **Frames per watt** (*the game's own frames, GPU power only*).
|
||||
>
|
||||
> Charts: **Render scale** under Distribution (`Charts/RenderScaleChart` over `RenderScaleSeries`: `100 × √(render pixels /
|
||||
> output pixels)` as steps — from the `render_res` blob where the resolution varied, a flat line at the row's extent where
|
||||
> it did not, and a sentence where the upscaler's parameters were never measured), and on **Sensors** the card's memory
|
||||
> temperature on the temperatures plot (its own palette colour, `Chart_SensorTertiary`: no existing one was 60 apart from
|
||||
> all six beside it) and a fourth plot, **Clocks and fan** — core and memory clock in MHz, the fan in RPM on the right, and
|
||||
> the ticks its power limit or heat held it back shaded behind them; collapsed when the session stored none of these.
|
||||
> Tests: `SessionSummaryViewModelTests` (the new cards, a row before beta.14 at N/A, the displayed low),
|
||||
> `RenderScaleAndClocksTests`, `ChartMathTests`.
|
||||
>
|
||||
> **Built 2026-09-14 (P3 PR-6).** `Windows/SessionSummaryWindow` (a secondary `FluentWindow` with its own
|
||||
> `ContentDialogHost`), opened from a Sessions-tab row (double-click or Open) and from the Dashboard's recent
|
||||
> list. Stat cards read the STORED aggregates — never recomputed — with the lows labelled *(presented)* when
|
||||
@@ -371,8 +587,9 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
|
||||
> beyond a percentile on each side — FR-4.8's rule, generalised — so its 1% and 0.1% lows are marked exactly where
|
||||
> the stat cards publish them, and the single shortest interval no longer sets the axis; the 0–100 axis holds.
|
||||
> - **Sensors** (the tab and a new section of the summary window): power on a watt axis at the right, the second
|
||||
> plot is *Memory* (the game's VRAM, the adapter's, the system's RAM), a per-present VRAM of 0 is a present the sample
|
||||
> did not reach and is left out, the time axis says where its zero is, and every line has its own colour in both
|
||||
> plot is *Memory* (the game's VRAM, the adapter's, the system's RAM), ~~a per-present VRAM of 0 is a present the sample
|
||||
> did not reach and is left out~~ (corrected 2026-10-03: there was no per-present VRAM to draw — the Overlay never
|
||||
> produced it; beta.12 replaced the plot with two, above), the time axis says where its zero is, and every line has its own colour in both
|
||||
> themes (the light theme drew power and CPU temperature in one gold). **A session that was not hooked charts its
|
||||
> sensors** — kept since 2026-09-22, shown nowhere until now.
|
||||
> - **The game page follows the Agent while it is shown**: a `SessionCompleted` for this game reloads it
|
||||
@@ -381,7 +598,8 @@ Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutte
|
||||
> **FR-5.3:** `Charts/Decimator` — every bucket's min and max in order, ≤ 4000 points per series per draw, a
|
||||
> 500k-point series keeps its spike and its dip (`DecimatorTests`). Zoom and pan are ScottPlot's.
|
||||
> **FR-9:** `SessionExporter` — the CSV with `03_METRICS` §Export schema's column line verbatim and the `#`
|
||||
> header block (tier, api, hardware, the tri-states with sources, the segments, the 1 Hz VRAM note),
|
||||
> header block (tier, api, hardware, the tri-states with sources, the segments, ~~the 1 Hz VRAM note~~ — since beta.12
|
||||
> the `# game_memory:` line, and a note that `vram_mb` is the in-game figure this build does not produce),
|
||||
> InvariantCulture throughout, no rows for Tier 2; the JSON (`frameledger-session/1`: metadata, the row as
|
||||
> aggregates with N/A omitted, segments, the annotation); PNG through `Plot.SavePng`. Tags (comma-separated,
|
||||
> de-duplicated) and notes save to the annotation row. **FR-3.8** is an in-app notice on `SessionCompleted`
|
||||
@@ -430,6 +648,13 @@ Session picker (2–5, cross-game allowed) → overlaid percentile curves + stat
|
||||
>
|
||||
> **beta.10:** three rows after Duration — *Display mode* (every share), *Window* and *Monitor* (with its refresh
|
||||
> rate) — facts, not scores: no mode is better than another, so none is ever marked best, and every tier has them.
|
||||
>
|
||||
> **beta.14 (D49):** *Time below 60 FPS* and *Frame to frame* (lower is better), *Display under refresh rate* (lower is
|
||||
> better), *VSync share* and *Render scale* (settings: no best), *Avg GPU core clock* and *Held back by power limit*
|
||||
> (facts: no best), *Max GPU memory °C* (lower) and *Frames per watt* (higher). **A statistic a present-only session has
|
||||
> over its presents carries *(presented)* in its cell** — the median, the lows, stutter, time below 60, frame to frame —
|
||||
> beside a session whose same statistic is over the game's own frames; the best is decided on the number, never the label
|
||||
> (`CompareViewModel.Row`'s label, `CompareViewModelTests`).
|
||||
|
||||
### Logs
|
||||
Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:AutoSuggestBox`), pause-scroll; buttons: Open logs folder, Export bug bundle (routes to 10_LOGGING flow).
|
||||
@@ -438,18 +663,47 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
|
||||
> (App / Agent) read with `FileShare.ReadWrite` — Serilog keeps it open — capped at the last 2 MB with the partial
|
||||
> first line dropped, refreshed every 2 s while the page is on screen (the page's Loaded/Unloaded start and stop
|
||||
> the timer) and never while paused; the level filter reads the `[HH:mm:ss.fff LVL]` prefix of 10_LOGGING's
|
||||
> template (continuation lines such as stack frames keep only under All); the search is a plain `ui:TextBox`, not
|
||||
> template ~~(continuation lines such as stack frames keep only under All)~~ — the App's; *(corrected 2026-10-04: the
|
||||
> Agent writes Serilog's default template, a date first, which the filter did not read, so Warning and Error showed no
|
||||
> Agent line; since beta.12 `LogTail.LevelOf` reads both)* — continuation lines such as stack frames keep only under All; the search is a plain `ui:TextBox`, not
|
||||
> an `AutoSuggestBox` — there is nothing to suggest. The view is a read-only `TextBox` in Consolas that scrolls to
|
||||
> the end on every refresh unless paused. "Export bug bundle" is 10_LOGGING's step 2 and nothing more (see there).
|
||||
> The status line says shown / total / file. Tests: `LogTailTests`, `LogsViewModelTests`, and the page renders in
|
||||
> `PagesLoadTests`.
|
||||
|
||||
### Settings
|
||||
> **beta.14 (owner request 2026-10-05: "an option to hide the scroll bars but still scroll").** The Window section has
|
||||
> **Hide scroll bars** (`ui.hide_scrollbars`, off by default). A bar's visibility is bound inside its scroller's template,
|
||||
> which no style reaches, so `Services.ScrollBarHiding` sets the scrollers themselves: ~~one class handler on
|
||||
> `ScrollViewer`'s Loaded (registered at start beside `DialogKeyboard`) reaches every scroller the App shows~~ class
|
||||
> handlers on `ScrollViewer`'s ScrollChanged and Loaded (registered at start beside `DialogKeyboard`) reach every scroller
|
||||
> the App shows *(corrected 2026-10-07, beta.17, the owner's screenshot of the Dashboard with its bar: WPF raises Loaded
|
||||
> only where a subtree listens for it with a handler of its own, and a class handler is not one — `16_WPFUI_SYNTAX`
|
||||
> §Gotchas. Settings, full of toggle switches whose template listens, lost its bar; the Dashboard, the first run, About,
|
||||
> the user guide and a game's wide sessions table kept theirs. Every scroller raises ScrollChanged from its first layout)*,
|
||||
> those inside a DataGrid, a TextBox, a rendered document and a dialog included. While on, an axis that is `Auto` or `Visible` becomes
|
||||
> `Hidden` — WPF's "no bar, still scrolls": wheel, keyboard and touch — and its own value is kept on it; a `Disabled` axis is
|
||||
> never touched (it lays its content out at the viewport's width). The toggle applies to the open windows at once, and off
|
||||
> puts every kept value back. Tests: `ScrollBarHidingTests` (on hides every bar and the wheel still scrolls; off restores
|
||||
> each; a scroller that loads later follows; since beta.17 a scroller laid out with no Loaded at all, and every page,
|
||||
> window and dialog shown in a real window with the option on), `SettingsViewModelTests.HidingScrollBars…`.
|
||||
|
||||
> **beta.11 (owner request 2026-10-03: "remove the Settings rows that have no button or similar").** Every row has a control
|
||||
> now: the *Games with hooking on* card shows only while a game has hooking on (its empty sentence is gone); the *Elevation*
|
||||
> card is gone and its state is the third line of *Run the agent as administrator* (its explanation a tooltip on it); the
|
||||
> sentence under the language row is gone. A **Data** section has one row, **Delete all sessions…** (FR-1.7): the
|
||||
> confirmation names how many, the Agent deletes them (`DeleteSessions`), and the strip says what happened or why nothing
|
||||
> was deleted (a session being recorded, no agent, an older agent). Tests: `SettingsViewModelTests.DeleteAllSessionsAsksWithTheTotalThenGoesThroughTheAgent`.
|
||||
> **Since beta.19 (D55) the Data section's first row is *Remove uninstalled games*** (`retention.remove_uninstalled_games`,
|
||||
> on by default, off in a viewer like every setting the Agent reads): its strip says the Agent reads it within 15 seconds
|
||||
> (`Settings_RemoveUninstalled_Applied`), not at the next session — the detection sweep reads it at every pass. Tests:
|
||||
> `ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer`, `GuideDocumentsTests.TheSettingsPageOfTheGuideNamesEverySetting`.
|
||||
|
||||
Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExpander` rows with `ToggleSwitch`, `ComboBox`, `ui:NumberBox` (numeric inputs — min session length, sensor interval, retention). Language switch applies immediately (09_I18N). Theme selector (Light/Dark/System) drives `ApplicationThemeManager` (16 §Theming). **Capture section (top, most important):** the global **hooking kill switch** (`ToggleSwitch`, prominent) with a one-line summary of what it does; a list of games currently hook-enabled with a per-game revoke; Vulkan layer registration state + Register/Unregister; a link to the safety documentation. Turning the global switch off must take effect immediately, including for the Vulkan layer.
|
||||
|
||||
**System (2026-09-21, FR "show the user's hardware"):** a card above Legal stating this PC as a session's hardware snapshot would record it right now — processor, graphics card, graphics driver, memory, Windows build, primary display — through the same `IHardwareSnapshotSource` the Agent stamps sessions with, read on the thread pool when the page opens, a field that could not be read as N/A, with **Copy** (the same lines as text) and a note that nothing is sent anywhere and what CPU temperature needs. Its own `SystemInfoViewModel`, not `SettingsViewModel`'s. The same snapshot is one tertiary line under the session summary's header (it was loaded for the export and shown nowhere), and `--diag` prints it; the bug bundle's `sysinfo.json` is deliberately NOT given it — its keys are the issue link's prefill.
|
||||
|
||||
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
|
||||
Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", ~~background capture toggle~~ *(removed in beta.12 — nothing read it; corrected 2026-10-04)*. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents.
|
||||
|
||||
> **The admin mode, beta.10 (owner decision D34; `01_ARCHITECTURE` ADR-9).** The Agent section has a switch, *Run the agent
|
||||
> as administrator* (`capture.run_elevated`, off by default). Turning it on opens a `ContentDialog`
|
||||
@@ -465,7 +719,8 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> **Built 2026-09-14 (P3 PR-8a), with three rows deferred to PR-8b and one to PR-9.** `SettingsViewModel` over
|
||||
> `Application.Settings.RegisteredSettings` (the registry of `06_DATA_MODEL` §Settings registry — every write is
|
||||
> one `settings` row, and a key the Agent reads gets the 4 s "Applied. The capture agent reads it at the next
|
||||
> session start" line, D16). **Capture, first:** the kill switch as a `CardExpander` whose header is the toggle
|
||||
> session start" line, D16 — but for turning the kill switch on, which says a game being measured stops at its next
|
||||
> safety scan, within 30 seconds: beta.18; until then it said the next session start). **Capture, first:** the kill switch as a `CardExpander` whose header is the toggle
|
||||
> and whose state line says "All hooking is off" / "Per-game settings decide" — it is `hooking.kill_switch`, the
|
||||
> gate's fourth input (`CaptureSession` consults it at every 30 s re-scan, so a running measured session stops at
|
||||
> its next scan; nothing else needs pushing); the hook-enabled list is `games.hook_enabled` as the ledger has it,
|
||||
@@ -476,14 +731,16 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> `19_SAFETY_AND_ANTICHEAT.md` at the public repository in the user's browser (nothing is fetched).
|
||||
> **Recording:** minimum session length, sensor interval and raw-series retention as `ui:NumberBox`es bounded by
|
||||
> the registry; a value outside the range is refused in place (the previous value comes back, a warning names the
|
||||
> range, nothing is written); background capture as a toggle with the honest sentence (recorded, measured only if
|
||||
> hook-enabled and not Vulkan). **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above
|
||||
> range, nothing is written); ~~background capture as a toggle with the honest sentence (recorded, measured only if
|
||||
> hook-enabled and not Vulkan)~~ *(removed in beta.12, 2026-10-04: the toggle wrote `capture.background`, which no Agent
|
||||
> code read, so turning it off recorded every game anyway; with no way to start a game from the App, "off" could only
|
||||
> have meant recording nothing. The key is reserved — `06_DATA_MODEL` §Settings registry)*. **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above
|
||||
> (not required by any tier; unlocks CPU temperature through PawnIO and attaching to elevated games); the logon
|
||||
> task row says the scheduled task arrives with the tray build. **Window:** "Start FrameLedger with Windows" is
|
||||
> `Infrastructure.Startup.RunAtLogon` — this user's `HKCU\…\Run` value, quoted executable path, never HKLM —
|
||||
> and the Run entry is the truth the toggle loads from; "Minimize to tray on close" is stored now and honoured
|
||||
> when the tray exists. **Privacy:** ~~`privacy.online_metadata`, off by default, with the network sentence~~ — the card is not shown since 2026-09-16 (no code makes the request; the setting stays reserved).
|
||||
> **Updates:** `update.channel` is read by PR-5's updater (beta = GitHub pre-releases), and `update.auto_check` — the startup check, on by default — sits beside it. **Logging:** `log.debug` moves this app's `LoggingLevelSwitch` at
|
||||
> **Updates:** `update.channel` is read by PR-5's updater (beta = GitHub pre-releases; since beta.14 *Automatic (Beta)* or *(Stable)* first, the default, following the running copy — D47), and `update.auto_check` — the startup check, on by default — sits beside it. **Logging:** `log.debug` moves this app's `LoggingLevelSwitch` at
|
||||
> once; the Agent has no reader for the key yet, and the row says so. **Legal:** reopen is a "not yet" line
|
||||
> until PR-9's gate exists. ~~Register/Unregister the layer, Register/Repair/Remove the task~~ — PR-8b, with the
|
||||
> Agent flags they need. Tests: `SettingsViewModelTests` (seven cases), `RunAtLogonTests` (Infrastructure, under
|
||||
@@ -520,7 +777,7 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> is gone. **Refresh** shows only while a row is *Checking…*, the one time it can change anything.
|
||||
|
||||
### First-run flow
|
||||
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
|
||||
1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept. **Since beta.12 (D45) Accept covers three** — the EULA, the Disclaimer, the Privacy Policy; the GPL is listed as *your licence*, with a line saying it needs no acceptance (GPLv3 §9), and gets no `legal_acceptance` row (`06_DATA_MODEL`). **Rendered since beta.12** (§Menu, *Documents are rendered*): the Markdown texts drawn, the GPL as written; a link from one document to another the gate shows opens it in the gate; *View on GitHub* opens the document at this build's source, through `IUrlOpener`.
|
||||
2. Agent setup: runs **unelevated by default** — a short, honest paragraph explains that elevation is optional and unlocks CPU temperature and elevated-game attach. ~~and the Tier-2 ETW fallback. It must be explicit that **without elevation there is no Tier 2**~~ — **struck 2026-08-28: no tier needs elevation, so there is nothing to warn about here.** Capability check results shown afterwards. ~~with Tier-2 availability listed as its own badge~~ — there is no availability to report.
|
||||
3. Hooking explainer: what Tier 1 vs Tier 2 means — **and it must be explicit that Tier 2 measures nothing**, because the honest version of this screen is the one where a user who declines knows what they are declining — and that hooking stays off until enabled per game.
|
||||
4. Optional library import.
|
||||
@@ -531,16 +788,17 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> in read-only mode. **(1) The gate:** the four documents ride in the assembly (`LegalDocuments`: `legal/EULA.md`,
|
||||
> the root `LICENSE` as the GPLv3 text, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md`, embedded at build so the
|
||||
> App shows the text this build was reviewed with; HTML authoring comments stripped; `{{RELEASE_DATE}}` left for
|
||||
> `release.yml`), a list on the left, the text in a read-only box, "View on GitHub" per document, **one Accept**
|
||||
> that writes four `legal_acceptance` rows with each document's own `**Version:**` line (`GPL-3.0-only` for the
|
||||
> licence), and Decline, which ends the host — the shell never appears. Closing the window without deciding is a
|
||||
> `release.yml`), a list on the left, the text in a read-only box (~~raw Markdown~~ rendered since beta.12), "View on GitHub" per document, **one Accept**
|
||||
> that writes ~~four~~ three `legal_acceptance` rows with each document's own `**Version:**` line ~~(`GPL-3.0-only` for the
|
||||
> licence)~~ *(corrected 2026-10-04: since beta.12, D45, the GPL is shown for information and gets no row; an older
|
||||
> `gpl` row is left as written)*, and Decline, which ends the host — the shell never appears. Closing the window without deciding is a
|
||||
> decline. **(2) Agent setup:** the honest paragraph (unelevated by default; elevation optional, unlocks CPU
|
||||
> temperature and elevated-game attach, required by no tier) and the facts from `HelloAck` as they arrive —
|
||||
> state, version, telemetry source, overlay build, CPU temperature, elevated — N/A until the Agent answers.
|
||||
> **(3) The explainer:** the consent dialog's own reviewed Tier 1 / Tier 2 paragraphs (`Safety_Consent_Hooked` /
|
||||
> `_NotHooked`, so the two screens cannot drift), that hooking stays off until enabled per game, and that the
|
||||
> Disclaimer states the risk. **(4)** ~~the import placeholder (P4)~~ **since P4 PR-4 (2026-09-14) a real pointer: the stores' libraries are imported from File ▸ Import library… once inside, every row hooking off** (the step itself stays text — the review dialog needs the shell's dialog host, which the first-run window has not). D8 unchanged: the gate is not a consent
|
||||
> precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = four
|
||||
> precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = ~~four~~ three
|
||||
> rows at the documents' versions, a moved version re-shows only that document, decline/close write nothing,
|
||||
> read-only records nothing, the Agent facts), the two steps rendered in `PagesLoadTests`.
|
||||
>
|
||||
@@ -559,6 +817,12 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
- Keyboard: ~~NavigationView items Ctrl+1…5; grids fully navigable; Esc closes flyouts/dialogs~~ — §Accessibility below, since P4 PR-8 (2026-09-15); this bullet named three behaviours and none of them was built or checked.
|
||||
- No blocking dialogs during capture; errors surface as InfoBars/tray toasts.
|
||||
- Charts and stat numbers use culture-aware formatting per active UI culture (09); colors only from theme resources or the per-theme chart palette (16 §ScottPlot).
|
||||
- **The mouse wheel scrolls whatever is under the pointer (beta.14).** Every page scrolls itself
|
||||
(`ScrollViewer.CanContentScroll="False"` on the `Page` — `16_WPFUI_SYNTAX` §Gotchas: until beta.14 the wheel scrolled
|
||||
nothing on five pages, and the Logs tail did not follow the newest line); a scroller nested in a dialog hands the wheel
|
||||
on at its ends (`ui:PassiveScrollViewer`); over a chart a plain wheel scrolls the page and **Ctrl+wheel zooms the chart**
|
||||
(`Charts/ChartWheel`, every plot through `ChartTheme.Attach`) — drag still pans and double-click still resets, as
|
||||
ScottPlot does. The import checklist scrolls inside its list and nowhere else, so its intro and its count stay put.
|
||||
|
||||
## Accessibility
|
||||
|
||||
@@ -576,7 +840,8 @@ the requirement was one bullet under §UX rules, and nothing checked it.
|
||||
| **Arrows, Home/End, Page Up/Down** | Move within a `DataGrid` (Sessions, Compare picker, Import checklist) | `DataGrid` defaults |
|
||||
| **Esc** | Closes the open `ContentDialog` or `MessageBox` with no result — the same as its Close/Cancel button | `DialogKeyboard`, one class handler per dialog type registered at start-up |
|
||||
|
||||
**Esc is the Close button, never the primary one.** On the consent dialog (FR-2.1) that is "Keep it off": nothing is
|
||||
**Esc is the Close button, never the primary one.** On the consent dialog (FR-2.1) that is ~~"Keep it off"~~ "Keep hooking
|
||||
off" *(the button's text, corrected 2026-10-07)*: nothing is
|
||||
stamped. A dialog that offers no Close button is not dismissed by Esc, and the Legal Gate (FR-11) is a window of its own
|
||||
(`FirstRunWindow`) with explicit Decline and Accept, on which Esc does nothing. WPF UI 4.3.0 handles no key in
|
||||
either dialog type (its `ContentDialog.cs` and `MessageBox.cs` at tag 4.3.0 have no key handler — read 2026-09-15),
|
||||
@@ -587,8 +852,9 @@ which is why the handler is ours.
|
||||
- Every interactive control that shows no text of its own carries `AutomationProperties.Name` from `.resx` — the
|
||||
toggles and choice boxes on Settings, the hooking switch on a game's page, and the icon-only close button in the
|
||||
`InfoBar` template. A control *with* visible text needs nothing: its text is its name.
|
||||
- `PagesLoadTests`-style scan (`AccessibilityTests.EveryTextlessControlHasAName`): every `Button`, `ToggleSwitch`,
|
||||
`ToggleButton`, `CheckBox`, `ComboBox` and `HyperlinkButton` in the App's XAML either has content or a name. A new
|
||||
- `PagesLoadTests`-style scan (`AccessibilityTests.~~EveryTextlessControlHasAName~~ EveryInputThatShowsNoTextHasAnAutomationName`
|
||||
— corrected 2026-10-04): every `Button`, `ToggleButton`, `ToggleSwitch`, `CheckBox`, `RadioButton`, `ComboBox`,
|
||||
`TextBox`, `NumberBox`, `PasswordBox`, `Slider` and `HyperlinkButton` in the App's XAML either has content or a name. A new
|
||||
unnamed one is red.
|
||||
- Status lines that change after an action (the Database maintenance result) are `AutomationProperties.LiveSetting="Polite"`.
|
||||
|
||||
@@ -625,6 +891,45 @@ palette per theme, chosen with the theme).
|
||||
> primary text, ≈ 12:1) but **clipping** — the pill sat in a star column with no trimming, so a sentence-length
|
||||
> qualifier overflowed the row. The qualifier text trims with an ellipsis at 260 px (the readout's tooltip carries the
|
||||
> full sentence), and the row's readout column is sized to content with the game's name trimming first.
|
||||
>
|
||||
> **A third hole, closed 2026-10-05 (beta.14; the owner's screenshot of File ▸ Import library in the dark theme: every
|
||||
> row white, its text invisible, each tick box a sliver).** A style `BasedOn="{StaticResource {x:Type DataGridRow}}"`,
|
||||
> added in beta.11 to dim the rows already in the library: WPF UI 4.3.0 keys its row style `DefaultDataGridRowStyle`
|
||||
> and defines no implicit one, so the lookup fell through to Aero2's row and its `SystemColors.WindowBrush` — a white no
|
||||
> theme reaches, under the dark theme's white text. No `#` in our XAML, no palette badge: neither check above could see
|
||||
> it, and light-theme rows read fine. The tick boxes were WPF UI's `CheckBox` (`MinWidth` 120, padding 11) in a 40 px
|
||||
> column. Held three ways: `AccessibilityTests.NoStyleIsBasedOnAnImplicitStyleTheThemeDoesNotDefine` (every `BasedOn`
|
||||
> type has a style in the App's dictionaries), `ImportReviewRenderTests` (the rendered dialog, both themes: every cell's
|
||||
> text against the composited colour painted under it ≥ 4.5:1, each ticked box drawn whole), and
|
||||
> `AccessibilityTests.NoDataGridCheckBoxColumn` (Compare's checkbox column drew an Aero2 box). Each went red on the
|
||||
> unfixed XAML before it went green.
|
||||
>
|
||||
> **A fourth hole, closed 2026-10-07 (beta.17; the owner's screenshots of Settings after a theme switch: its descriptions
|
||||
> light grey on white in Light, dark grey on dark in Dark).** Every check above measures a theme as a surface is *made*
|
||||
> under it; a switch while the surface is on screen is a different question. WPF UI 4.3.0's `ui:TextBlock
|
||||
> Appearance="Secondary|Tertiary"` — 129 texts in 20 files, nearly every description and caption — looks its brush up
|
||||
> once and keeps it (`16_WPFUI_SYNTAX` §Gotchas), so the page on screen during a switch kept the old theme's muted text:
|
||||
> Settings above all, where the theme is chosen. Pages are made again on each navigation, which is why only the page in
|
||||
> view showed it. Those texts take the `SecondaryText` / `TertiaryText` styles now. Held two ways:
|
||||
> `ContrastTests.NoTextBlockTakesItsColourFromAppearance` (no `Appearance` on a TextBlock in any form, nor its code form),
|
||||
> and `PagesLoadTests.EveryTextFollowsAThemeSwitch` (every page, the first run, About, the user guide, a session's
|
||||
> summary, every dialog's content and the safety InfoBar, made under one theme, switched, and compared text by text with
|
||||
> the same surface made fresh under the other — both ways). Both went red on the unfixed XAML, the second with 146 stale
|
||||
> texts each way, before they went green.
|
||||
>
|
||||
> **A fifth hole, closed 2026-10-07 (beta.18; the owner's screenshots of beta.17 in the dark theme: every page's title and
|
||||
> section headings near-black on the dark window — beta.16's screenshot shows it too).** This text had no colour of ours,
|
||||
> because it had none. A page is shown in WPF UI's `NavigationViewContentPresenter`, a `Frame`, and a Frame passes no
|
||||
> inherited value into its page (`InheritanceBehavior.SkipToAppNow`), so a text that sets no colour falls to the TextBlock
|
||||
> default, which WPF UI 4.3.0 makes black (`16_WPFUI_SYNTAX` §Gotchas). Cards, grids and controls set their own; the bare
|
||||
> titles and headings did not: 19 texts on the six pages at 1.29:1. Every check above laid a page out straight in a
|
||||
> window, whose text colour the page then inherited — a page the App never draws — and a page on screen during a theme
|
||||
> switch did take the window's colour, while each navigation makes a new one that does not, so it came and went. Every
|
||||
> page sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"` on its root. Held two ways:
|
||||
> `AccessibilityTests.EveryPageSetsItsOwnTextColour`, and `PagesLoadTests.EveryTextIsReadableInBothThemes` — every
|
||||
> surface hosted as the App hosts it, a page in the presenter, and every text that shows ≥ 3:1 over the colour painted
|
||||
> under it, in both themes. `EveryTextFollowsAThemeSwitch` hosts its pages in the presenter too since, and went red with
|
||||
> them: a page made after a switch stayed black. All three went red on the unfixed XAML before they went green.
|
||||
|
||||
### DPI
|
||||
|
||||
|
||||
+18
-4
@@ -2,6 +2,9 @@
|
||||
|
||||
Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as the rest of the poli0981 portfolio.
|
||||
|
||||
> **The user guide is English (beta.12, owner decision D44)**, like the legal documents: `guide/` is Markdown the App
|
||||
> embeds and renders, not `.resx` text. The UI around it — the menu item, the window's title — is translated.
|
||||
|
||||
> **Both string families are given the UI culture explicitly (2026-09-21).** `App.ApplyCulture` sets `Strings.Culture`
|
||||
> AND `FrameLedger.Shared.Strings.Culture`. The second was missing: the safety family fell back to the thread's
|
||||
> `CurrentUICulture`, and a culture set inside the App's async start flows with that async context, not to the
|
||||
@@ -11,10 +14,16 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
|
||||
## Mechanics
|
||||
|
||||
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` for error codes). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
|
||||
- XAML binding via `{x:Static res:Strings.Key}` plus a `LocalizeExtension` for the few dynamic cases.
|
||||
- One `Strings.resx` (+ `Strings.vi.resx`, `Strings.ja.resx`) per assembly that has user-visible text (`App`, `Shared` ~~for error codes~~ for the safety family, the `Safety_*` keys — corrected 2026-10-04). Access through a generated strongly-typed class; **no string literals in XAML/C# for user-visible text** (analyzer TODO: Meziantou MA0011/manual review in PR checklist). **As built (P3 PR-2, 2026-09-13):** the class is `Strings.Designer.cs`, written by `tools/resx-gen.ps1 -Resx <file>` and **committed** — not the SDK's `ResXFileCodeGenerator`, which the SDK-style WPF project does not run — with `Culture`, `ResourceManager`, `Keys`, and one property per key; the audit below fails when it is stale. The first family is `src/FrameLedger.App/Strings.resx` (65 keys); `Shared`'s arrives with PR-4's `Safety_*` text, because an empty family is what the audit refuses.
|
||||
- XAML binding via `{x:Static res:Strings.Key}` ~~plus a `LocalizeExtension` for the few dynamic cases~~ *(corrected 2026-10-04: no `LocalizeExtension` exists; text that varies is composed in the view model from `Strings.*`)*.
|
||||
- **Runtime switching:** setting change → set `CultureInfo.CurrentUICulture` + `Thread` defaults → re-create the main window shell (cheap; state preserved via VM). Persist in `settings`.
|
||||
- `SatelliteResourceLanguages` = `en;vi;ja` in the App csproj to keep publish size down.
|
||||
**Two kinds of text did not follow, until beta.15:** a list of choices built once in a static (Settings' themes and update
|
||||
channels, the Logs page's two lists, the Games page's sort order — `x:Static` read the list built in the language the
|
||||
App started in), and the singletons that outlive the rebuilt window (the tray's menu, the title bar's Agent pill and the
|
||||
update banner). The lists are per page now, bound through the view model; the singletons implement
|
||||
`ILanguageFollower`, which `ShellHost.Rebuild` calls once the new window is up. `LanguageFollowingTests` refuses a new
|
||||
static list of labelled choices — the language list, each language in its own words, is the one exception.
|
||||
- `SatelliteResourceLanguages` = `en;vi;ja` in ~~the App csproj~~ `Directory.Build.props` (corrected 2026-10-04) to keep publish size down.
|
||||
|
||||
## Key conventions
|
||||
|
||||
@@ -31,7 +40,7 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
|
||||
- `en` written first, is authoritative.
|
||||
- `vi` authored by the maintainer.
|
||||
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; the About dialog credits reviewers.
|
||||
- `ja` machine-drafted, each entry marked with `<comment>review</comment>` until reviewed; ~~the About dialog credits reviewers~~ *(corrected 2026-10-04: no screen credits reviewers yet, and no `ja` entry has been reviewed — owner-only)*.
|
||||
- CI check (`tools/resx-audit`): every key present in all three files; ~~missing → build warning list artifact~~ **missing is RED (2026-09-13)**: `tools/resx-audit.ps1` exists since P3 PR-2 as `build.ps1` step 15, self-test first (11 fixture cases, at least four must go red) then the live pass over every `Strings.resx` under `src/`. Per family it requires C#-identifier keys with non-empty neutral values, **exactly** the neutral key set in `vi` and `ja` (a missing key would fall back to English silently; an extra one is dead text), the `Safety_*` rule below, and a current `Strings.Designer.cs`. A tree with no family is red, not green — the gate must not be vacuous.
|
||||
|
||||
## Glossary (fixed translations)
|
||||
@@ -52,6 +61,11 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
| Anti-cheat | Anti-cheat (giữ nguyên) | アンチチート |
|
||||
| Capture tier | Mức thu thập | 計測ティア |
|
||||
| Measured / Supports | Đo được / Hỗ trợ | 実測 / 対応 |
|
||||
| VRAM / RAM (beta.12) | VRAM / RAM (giữ nguyên) | VRAM / RAM |
|
||||
| Dedicated / Shared GPU memory | Bộ nhớ GPU chuyên dụng / dùng chung | 専用 / 共有 GPU メモリ |
|
||||
| Private working set / Working set / Commit | giữ nguyên | プライベート ワーキング セット / ワーキング セット / コミット |
|
||||
| this game / whole graphics card / whole PC | game này / cả card đồ họa / cả máy | このゲーム / グラフィックス カード全体 / PC 全体 |
|
||||
| Median / Mean / Peak | Trung vị / Trung bình / Đỉnh | 中央値 / 平均 / ピーク |
|
||||
|
||||
Technical benchmark vocabulary stays in English across all locales where the community convention is English (1% Low, stutter, present mode, frame pacing).
|
||||
|
||||
|
||||
@@ -3,9 +3,19 @@
|
||||
## Serilog configuration
|
||||
|
||||
- Sinks: rolling file per process — `logs/ui-.log`, `logs/agent-.log` (`rollingInterval: Day`, `retainedFileCountLimit: 7`, `fileSizeLimitBytes: 10 MB`, `rollOnFileSizeLimit: true`). Console sink in DEBUG builds. *(`ui-.log` is written since 2026-09-13, P3 PR-2, with `Process=ui` enriched and every unhandled path — Dispatcher, AppDomain, unobserved task — logged as Fatal/Error; ~~the crash dialog and minidump of §Crash handling are still P4's~~ — built 2026-09-15, P4 PR-9, §Crash handling's note.)*
|
||||
- *(beta.15, D52: an App started with `--data-dir <copy>` — a viewer — writes `ui-.log` and its crash dumps under the
|
||||
copy, never under `%LOCALAPPDATA%\FrameLedger`; its first lines name the folder and say it is a viewer.)*
|
||||
- Minimum level `Information` (`Debug` toggle in Settings → applies live via `LoggingLevelSwitch`).
|
||||
- Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).
|
||||
- ~~Enrichers: process name, version, `SessionGuid` and `GamePid` scoped properties during capture (`LogContext.PushProperty`).~~
|
||||
- Template: `[{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}`.
|
||||
|
||||
> **Corrected 2026-10-04 — the four lines above are `ui-.log`'s configuration, not both processes'.** `agent-.log`
|
||||
> (`FrameLedger.Agent/Program.cs`, since 2026-09-10) is daily with **14** files kept and no size cap, writes Serilog's
|
||||
> **default** template — `2026-10-04 09:15:02.123 +07:00 [INF] …`, a date first — and its level is fixed at
|
||||
> Information with `Microsoft.*` at Warning: `log.debug` is the App's alone. Neither process has a console sink, and no
|
||||
> enricher exists beyond the App's `Process=ui`. The Logs page reads both shapes since beta.12 — until then its level
|
||||
> filter recognised only the App's `[HH:mm:ss.fff LVL]` prefix, so Warning and Error showed no Agent line at all
|
||||
> (`LogTail.LevelOf`, `LogTailTests.TheAgentsTemplateIsReadToo`).
|
||||
- **Never log:** full user paths outside `%LOCALAPPDATA%\FrameLedger` (redact to `<user>`), machine name, any exe arguments of games. ~~A `RedactingEnricher` enforces the path rule.~~ *(No such enricher was ever written: found 2026-09-15, checking `legal/PRIVACY_POLICY.md` §3's "logs are redacted (user directory paths removed) before bundling" against the bundle, which copied the logs verbatim. An enricher could not have kept the rule anyway: exception text and the Overlay's native log never pass through one, and the data directory itself sits under the user's profile, so every run logs a user name. The rule is enforced where a log leaves the machine instead: `App/Services/LogRedactor` over every log copy in the bug bundle, §Bug report flow step 2. The files in `logs\` keep their full paths; they leave the PC only if the user copies them.)*
|
||||
- Capture hot path logs nothing per-frame; counters summarized at finalize.
|
||||
|
||||
@@ -151,7 +161,7 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
|
||||
|
||||
## Diagnostics extras
|
||||
|
||||
- `Tools → Agent status…` shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder) + last 20 Agent log lines.
|
||||
- `Tools → Agent status…` ~~shows the `HelloAck` capability set (telemetry source, overlay build id, Vulkan layer~~ — ~~tier availability~~, which meant "is the ETW fallback reachable" and has no meaning under a two-rung ladder ~~) + last 20 Agent log lines~~. *(Corrected 2026-10-04: it opens the Dashboard's Agent card — state, version, telemetry source, overlay build id, elevated, running sessions. The Vulkan layer state is on Settings ▸ Capture and the Agent's log on the Logs page.)*
|
||||
- **Never include a game's own logs, saves, or config files** in a bug bundle, even when a crash looks game-related. We ship our logs only.
|
||||
- `--diag` CLI flag on the App prints environment + capability report to stdout (support requests).
|
||||
|
||||
@@ -162,8 +172,9 @@ Tails the active files (shared read), level filter, text search, pause autoscrol
|
||||
> **Built 2026-09-14 (P3 PR-8a).** `App.OnStartup` sees `--diag` and runs `DiagAsync` instead of the host: no
|
||||
> window, no Agent, the ledger opened read-only for its schema version and the settings, then
|
||||
> `Services/DiagReport.Build` (app version, OS and bitness, runtime, locale, elevation, data and logs
|
||||
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, every
|
||||
> registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
|
||||
> directories, ledger schema or "could not open", whether `FrameLedger.Agent.exe` is beside the App, since
|
||||
> 2026-09-21 the machine as a session's hardware snapshot records it — CPU, GPU, driver, RAM, display — added to this
|
||||
> list 2026-10-04, and every registry key's effective value) written to `logs/diag-<yyyyMMdd-HHmmss>.txt` **and** to stdout — the App is
|
||||
> a WinExe with no console of its own, so stdout carries the report only when the caller attached one or piped
|
||||
> it (`FrameLedger.exe --diag | more` works; a double-click leaves the file). Exit 0, or 1 with a Fatal line in
|
||||
> `ui-*.log`. The Agent's `--diag` stays on its `NotImplementedFlags` list — 10_LOGGING names the flag as the
|
||||
|
||||
+65
-10
@@ -1,14 +1,17 @@
|
||||
# 11 — Updater
|
||||
|
||||
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. Stable channel only in v1.
|
||||
Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledger`. ~~Stable channel only in v1.~~ *(Corrected 2026-10-04: two channels since P4 PR-5 — `update.channel`, ~~stable by default~~ or beta, which adds pre-releases. Every release so far is a pre-release; see §Built, Channels.)* *(Corrected 2026-10-05: the default is `auto` since beta.14, which follows the running copy — §The update audit, beta.14.)*
|
||||
|
||||
## Flow
|
||||
|
||||
- **Startup silent check** (if enabled): `UpdateManager.CheckForUpdatesAsync()` 5 s after UI idle. Offline/any failure → log `Information`, no dialog (NFR-10). Update found → non-blocking toast "Update vX.Y.Z available" → Downloads in background → "Restart to update" button (never auto-restart; the user may be mid-capture — if a capture is active, defer the prompt until session end).
|
||||
- **Manual check** (Help → Check for updates): progress dialog; all failures produce the mapped dialog below.
|
||||
- **A viewer never updates** (beta.15, D52): an App started with `--data-dir <copy>` registers neither Velopack nor the
|
||||
startup check (`Services.MachineFacingServices` gives it `ViewerUpdateClient`, which answers "not installed"), and
|
||||
Help → Check for updates and the automatic-check switch are disabled — an update replaces this PC's installed copy.
|
||||
- **Never apply an update while a game is hooked** (FR-12): the Overlay DLL on disk must not change under a running game, and a mid-session swap would invalidate the ring layout handshake. If a capture is active, defer the prompt and the apply until the session ends.
|
||||
- Apply: `WaitExitThenApplyUpdates` on restart. Agent is stopped via `Shutdown` before applying and the scheduled task action path is re-validated after update (Velopack keeps a stable `current` path, but verify in P4 and re-register task if the action path changed).
|
||||
- Release notes (GitHub release body, Markdown) rendered in the update dialog.
|
||||
- Release notes (GitHub release body, Markdown) rendered in the update dialog. ~~(shown as plain text until beta.12 — §Flow and §Limits below said so)~~ **Rendered since beta.12** by `Controls/MarkdownView` (`08_UI` §Menu, *Documents are rendered*), relative links resolved against `CHANGELOG.md` at this build's source.
|
||||
|
||||
## Error mapping (FR-12)
|
||||
|
||||
@@ -21,7 +24,7 @@ Velopack, feeding from GitHub Releases of `https://github.com/poli0981/frameledg
|
||||
| Package hash mismatch | `Update_Err_Corrupt` | Auto-retry once, then dialog |
|
||||
| Unknown | `Update_Err_Unknown` + exception logged | "Report a bug" shortcut |
|
||||
|
||||
Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.
|
||||
~~Detection-rules updates share this client, but the **`anticheat` block is fetched and applied on its own schedule regardless of the user's rules-update preference** (`05_DETECTION` FR-7.3) — a user who turned off rules updates must still receive new anti-cheat entries.~~ *(Corrected 2026-10-04: there is no rules fetch and no rules-update preference. Tools ▸ Update detection rules re-reads the copy seeded from the install (`07_IPC`); FR-7.3 is unmet (`20_OPEN_QUESTIONS` §S20). The sentence is what a fetch must do once built.)*
|
||||
|
||||
All update HTTP goes through one `GitHubHttpClient` (also used by rules updates) with: UA `FrameLedger/{version}`, 10 s timeout, ETag cache in `settings`, single retry with jitter for transient failures.
|
||||
|
||||
@@ -29,7 +32,12 @@ All update HTTP goes through one `GitHubHttpClient` (also used by rules updates)
|
||||
|
||||
Binaries are not code-signed (project policy). Consequences and mitigations, documented in README and the update dialog footer:
|
||||
- SmartScreen warning on first run of a new version — expected; SHA-256 checksums (`SHA256SUMS.txt`) published with every release; CI prints them into release notes.
|
||||
- Velopack delta packages reduce download size; full package fallback automatic.
|
||||
- ~~Velopack delta packages reduce download size; full package fallback automatic.~~ *(Corrected 2026-10-04: no delta has been published — `release.yml` never puts the previous release in `out/release` before `vpk pack`, so every update downloads the full package; a delta needs a `vpk download github` step first.)* **Built in beta.13:**
|
||||
`release.yml` downloads the previous release into `out/release` before `vpk pack`, so a release carries
|
||||
`FrameLedger.App-<version>-delta.nupkg` beside the full package; the previous full package is moved out (neither uploaded
|
||||
nor checksummed) and the feed lists this build alone, as `vpk upload github` would write it. Velopack applies the delta
|
||||
when the installed copy is the previous release and falls back to the full package otherwise — `0.1.0-beta.13` is the
|
||||
first release with one, so beta.12 → beta.13 is the first update that can use it (owner-only: HANDOFF item 10).
|
||||
- Never bypass or suppress OS warnings programmatically.
|
||||
|
||||
## Versioning
|
||||
@@ -37,7 +45,7 @@ Binaries are not code-signed (project policy). Consequences and mitigations, doc
|
||||
SemVer `MAJOR.MINOR.PATCH`. Tag `vX.Y.Z` triggers the release workflow (13_CI_CD). `MAJOR` bumps for DB schema or IPC protocol breaks; migrations must cover every released `MAJOR-1` version.
|
||||
|
||||
> **Under `0.x` this rule is not applied, and every pre-release says so by shipping one anyway** (SemVer §4: a major version
|
||||
> zero is initial development). Schemas 0008–0015 and the shared-memory layout 4 (2026-09-27, beta.10) each shipped in a
|
||||
> zero is initial development). Schemas ~~0008–0015~~ 0008–0017 *(corrected 2026-10-04: 0016 shipped in beta.10 beside 0015, 0017 in beta.11; 0018 rides beta.12)* and the shared-memory layout 4 (2026-09-27, beta.10) each shipped in a
|
||||
> `0.1.0-beta.N`. What protects a user is not the number: the ledger migrates in place (`06_DATA_MODEL` §Migrations), and a
|
||||
> layout mismatch is refused at attach with "restart the game" (`07_IPC` §Protocol rules). The rule applies from `1.0.0`.
|
||||
|
||||
@@ -55,8 +63,8 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
window is off screen (`08_UI` §Notifications policy), and the shell's persistent InfoBar carries the download
|
||||
and the **Restart to update** button.
|
||||
- **Manual check:** Help ▸ Check for updates → `UpdateService.CheckInteractivelyAsync` and the dialogs in
|
||||
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, shown as text —
|
||||
no Markdown renderer is shipped), the unsigned-release footer, Download / Later; "up to date"; "not an
|
||||
`UpdatePrompts` (WPF-UI `MessageBox`): the offer with the release notes (the GitHub release body, ~~shown as text —
|
||||
no Markdown renderer is shipped~~ rendered since beta.12, at most 260 px tall and scrolling), the unsigned-release footer, Download / Later; "up to date"; "not an
|
||||
installed copy"; and the error table below. There is no progress *dialog*: progress is the banner's percent. A
|
||||
package that fails its checksum is downloaded once more before the Corrupt row is shown (the table's "auto-retry
|
||||
once").
|
||||
@@ -104,8 +112,55 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
empty token — measured on 1.2.0 by reflection, so the request identifies the product and nothing else. When the rules fetch is built
|
||||
(`05_DETECTION` FR-7.3, `20_OPEN_QUESTIONS` §S20 feed half) it needs a client of its own; this paragraph no
|
||||
longer claims the updater provides one.
|
||||
- Release notes are rendered as plain text, not Markdown.
|
||||
- ~~Release notes are rendered as plain text, not Markdown.~~ Corrected 2026-10-03: rendered since beta.12 (Markdig; HTML off, no image fetched).
|
||||
|
||||
## The update audit, beta.14 (owner request 2026-10-05: "check the update logic")
|
||||
|
||||
No failure had been reported; the audit read the flow above against Velopack 1.2.0 and the owner's own updater log
|
||||
(`%LOCALAPPDATA%\velopack\velopack_FrameLedger.App.log`, read-only) and found two defects that made the flow above
|
||||
partly fiction, and six smaller ones. Each is fixed in place:
|
||||
|
||||
- **A copy left on its defaults never found an update.** `update.channel` defaulted to `stable` while every release is a
|
||||
GitHub pre-release; the owner's log reads "No releases found" from the day their ledger (and its settings row) was reset.
|
||||
**Owner decision D47:** the default is `auto`, which follows the running copy — a pre-release asks for pre-releases, a
|
||||
release for releases (`Update/UpdateChannelPolicy`, SemVer's `-` before any `+`) — and a stored `stable` or `beta` is the
|
||||
user's choice and wins. Settings shows *Automatic (Beta)* or *(Stable)* first. Only an explicit selection ever wrote the
|
||||
row (`SettingsViewModel.Persist` is guarded while loading), so existing copies with no row move to `auto`.
|
||||
- **Velopack applied a downloaded update at the next start, behind FR-12.** `VelopackApp` applies a package waiting in
|
||||
the install folder on startup unless told not to (`SetAutoApplyOnStartup`, ON by default), and the startup check
|
||||
downloads in the background — so the next start of `FrameLedger.exe` (the Start menu, the logon Run value, a second
|
||||
click, `--diag`) applied it inside `VelopackApp.Run()`, before the single-instance claim, before FR-12 could ask
|
||||
whether a session runs, and before the Agent was asked to stop; its updater killed the Agent instead (the owner's log:
|
||||
"Auto apply is true, so restarting to apply update…", then "Killing process: …FrameLedger.Agent.exe"). Off now
|
||||
(`VelopackHooks`, pinned by `VelopackHooksTests` through the builder's private fields); a package an earlier run left
|
||||
is adopted at start — `UpdateService.AdoptPending`, from `UpdateManager.UpdatePendingRestart`, no feed request — and is
|
||||
Ready or Deferred like any other.
|
||||
- **An update Velopack starts itself** (the installer run over an installed copy) asks the Agent to stop first, as the
|
||||
uninstaller does (`OnBeforeUpdateFastCallback`, 15 s budget, a line in `logs\update.log`). The hook runs in the
|
||||
version being replaced, so it first works for the update after beta.14.
|
||||
- **The apply waits while a game still has the Overlay loaded** from the install folder (`Update/PayloadInUse`: a mapped
|
||||
image refuses an exclusive write — a file-system question, no process opened). The Overlay is never unloaded from a
|
||||
live game (`17_HOOK_ENGINE`), so after a mid-game stop the swap would fail half way after the App had quit. Asked before
|
||||
the Agent is stopped; the strip names the file.
|
||||
- **An Agent waiting on the administrator prompt** (the logon task's, the admin mode) holds only its elevation marker, not
|
||||
the instance lock; the apply now waits for either (`UpdateService.AgentHolds`).
|
||||
- **The stop budget is the Agent's own shutdown grace and five seconds** (`IpcProtocol.AgentShutdownGrace`, 15 s, which
|
||||
the Agent's host now reads too): the App waited 10 s for an Agent that took up to 15 to finalize its sessions.
|
||||
- **The offer says the download Velopack will make:** the deltas from the installed version when the feed has them
|
||||
(`UpdateInfo.DeltasToTarget`; 1.6 MB for beta.12 → beta.13) and the full package as the fallback — it said ~102 MB.
|
||||
Velopack's own lines are in the App's log since beta.14 (`velopack: …`, `VelopackSerilogLogger`), so whether a delta
|
||||
or the full package came is in the bug report too.
|
||||
- **Smaller:** an `IOException` is "offline" only from the network (`HttpIOException`, a socket error) — a full disk
|
||||
read as offline; the uninstaller removes the "Start FrameLedger with Windows" Run value, which named an executable it
|
||||
deletes.
|
||||
|
||||
**What none of this reaches:** a copy still on 0.1.0-beta.13 or older runs its own code for the update to beta.14 —
|
||||
stable by default, apply-at-start on. Its user chooses *Beta* in Settings ▸ Updates and updates with no game running
|
||||
(the beta.14 release notes say so); everything above holds from beta.14 on.
|
||||
|
||||
`UpdateServiceTests` (App.Tests/Update) cover the two skips, the channels, Deferred ↔ Ready, each error row, and
|
||||
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; a real feed has
|
||||
not been exercised — the first tag is the measurement (`13_CI_CD` §release.yml).
|
||||
the apply's three endings; `UpdateFailureMapperTests` the table; `UninstallHookTests` the hook; ~~a real feed has
|
||||
not been exercised — the first tag is the measurement~~ *(corrected 2026-10-04: the feed has existed since
|
||||
v0.1.0-beta.1, 2026-09-16, and every release since carries `releases.win.json`; whether an installed copy has updated
|
||||
through it is not recorded here)*
|
||||
(`13_CI_CD` §release.yml).
|
||||
+81
-19
@@ -5,7 +5,7 @@ Mixed toolchain: .NET 10 for managed projects, MSVC for the native layer.
|
||||
## Prerequisites
|
||||
|
||||
- Windows 11 (dev), **.NET 10 SDK**, **Visual Studio 2026** with: .NET desktop development, **Desktop development with C++** (MSVC v143+, Windows 11 SDK ≥ 10.0.22621), C++ ATL not required.
|
||||
- **Vulkan SDK** (for the layer + validation layers during development).
|
||||
- **Vulkan SDK** (~~for the layer +~~ validation layers during development, and to run `tools/vklayer-blastradius.ps1`) *(corrected 2026-10-04: the layer builds against the vendored `third_party/vulkan-headers`; CI installs no SDK)*.
|
||||
- CMake ≥ 3.28 (native projects use CMake; consumed by the solution via a build target — see below).
|
||||
- Optional: PawnIO for CPU-temperature testing; an NVIDIA GPU for the NVAPI/Reflex paths (dev machine: RTX 5080). AMD/Intel telemetry paths need no SDK — if you have such hardware, testing L1/L2 coverage there is valuable.
|
||||
- **No admin needed for normal development.** `FL_MOCK=1` is **specified but not implemented** — `grep -rn FL_MOCK src tests tools build.ps1` returns nothing (CLAUDE.md §Dev mode records the same, and this line contradicted it in the present tense until 2026-08-05). When it exists it runs the whole app with a synthetic source and zero injection. Until then the no-injection development path is `hook-harness`, which needs no admin either.
|
||||
@@ -23,8 +23,9 @@ Targets:
|
||||
- `FrameLedger.Overlay` → `FrameLedger.Overlay.dll`
|
||||
- `FrameLedger.VkLayer` → `FrameLedger.VkLayer.dll` + `VkLayer_FRAMELEDGER_overlay.json`
|
||||
- `FrameLedger.Injector` → **static lib only.** There is no `FrameLedger.Injector.exe` and none ships (`20_OPEN_QUESTIONS` §S9, decided 2026-08-02). A standalone `LoadLibraryW` injector that users can run is a path into a game process that the guard does not stand in front of — a bypass, and a bad look for a project whose position is "we refuse where we are not welcome". The Agent links the static lib; the guard owns the chokepoint inside it (§S13(b)), so there is no callable entry point that skips the gate. Manual testing uses `hook-harness`, never a real game (§Debugging).
|
||||
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other three shipped natives. ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
|
||||
- `FrameLedger.Overlay.Tests` → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
|
||||
- `FrameLedger.NvapiBridge` → `FrameLedger.NvapiBridge.dll` (**2026-09-10, P2 PR-E2**): the C ABI the Agent reaches NVAPI through (`18_GPU_VENDOR_APIS` §L3) and the **only shipped binary that links `nvapi64.lib`**. Read-only by construction, loaded by the Agent into **its own process** by absolute path through `/FrameLedger.NvapiBridge.targets`, and **never into a game** — its name carries none of the words the guard's §S18 heuristic scans for. `fl_native_flags` only, not the hostile-environment set. `versioninfo-check.ps1` requires its version block like the other ~~three~~ shipped natives (five in all since beta.12 — corrected 2026-10-04). ctest `fl_nvapi_bridge` (`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires `BRANCH: AVAILABLE` or `BRANCH: DEGRADED` in the output, so a bridge gutted to `return 0` is red on a runner without the driver too.
|
||||
- `FrameLedger.Guard` → `FrameLedger.Guard.dll` (the guard's C ABI over the Injector library, `src/native/FrameLedger.Injector/CMakeLists.txt`; loaded by the Agent) and `FrameLedger.ProcessStats` → `FrameLedger.ProcessStats.dll` (beta.12, D43: the game process's memory, read by the Agent from outside the game; probe `fl-probe-processstats`) *(both bullets added 2026-10-04; they were missing)*
|
||||
- ~~`FrameLedger.Overlay.Tests`~~ the ctest executables in `src/native/tests/` (`fl_ring_test`, `fl_guard_test`, `fl_vklayer_test`, … — corrected 2026-10-04: no target of that name has existed) → Catch2 unit tests (ring buffer, record layout, fault filter, seqlock) **and the guard's fail-closed matrix** (`14_TESTING` §Safety-guard tests) — the guard is native, so its tests are too
|
||||
- `hook-harness` → the dummy **D3D11 + D3D12** app, WARP + composition swapchain so it runs headless on CI (`17_HOOK_ENGINE` §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. ~~Vulkan and OpenGL modes to follow as those hooks land.~~ **`--vulkan --hold-presenting N` since 2026-09-06 (P1 item 3):** a real swapchain on a hidden window through the real loader, reached by `LoadLibraryW("vulkan-1.dll")` so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. **`--opengl --hold-presenting N` since the same day (P1 item 4):** a real context on a hidden window, `SwapBuffers`'d through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI.
|
||||
- `fl-probe-hookprofile` → build-profile probes for `/guard:cf` and `-D_HAS_EXCEPTIONS=0` (`20_OPEN_QUESTIONS` §H1/§H3)
|
||||
- `fl-probe-guard` → measures the Windows APIs the guard is built on, unelevated (`spike-notes.md` §1). Not the guard, and takes no injection rights.
|
||||
@@ -43,7 +44,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
|
||||
**No AMD or Intel GPU *telemetry* SDK is vendored.** Those vendors' sensors are covered by LibreHardwareMonitor and the DXGI/PDH baseline (`18_GPU_VENDOR_APIS`). A build that pulls in Intel IGCL or AMD ADLX material is a licensing regression, not a feature — CI greps for it. **The AMD FidelityFX ffx-api headers (MIT by exception, tag v2.3.0) ARE vendored since 2026-09-04**, for the Overlay's upscaler hook and for types only — `fl_fidelityfx_headers` above, `18_GPU_VENDOR_APIS` §AMD for the licence reading, and `license-check.ps1` §2d for the per-file gate. Intel's XeSS SDK failed the checklist and nothing of it is here.
|
||||
|
||||
**VERSIONINFO is mandatory** on `FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`: real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing.
|
||||
**VERSIONINFO is mandatory** on ~~`FrameLedger.Overlay.dll` and `FrameLedger.VkLayer.dll`~~ every shipped native — the five `tools/versioninfo-check.ps1` lists (corrected 2026-10-04): real `CompanyName`, `ProductName=FrameLedger`, `FileDescription`, version. Identifiability is a requirement (`19_SAFETY`), and a CI check fails the build if the resource block is missing. **Since beta.14 (D50) the managed binaries are held to the same** — §Version, *Identity*.
|
||||
|
||||
## Managed build & native integration
|
||||
|
||||
@@ -55,7 +56,7 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
> **`RuntimeIdentifier` is NOT set here, and this bullet claimed it was until 2026-08-06.** The props file's own comment explains why: forcing a RID onto class libraries pulls RID-specific assets into their restore for no benefit, so each executable sets it — `FrameLedger.App`, `FrameLedger.Agent` and now `FrameLedger.CaptureHost`, plus its test project, which needs the same RID to reference a RID'd exe. A new project copying this document rather than the props file would have inherited nothing.
|
||||
- Nullable enable, ImplicitUsings enable, `TreatWarningsAsErrors=true`, `AnalysisLevel=latest-all`, deterministic, `ContinuousIntegrationBuild` on CI.
|
||||
- `Directory.Packages.props`: central package management, all versions pinned (including `WPF-UI` = 4.3.0 exactly — `16_WPFUI_SYNTAX` §Version hygiene).
|
||||
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
|
||||
- **Native output reaches the managed side through `.targets` files imported by `FrameLedger.Agent`**, not through `FrameLedger.Infrastructure`: `/FrameLedger.Guard.targets` (the guard DLL), `/FrameLedger.Overlay.targets` (the payload, §S22), `/FrameLedger.Rules.targets` (the blocklist seed) and, since 2026-09-10, `/FrameLedger.NvapiBridge.targets` (the L3 bridge; it **warns rather than fails** when the DLL is absent, because a missing telemetry layer reports itself where a missing guard would be a safety hole), and since beta.12 `/FrameLedger.ProcessStats.targets` (the game-memory reader, D43; it also warns rather than fails — an absent reader reads N/A; added 2026-10-04). Ordering comes from `build.ps1`, which runs the native build first — **not** from the solution: `FrameLedger.slnx` contains no native project.
|
||||
|
||||
> **This bullet was wrong in four ways and is corrected 2026-08-04.** It named a copy of `FrameLedger.Injector.exe`, which §S9 closed and which line 25 above says does not exist, 24 lines earlier in the same document. It attributed the copying to a build target in `FrameLedger.Infrastructure.csproj`, which contains no `<Target>` at all. It said the copies happen there, when the guard DLL was deliberately moved out to a `.targets` file so it would stop flowing to every referencing project (§S18 blocker 3). And it credited the solution with an ordering the solution cannot express.
|
||||
- **Struct mirror check — ✅ built 2026-08-05.** `ShmLayoutMirrorTests` runs `tools/fl-layout-dump`, reads its JSON, and asserts size plus every field offset against the C# `[StructLayout]` mirrors in `FrameLedger.Shared` — in **both directions**, so a field on either side alone fails. It also asserts blittability, which offsets cannot see. The `struct-mirror` gate reads the run's `.trx` and fails when that test class did not execute, so deleting the test is red as well as breaking it. Struct drift between the two layers is the most dangerous silent bug in this architecture; the build now genuinely catches it.
|
||||
@@ -64,10 +65,24 @@ Compiler/linker flags (enforced in CMake, not per-target ad hoc): `/std:c++20 /M
|
||||
|
||||
## Debugging
|
||||
|
||||
Launch profiles:
|
||||
- **"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.
|
||||
- **"UI + Agent"** — both managed processes, real capture against `hook-harness`.
|
||||
- **"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.
|
||||
~~Launch profiles:~~
|
||||
- ~~**"UI + Mock"** — `FL_MOCK=1`, no Agent, no injection. Default for UI work.~~
|
||||
- ~~**"UI + Agent"** — both managed processes, real capture against `hook-harness`.~~
|
||||
- ~~**"Harness + Overlay"** — starts `hook-harness` under the debugger with the Overlay injected at launch; attach a second native debugger to step hook code.~~
|
||||
|
||||
*(Corrected 2026-10-04: none of these is committed, and "UI + Mock" needs `FL_MOCK`, which §Prerequisites says is not
|
||||
implemented. What exists: `FrameLedger.exe` starts `FrameLedger.Agent.exe --serve` beside itself. To capture against the
|
||||
harness, run `hook-harness.exe --real --hold-presenting N`, then the Agent's `--console --data-dir <scratch>` verbs
|
||||
`consent grant --exe` and `capture --exe`, as `AgentEndToEndTests` does — never against your own data folder.)*
|
||||
|
||||
**To look at real data with a build of your own (beta.15, D52): `FrameLedger.exe --data-dir <copy>`.** Make the copy with
|
||||
SQLite's online backup, which is consistent while the Agent writes — in Python,
|
||||
`sqlite3.connect("file:C:/Users/<you>/AppData/Local/FrameLedger/ledger.db?mode=ro", uri=True).backup(sqlite3.connect(r"<copy>\ledger.db"))`
|
||||
— or copy the whole folder with every FrameLedger process stopped
|
||||
(closing the App does not stop the Agent). The App opens the copy, migrating it if your build is newer, which is exactly
|
||||
why it must be a copy, and writes its log and crash dumps beside it. It is a viewer: no Agent is started or contacted and
|
||||
nothing on the PC is changed (`08_UI` §Shell). It refuses the profile's own folder however it is spelled, and a folder
|
||||
that does not exist.
|
||||
|
||||
**Toolchain gotchas, both hit on a real machine and both handled by `build.ps1`:**
|
||||
|
||||
@@ -164,6 +179,29 @@ two products claiming to be one.
|
||||
- `release.yml` refuses a tag whose numeric core is not the file's. Bumping the version is one edit to
|
||||
`VERSION`, in the same commit as the changelog section, before the tag.
|
||||
|
||||
**Identity (beta.14, D50).** Every binary names the product, says what it is and carries one copyright line. Until
|
||||
beta.14 only the native blocks did: the managed ones carried the SDK's defaults — the Agent's company and product read
|
||||
`FrameLedger.Agent`, each library's its own assembly name — and no copyright, and those blocks are what Explorer's
|
||||
*Properties ▸ Details* and Task Manager show (Task Manager lists the Agent by its file description).
|
||||
|
||||
| Field | Native (`src/native/CMakeLists.txt`) | Managed (`Directory.Build.props`, the two entry points' csproj) |
|
||||
|---|---|---|
|
||||
| CompanyName, ProductName | `FL_COMPANY_NAME`, `FL_PRODUCT_NAME` = `FrameLedger` | `Company`, `Product` = `FrameLedger` |
|
||||
| LegalCopyright | `FL_COPYRIGHT` | `Copyright` — the same line, word for word |
|
||||
| FileDescription | each target's `fl_add_version_resource` description | `AssemblyTitle`: `FrameLedger` (App), `FrameLedger Agent` (Agent); a library keeps its assembly name |
|
||||
| Comments | the identification sentence | `Description` — the same sentence for a library, a line of its own for each entry point |
|
||||
| FileVersion / ProductVersion | the numeric core, `x.y.z.0` | `x.y.z.0` / the full version (`-p:Version`, a pre-release's tag included) |
|
||||
| OriginalFilename | the file's own name | the assembly's (`FrameLedger.dll`) — the apphost `.exe` carries a copy of its assembly's block |
|
||||
|
||||
Also stamped on every assembly: `AssemblyMetadata("RepositoryUrl")` (the SDK, from `RepositoryUrl`; the App test holds
|
||||
it equal to `IssueLink.Repository`) and, when `release.yml` passes it, `FrameLedgerSourceRef` — the App csproj's alone
|
||||
until beta.14, now `Directory.Build.props`', and passed to both publishes. `tools/versioninfo-check.ps1` reads all of it
|
||||
from the BUILT binaries — the native five and, with `-ManagedDir`, the managed eight (`FrameLedger.exe`/`.dll`,
|
||||
`FrameLedger.Agent.exe`/`.dll`, Domain, Application, Infrastructure, Shared) — and is red when a copyright differs
|
||||
anywhere, when a managed `ProductVersion` is not `-ExpectedProductVersion` (required: a comparison with nothing passes
|
||||
everything), or when an apphost does not carry its assembly's block; its `-SelfTest` (ten cases, nine RED, each for the
|
||||
reason it names) runs first. `AssemblyIdentityTests` (App and Agent) pins the source against `FL_COPYRIGHT`.
|
||||
|
||||
The Velopack package version is the tag's (`vpk pack --packVersion`), and `UpdateManager.CurrentVersion` reads
|
||||
the installed package's manifest — not the assembly — which is why the two are made to agree here rather than
|
||||
assumed to.
|
||||
@@ -172,15 +210,20 @@ assumed to.
|
||||
|
||||
```
|
||||
cmake --build --preset x64-release
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -o out/app
|
||||
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
dotnet publish src/FrameLedger.App -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
|
||||
dotnet publish src/FrameLedger.Agent -c Release -r win-x64 --self-contained -p:PublishReadyToRun=true -p:FrameLedgerSourceRef={tag} -o out/app
|
||||
vpk download github --repoUrl https://github.com/poli0981/frameledger --channel win --pre --outputDir out/release # beta.13: the previous release, for a delta
|
||||
vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainExe FrameLedger.exe --packTitle FrameLedger --packAuthors FrameLedger --releaseNotes out/notes.md --outputDir out/release
|
||||
```
|
||||
|
||||
> **Run by `release.yml` since 2026-09-14 (P4 PR-5)** — `13_CI_CD` §release.yml carries the steps around it
|
||||
> (the version gate, `{{RELEASE_DATE}}`, the published-tree assertion, checksums, the release). Both publishes
|
||||
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
|
||||
> for six weeks.
|
||||
> for six weeks. **Since beta.12 the App also takes `-p:FrameLedgerSourceRef`** — the tag, or for a rehearsal the
|
||||
> commit — stamped as assembly metadata so its links into the repository open THIS version's documents
|
||||
> (`Services/RepositoryLinks`); a build without it links to `main`. **Since beta.14 the Agent takes it too**, because
|
||||
> `Directory.Build.props` stamps it on every assembly and both publishes build the same libraries into `out/app` (§Version,
|
||||
> *Identity*).
|
||||
>
|
||||
> **The package id is `FrameLedger.App`, and this line said `FrameLedger` until 2026-09-14 — which would have
|
||||
> deleted every user's ledger on uninstall.** Velopack installs into `%LOCALAPPDATA%\<packId>` and removes that
|
||||
@@ -215,7 +258,7 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
|
||||
|
||||
- No trimming (WPF + reflection), no NativeAOT (WPF unsupported), **no obfuscation** (GPLv3 policy, and `19_SAFETY` forbids making our binaries harder to identify).
|
||||
- `SatelliteResourceLanguages=en;vi;ja`. ~~Expected package ≈ 95–130 MB self-contained.~~ **Measured 2026-09-14 (P4 PR-5): the published tree is 250 MB in 362 files** (App + Agent, self-contained, ReadyToRun roughly doubles the IL). `vpk pack` 1.2.0 over that tree, run by hand the same day with the workflow's arguments: `FrameLedger.App-win-Setup.exe` **104 MB**, the full `.nupkg` and the portable zip 100 MB each, plus `releases.win.json` / `RELEASES` / `assets.win.json`; vpk's own pre-process step verified `VelopackApp.Run()` in `FrameLedger.App.Program::Main()`. **From the hosted runner on the first tag (2026-09-16, `v0.1.0-beta.1`):** the tree 252 MB, `Setup.exe` 110 MB, the nupkg and the zip 105 MB — the same shape, a few MB heavier for two more days of code.
|
||||
- Velopack hooks (**built 2026-09-14, P4 PR-5**: `App/Update/VelopackHooks`, wired in the hand-written `Program.Main` before any window). **Install registers nothing** — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs `UninstallHook`: `Shutdown` to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, then **ask** about the data folder — deleted on Yes only, never when it and the install overlap (`AreSeparate`), and a question unanswered inside Velopack's 30 s callback budget keeps it.
|
||||
- Velopack hooks (**built 2026-09-14, P4 PR-5**: `App/Update/VelopackHooks`, wired in the hand-written `Program.Main` before any window; since beta.14 Velopack's apply-at-start is off and an update it starts itself stops the Agent first — `11_UPDATER` §The update audit). **Install registers nothing** — the first-run flow is the offer (Agent setup), and the layer follows the ledger (§The Vulkan layer is not registered at install time); this line used to say "offer Agent setup + Vulkan layer registration", and the second half was the thing the section below forbids. Uninstall runs `UninstallHook`: `Shutdown` to a running Agent over the pipe (best effort, it holds the install directory), unregister the layer (HKCU), remove the logon task, remove the *Start FrameLedger with Windows* Run value (beta.14 — it named the executable being deleted), then **ask** about the data folder — deleted on Yes only, never when it and the install overlap (`AreSeparate`), and a question unanswered inside Velopack's 30 s callback budget keeps it.
|
||||
|
||||
## Release-time token substitution
|
||||
|
||||
@@ -223,33 +266,52 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
|
||||
the repository, and it is deliberate: the effective date of a legal document is
|
||||
the date it ships, which is not knowable at authoring time. `release.yml` (**built 2026-09-14**, P4 PR-5 — the step runs before the
|
||||
build, because the App embeds `legal/*.md`)
|
||||
substitutes it with the tag date when packaging, and `ci.yml` fails the build if
|
||||
substitutes it with ~~the tag date~~ the run's UTC date (corrected 2026-10-04) when packaging, and `ci.yml` fails the build if
|
||||
**any other** `{{` token appears in `README.md` or `legal/*.md` (`13_CI_CD.md`
|
||||
§ci.yml). Everything else — repository URL, slug, developer identity, contact
|
||||
address — is resolved in the source files, because an unsubstituted token in a
|
||||
document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
|
||||
**The build id is read before it (beta.18).** The substitution edits tracked files, and the native build id is
|
||||
`git describe --dirty` at CMake's configure (`src/native/FrameLedger.Shm/CMakeLists.txt`): every release until beta.18
|
||||
shipped `<tag>-dirty` — the owner's Dashboard read *Overlay build v0.1.0-beta.17-dirty*, and that run's log printed
|
||||
`FL_BUILD_ID = v0.1.0-beta.17-dirty` two lines after `RELEASE_DATE = 2026-10-07 in 3 file(s)`. `release.yml` now reads
|
||||
describe from the clean checkout first, refuses one that is already dirty or longer than 31 characters, and passes it
|
||||
as the environment's `FL_BUILD_ID`, which CMake takes as given (checked for the characters a C string literal carries);
|
||||
after the publish, `tools/buildid-check.ps1` reads it back out of the four native binaries that compile it, by their
|
||||
bytes — nothing is loaded. A developer's build still runs describe itself (`+` marks a dirty tree when the long form
|
||||
would not fit).
|
||||
|
||||
## Local quality gate (pre-push)
|
||||
|
||||
`./build.ps1 check`:
|
||||
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`)
|
||||
1. `cmake --build --preset x64-release` (C++ `/W4 /WX`) — since beta.12 also `FrameLedger.ProcessStats.dll` (the game
|
||||
process's memory, D43; staged beside the Agent, CaptureHost and Infrastructure.Tests by
|
||||
`FrameLedger.ProcessStats.targets`), its ctest `fl_process_stats` (GPU_INSTANCE on a machine with a hardware adapter,
|
||||
NO_GPU_INSTANCE elsewhere) and the instrument `fl-probe-processstats` (`spike-notes` §16)
|
||||
2. native tests (Catch2)
|
||||
3. `clang-format --dry-run -Werror` over `src/native`
|
||||
4. `dotnet restore` + build (warnings as errors)
|
||||
5. `dotnet format --verify-no-changes`
|
||||
6. `dotnet test --logger trx` — including `ShmLayoutMirrorTests`; with no switches it also runs the
|
||||
`Category=Integration` classes, which CI excludes
|
||||
`Category=Integration` classes, ~~which CI excludes~~ which CI runs too *(corrected 2026-10-04: `ci.yml` and
|
||||
`release.yml` call `./build.ps1 check` with no switches since 2026-09-06, as the paragraph after this list says;
|
||||
only `-SkipIntegration`, which nobody passes, leaves them out, loudly)*
|
||||
7. `tools/coverage-gate.ps1` — reads this run's cobertura reports; self-arming, and armed today for
|
||||
`FrameLedger.Domain` and `FrameLedger.Application`
|
||||
8. `tools/rules-validate.ps1` (schema + `anticheat` block sanity — a malformed or empty blocklist is a safety bug)
|
||||
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version)
|
||||
9. `tools/versioninfo-check.ps1` — reads the built binary, because what ships is what an anti-cheat vendor sees; since P4 PR-5 it also compares every `FileVersion` against the `VERSION` file (§Version); **since beta.14 (D50) both halves run — the self-test, then the native five and the managed eight from the App's and the Agent's build output** (`-ManagedDir`, `-ExpectedProductVersion` = `VERSION`), one copyright across all of them (§Version, *Identity*). Under `-SkipNative` the managed half still runs
|
||||
10. `tools/chokepoint-check.ps1` — injection and evasion primitives confined to one file, native **and** managed, plus the `FL_GUARD_TESTABLE` symbol check against the shipped artifacts
|
||||
11. **`tools/hookinventory-check.ps1`** — three passes: A resolves every vendor symbol the Overlay names against `docs/vendor-exports.json`, B sweeps for stray literals, C reads the BUILT Overlay's import table and asserts it imports no vendor module. C skips loudly under `-SkipNative`. **Missing from this list until 2026-08-28**, which is §R10 happening again
|
||||
12. **`tools/package-closure-check.ps1`** — both halves: the self-test (5 cases, 4 of which must go RED) **and** a live pass over this repository. It walks the transitive `ProjectReference` closure of the two publish roots below and fails on anything outside the allowlist, naming the reference edge. `FrameLedger.CaptureHost` is an injecting entry point kept out of the package by construction, and `20_OPEN_QUESTIONS` §S27 is closed on exactly that basis
|
||||
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: fourteen fixture cases, five that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture
|
||||
13. `tools/license-check.ps1` — asserts every vendored third-party has a licence copy in `legal/licenses/`, and that no Intel IGCL / AMD ADLX material has appeared in the tree; since P4 PR-6 (§3) also that `legal/licenses/nuget/` is exactly what `tools/license-gather.ps1` writes for this build's restore output — every NuGet package the App and the Agent ship (77), both directions. `license-gather.ps1 -SelfTest` runs first: ~~fourteen~~ sixteen fixture cases, ~~five~~ six that must be RED (a hand edit, a package that no longer ships, a URL-only licence with no reviewed override, an expression with no text in the script and no reviewed override, an applied MPL Exhibit B, a missing restore output), and one run under tr-TR in a child process, because the output must not depend on the machine's culture. **Since beta.12 (78 packages):** a reviewed override also answers for an expression the script has no text for — Markdig declares BSD-2-Clause and ships no file, and `tools/license-overrides/Markdig.txt` is the project's own `license.txt` at the packaged commit
|
||||
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
|
||||
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
|
||||
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
|
||||
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/` and `LIMITATIONS.md` into a temporary folder, as `wiki.yml` does at a release (`13_CI_CD` §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than `guide/README.md`, a backticked repository path in a `wiki/` page that names nothing, and a version number written into a `wiki/` page (the footer says which release the wiki shows). Nine self-test cases, both directions
|
||||
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
|
||||
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one). The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
|
||||
14c. **`tools/buildid-check.ps1 -SelfTest`** (beta.18) — eight cases, both directions: a binary built from a dirty tree (`-dirty`, or the short form's `+`), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in `release.yml` over the published tree (§Release-time token substitution)
|
||||
15. `tools/resx-audit.ps1` — ~~**skipped loudly; it does not exist, and no `.resx` file does either**~~ **built 2026-09-13 (P3 PR-2)**: `-SelfTest` first (11 fixture cases, both directions), then the live pass over every `Strings.resx` family under `src/` — key sets equal across en/vi/ja, `Safety_*` in `ja` marked for review or signed, `Strings.Designer.cs` current with `tools/resx-gen.ps1`. A tree with no family is red (`09_I18N` §Translation workflow)
|
||||
16. **struct-mirror** — reads this run's `.trx` and fails when `ShmLayoutMirrorTests` did not execute, so deleting the mirror test is red as well as breaking it
|
||||
16b. **`tools/test-artifacts-check.ps1`** — `-SelfTest` first (seven cases, two RED), then live: an `overlay-*.log` created since this gate started, still in the real `%LOCALAPPDATA%\FrameLedger\logs` after the tests, whose first line names a `hook-harness*` image, fails the gate. It is what makes a test binary without its log sweep red (`17_HOOK_ENGINE` §Native logging, 2026-09-15); a game's log never counts
|
||||
|
||||
+61
-13
@@ -6,7 +6,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
|
||||
## Workflows (`.github/workflows/`)
|
||||
|
||||
### `ci.yml` — push to `main` + all PRs · **repo-local**
|
||||
### `ci.yml` — push to `main` + all PRs + `workflow_dispatch` (added 2026-10-04) · **repo-local**
|
||||
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd`, NuGet cached.
|
||||
- Single step of substance: **`./build.ps1 check`** — the same script, with the same switches (none), a developer runs before pushing. The gate list lives in `12_BUILD` §Local quality gate, **once**, rather than being restated here where it goes stale.
|
||||
- ~~**`-SkipIntegration` is the one place local and CI deliberately differ**~~ — **gone since 2026-09-06.** From 2026-08-05 CI passed it for a measured reason: §S16 puts the injecting process's ancestors in the scan set, a .NET test host loads `System.Security.Cryptography.ProtectedData.dll`, and the guard's `protect` fragment refused our own harness (§S19(b)). The signer half now verifies that module's embedded signature offline and reads `O=Microsoft Corporation` on the compiled-in bound, so the `Category=Integration` cases run here — **nine** when this was written, **20 across six classes** as of 2026-09-13 (Agent 6, CaptureHost 7, Infrastructure 7); count them with `grep -rl 'Category", "Integration' tests` rather than trusting either number — and a green CI IS evidence for the managed drain and the capture host's end-to-end behaviour. The switch remains in `build.ps1`, loud, for a developer who must.
|
||||
@@ -52,6 +52,17 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
case. `Kill` now waits for exit (bounded, asserted) and the delete retries. Not §S19(b) either — a test-harness
|
||||
race, and the third flake shape of the day (the registry-subtree race between `VkLayerRegistrationTests` and the
|
||||
GOG reader's test, fixed in #188) was the same kind.
|
||||
- **Two more on 2026-10-07 (beta.18), both re-run green and then fixed the same day.**
|
||||
`WhenTheTargetExitsTheHostStopsAndSaysWhy` ended **`TargetNotRunning`** (#286, run 37619719203): the host resolves its
|
||||
target once, as it starts, and a host slower than the harness's 6 s hold found it gone — the shape recorded since
|
||||
2026-09-21. The hold is 15 s: a margin, not a signal, because the host prints nothing until its session ends.
|
||||
`LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing` ended **`RefusedByGuard` / `ModuleScanFailed`**
|
||||
(#288, run 37627351438): the hosted runner has the Vulkan loader and no device, so the harness exits 77 with a
|
||||
`[SKIP]` line — but the runner is elevated, the host starts the harness through `CreateProcessWithTokenW`
|
||||
(`UnelevatedProcess`), the child gets no stdout, and the line never reached the host's output; the test then
|
||||
depended on the session reading `LaunchTargetExited`, and a scan that hit the dying harness failed it instead. The
|
||||
test now asks the harness directly, before the host runs (exit 77 = skip, with the harness's own line); hiding the
|
||||
Vulkan ICDs from that probe makes it skip in under a second, and on a machine with a device it runs in full.
|
||||
- **A re-run ERASES the evidence, which is why the count above had to be kept by hand.**
|
||||
`gh run rerun --failed` updates the original run's conclusion, so `gh run list` showed **18 success, 1
|
||||
cancelled, 0 failed** across the twenty runs that contained all three failures above. Anyone measuring
|
||||
@@ -81,8 +92,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
> `ShmLayoutMirrorTests` did not execute. `12_BUILD` carried the identical stale sentence and is
|
||||
> corrected with it; restating the gate list in two documents is what let one of them rot.
|
||||
- **Licence guard:** `tools/license-check` fails the build if a vendored dependency is missing its licence copy, or if Intel IGCL / AMD ADLX headers appear anywhere in the tree (`docs/18_GPU_VENDOR_APIS.md` §Vendor SDKs we deliberately do not use), or — since P4 PR-6 — if `legal/licenses/nuget/` is not what `tools/license-gather.ps1` writes for the NuGet packages this build ships. A Dependabot bump therefore goes red until someone re-runs the script and commits the texts, which is the point: the new version's licence is read by a person before it ships. Licensing regressions are silent and hard to unwind later — catch them at PR time.
|
||||
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md`. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
|
||||
- `permissions: contents: read`.
|
||||
- **Placeholder guard:** fails if any `{{` token survives in `README.md` or `legal/*.md` *(other than `{{RELEASE_DATE}}`, which `release.yml` substitutes — added 2026-10-04)*. Those are shipped, legally operative documents (FR-11 displays them in the first-run Legal Gate); an unsubstituted `{{DEVELOPER_NAME}}` in an EULA is not a cosmetic defect.
|
||||
- ~~`permissions: contents: read`.~~ `permissions: contents: read, pull-requests: read` — the second for the Changelog step's list of a pull request's files, read-only *(corrected 2026-10-04)*.
|
||||
|
||||
### `codeql.yml` — push, PR, weekly cron · **repo-local**
|
||||
|
||||
@@ -127,15 +138,27 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
`VERSION` file (`12_BUILD` §Version); and `CHANGELOG.md` must carry a **non-empty** `## [x.y.z]` section for the
|
||||
full version, extracted by `tools/release-notes.ps1` (self-tested on every `build.ps1 check`). A missing
|
||||
section is a red release, not an empty note — the ledger's header said the opposite for five weeks.
|
||||
- **The build id from the clean checkout** (beta.18): `git describe --always --dirty --abbrev=12` before anything edits a
|
||||
tracked file — a dirty one or one over 31 characters stops the run — into `FL_BUILD_ID` for CMake. Until beta.18 the
|
||||
substitution below ran first and every release's natives called themselves `<tag>-dirty` (`12_BUILD` §Release-time
|
||||
token substitution).
|
||||
- `{{RELEASE_DATE}}` substituted in `legal/*.md` with the run's UTC date **before the build**, because the App
|
||||
embeds those documents (FR-11); any `{{` token left anywhere after that fails the job.
|
||||
- **The identical gate** — `./build.ps1 check`, native first, every tool including `versioninfo-check` against
|
||||
`VERSION`. A release never skips it.
|
||||
- `dotnet publish` App + Agent, self-contained + ReadyToRun, `-p:Version=<tag>`, into one `out/app`.
|
||||
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the four shipped natives
|
||||
`versioninfo-check` lists, `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
|
||||
- **The published tree asserted by name**: `FrameLedger.exe`, `FrameLedger.Agent.exe`, the ~~four~~ five shipped natives
|
||||
`versioninfo-check` lists (`FrameLedger.ProcessStats.dll` since beta.12 — corrected 2026-10-04), `rules/detection-rules.json`; `FrameLedger.CaptureHost.exe` absent (`12_BUILD`:
|
||||
exactly two roots — `package-closure-check` proves it statically, this reads the directory); `versioninfo-check`
|
||||
run again over `out/app`, because a `.targets`-staged DLL that failed to copy is a warning to `dotnet publish`.
|
||||
run again over `out/app`, because a `.targets`-staged DLL that failed to copy is a warning to `dotnet publish` —
|
||||
**since beta.14 (D50) with its managed half** (`-ManagedDir out/app -ExpectedProductVersion <tag>`): the eight managed
|
||||
binaries name FrameLedger, carry the tag's full version and the native binaries' copyright line (`12_BUILD` §Version,
|
||||
*Identity*). Both publishes take `-p:FrameLedgerSourceRef` since beta.14.
|
||||
- **since beta.13, `vpk download github --pre` first**, so `vpk pack` finds the previous release's full package in
|
||||
`out/release` and writes a delta; after the pack, what `assets.win.json` names is kept and the rest (the previous full
|
||||
package) moves to `out/previous`, the feed and `RELEASES` are filtered to this build, and a downloaded previous package
|
||||
with no delta beside it fails the job. A failed download is a warning: the release is full-only, as every one before it
|
||||
was (`11_UPDATER` §Built).
|
||||
- `vpk pack --packId FrameLedger.App` (the `vpk` tool pinned to the library's 1.2.0) with the release notes;
|
||||
`FrameLedger.App-win-Setup.exe` must come out, because README §Install names it. **Not `--packId FrameLedger`**:
|
||||
Velopack installs into and uninstalls `%LOCALAPPDATA%\<packId>`, which with that id is the data folder
|
||||
@@ -148,8 +171,8 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- ~~Optional final step: submit installer hash to VirusTotal~~ — not built; an upload of the installer to a third
|
||||
party is a decision the owner makes, not a step a workflow adds quietly.
|
||||
|
||||
### `rules-publish.yml` — on change to `rules/detection-rules.json` in `main`
|
||||
- Runs `tools/rules-validate` and fails on anti-cheat removals. The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.
|
||||
### `rules-publish.yml` — ~~on change to `rules/detection-rules.json` in `main`~~ on a PR or push to `main` touching the rules file, its schema, `rules-validate.ps1` or this workflow (corrected 2026-10-04)
|
||||
- Runs `tools/rules-validate` and fails on anti-cheat removals. ~~The raw file on `main` **is** the distribution endpoint (05_DETECTION), so this workflow only gates correctness.~~ *(Corrected 2026-10-04: there is no feed — §S20's feed half is deferred and nothing in `src` fetches. A rules change reaches users only inside a release, seeded by the Agent from the packaged copy; this workflow only gates correctness.)*
|
||||
|
||||
> **There is no `rulesVersion` bump check, and this line used to claim one.**
|
||||
> `rules-validate.ps1` checks the field's *format* and nothing compares it
|
||||
@@ -173,9 +196,32 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
> evaluator through the real probe. Both halves run on the same PR; only the
|
||||
> coverage half fires on a rules-only change, which is why the two are
|
||||
> described separately rather than as one gate.
|
||||
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix.
|
||||
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
|
||||
- `permissions: contents: read`.
|
||||
|
||||
### `wiki.yml` — after a successful Release run, and by hand · **repo-local, built 2026-10-07 (beta.17, D53/D54)**
|
||||
- **What:** the GitHub Wiki is a copy of the repository's own pages — `wiki/` (Home, the sidebar, the developer pages)
|
||||
and `guide/` (the user guide: the End-user part, the same pages the App shows) with `LIMITATIONS.md`.
|
||||
`tools/wiki-build.ps1` names each page (a guide page after its first heading, `guide/README.md` as *User-guide*,
|
||||
`LIMITATIONS.md` as *Limitations*), rewrites links between pages to page names and every other repository link to
|
||||
its address on GitHub **at the release's tag**, drops each page's first heading (the wiki prints the page name), and
|
||||
writes a footer naming the tag. The same assembly is `build.ps1`'s `wiki-check` gate (`12_BUILD` §Local quality gate,
|
||||
13d), so a dead link is red on the pull request, never on the published wiki.
|
||||
- **When:** `workflow_run` on `Release`, completed — the job runs only when that run succeeded and was started by a
|
||||
pushed `v*` tag, so a `workflow_dispatch` rehearsal of `release.yml` never publishes. It checks out the run's
|
||||
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. By hand:
|
||||
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
|
||||
`publish=true` it publishes them.
|
||||
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
|
||||
that fails to publish is a red run of its own that can be re-run — a step after `gh release create` could never be
|
||||
re-run, the release already existing. A release created with `GITHUB_TOKEN` fires no `release` event for other
|
||||
workflows; `workflow_run` fires because the Release run itself was started by a tag push.
|
||||
- **Publishing:** `gh auth setup-git`, a clone of `<repo>.wiki.git`, everything but `.git` replaced, a commit as
|
||||
`github-actions[bot]` only when something changed, `git push origin HEAD:master` (the wiki's branch is `master`). A
|
||||
page edited on the Wiki tab is overwritten at the next release: edit `wiki/` or `guide/`.
|
||||
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
|
||||
2026-10-07), and pushing to the wiki repository needs write.
|
||||
|
||||
## Dependabot (`.github/dependabot.yml`)
|
||||
|
||||
```yaml
|
||||
@@ -195,7 +241,7 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
## Branch & release policy
|
||||
|
||||
- `main` protected: CI + CodeQL required, linear history, no direct pushes.
|
||||
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
|
||||
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) → tag `vX.Y.Z` → `release.yml` does the rest (and refuses a tag that disagrees with either file) *(corrected 2026-10-04: for a pre-release tag `vX.Y.Z-beta.N`, do not bump `VERSION` — it already holds the numeric core the gate compares, and it read `0.1.0` through eleven betas; the section is `## [X.Y.Z-beta.N] - date`, the full version. Bump `VERSION` only when the numeric core moves)* → smoke-test the produced installer on a clean Win 10 VM + Win 11 (manual checklist in 14_TESTING §Release smoke).
|
||||
- Pre-releases: `vX.Y.Z-beta.N` tags mark the GitHub release as pre-release; the App's `stable` channel ignores them and its `beta` channel (Settings ▸ Updates, `update.channel`) includes them — built with P4 PR-5, so ~~explicit beta channel is v2 backlog~~ is struck. The managed assemblies carry the full tag version; the native VERSIONINFO blocks carry the numeric core (`12_BUILD` §Version).
|
||||
|
||||
## Repo hygiene checklist
|
||||
@@ -207,7 +253,7 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
**In the tree — done:**
|
||||
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph
|
||||
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph *(and `wiki.yml` since beta.17, repo-local too: five)*
|
||||
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
|
||||
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
|
||||
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
|
||||
@@ -215,7 +261,9 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
|
||||
**GitHub settings — the owner's (`HANDOFF` §Owner-only):**
|
||||
|
||||
- [ ] Branch protection as §Branch & release policy states; `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [x] Branch protection as §Branch & release policy states *(marked 2026-10-04, read from the API: required checks `check`, `analyze (csharp, none)` and `analyze (cpp, manual)`; linear history; a pull request required; force pushes off; enforced for admins)*
|
||||
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
|
||||
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
|
||||
- [ ] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves
|
||||
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
|
||||
- [ ] Wiki editing restricted to collaborators (Settings ▸ General ▸ Features ▸ Wikis ▸ *Restrict editing to collaborators only*): otherwise anyone with a GitHub account can change a page until the next release overwrites it (§wiki.yml, beta.17)
|
||||
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
|
||||
+68
-4
@@ -6,9 +6,9 @@ Managed: xUnit.net v3 4.x (the `xunit.v3.mtp-off` variant since 2026-09-21 — `
|
||||
|
||||
The anti-cheat guard is the one component where a bug can cost someone an account. It gets the most rigorous treatment in the codebase:
|
||||
|
||||
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **Landed long since** — `ctest` runs 31 native suites on every gate (`fl_guard` alone is ~100 s); the sentence was left in the future tense until 2026-09-21.
|
||||
**These are Catch2 tests, not xUnit.** `20_OPEN_QUESTIONS` §S13(a) settled the guard into the C++ `FrameLedger.Injector`, so the fail-closed matrix below lives in the native suite and the guard needs seams — injectable enumerator function pointers — before any of these failures can be forced at all. ~~Landing Catch2 is a prerequisite of the guard, not a later nicety (§S15).~~ **Landed long since** — `ctest` runs ~~31~~ 32 native suites on every gate (`fl_process_stats` since beta.12 — corrected 2026-10-04) (`fl_guard` alone is ~100 s); the sentence was left in the future tense until 2026-09-21.
|
||||
|
||||
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set. **Since 2026-09-25** the fixture is generated from the shipped seed (`rules_budget_test.cpp`: every entry's every value matches its own family in its own group, which also catches a row an earlier prefix shadows), and Ricochet's fixture asserts its data; VAC's still asserts that no family entry fakes it.
|
||||
- Blocklist matching: exact, case-insensitive, prefix rules; every family in `19_SAFETY` §Blocklist seed has a fixture. ~~Two families (Activision Ricochet, Valve VAC) have **no data yet**, so their fixtures must assert that absence explicitly rather than quietly passing on an empty rule set.~~ *(Corrected 2026-10-04: both have data since 2026-09-25 — Ricochet a driver and services, VAC per-title lists of Steam ids and executables, which `rules_budget_test.cpp` matches back to "Valve VAC".)* **Since 2026-09-25** the fixture is generated from the shipped seed (`rules_budget_test.cpp`: every entry's every value matches its own family in its own group, which also catches a row an earlier prefix shadows), and Ricochet's fixture asserts its data; VAC's still asserts that no family entry fakes it.
|
||||
- **A finding turns the game's hooking off (2026-09-22), and the proofs are about WHICH findings.** `AntiCheatVerdictTests` pins `IsFindingAboutTheGame` per reason (in the game: yes; machine-wide driver or service, heuristics, failed scans, the latch: no) and that a finding without a family is not one; `CaptureSessionTests` that a start-time `BlockedModule` writes the block, keeps the consent stamp and says `HookingTurnedOff`, that a `BlockedDriver` refuses the session and leaves the row alone, and that the 30 s re-scan's finding writes the same block; `RecordedSessionEventsTests` and `SafetyNoticesTests` that the flag travels to the notice. The override of 2026-09-21 had its own proofs for one day; they went with it, and `NoSecondMatcherTests` counts the port's four methods again.
|
||||
- **Fail-closed proofs:** malformed `detection-rules.json`, missing `anticheat` block, unreadable target process, `EnumProcessModulesEx` failure, partial module list → **all must refuse injection**, never allow. Each is a named test.
|
||||
- **Measured error paths that must be named tests** (`spike-notes.md` §1): `ERROR_PARTIAL_COPY (299)` from a suspended target, `ERROR_ACCESS_DENIED (5)` from a protected one, a driver-list parse whose paths are not native paths, and a service query returning `ACCESS_DENIED` — the last of which **cannot be produced on real services by a standard user**, so it exists only as a fake. Every one means REFUSE.
|
||||
@@ -16,12 +16,19 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
- **Absence-of-override test:** no code path may reach the injection primitive without a passing guard result. The mechanism previously described here — a `sealed` token type "only the guard can produce" — does not work and was disproved by compiling (`20_OPEN_QUESTIONS` §S8: C# accessibility flows inward, `CS0122`). The replacement is structural: the guard **owns the chokepoint** and calls the primitive itself, the primitive has internal linkage in the guard's own translation unit so no other TU has a symbol to call, and a build-time check asserts that nothing else references it. A token that escapes can be ignored; a symbol that does not exist cannot.
|
||||
- Static pre-scan: a game directory containing `EasyAntiCheat/` renders `hook_enabled` un-settable; API-level attempt to set it is rejected — including via `SetWatchlist`, which no longer carries hooking state at all (`07_IPC` §The pipe is not a trust boundary). ~~**The toggle half needs persistence and is not built yet**~~ **built in P2/P3**: `SqliteGameConsentStore.RecordGuardBlockAsync` forces `hook_enabled = 0`, `AgentCommandHandler.SetHookEnabledAsync` re-runs the pre-scan and answers `Refused`, and `GameDetailViewModel` disables the toggle on a blocked row (corrected 2026-09-21; since 2026-09-22 a finding at a session's start or at the re-scan writes the same block — `CaptureSessionTests`); the scan itself is ctest `fl_prescan`, whose matrix is mostly fail-closed: a listing that FAILED, one that was TRUNCATED, a directory that could not be established, unusable rules, and a missing evidence source must each be *undetermined*, never clean. Two cases exist only to stop the rest passing vacuously — a genuinely clean directory must be **allowed**, and a name matching the wrong group (a directory named like a `files` entry) must **not** fire. One case removes a family from the rules and asserts the hit disappears, which is what proves there is a single matcher rather than a second one that happens to agree.
|
||||
|
||||
> **D48 (beta.14):** the module check's one re-read is held both ways in ctest `fl_guard` `[D48]` — a member still
|
||||
> loading reads clean on the re-read (one pause, two snapshots); one still unreadable refuses; one that exited drops out of
|
||||
> the fresh set; a target that exited refuses; `ACCESS_DENIED` is never retried; a finding refuses at once and a finding
|
||||
> the re-read sees refuses — and against the real source (`[live]`: a process created suspended and a pid with no process
|
||||
> answer `kRetry`). The managed half — a refused re-scan of a game that has exited ends as its exit, never for a finding —
|
||||
> is `CaptureSessionTests` and `SessionRecorderTests`.
|
||||
|
||||
## Native unit tests (Catch2)
|
||||
|
||||
- **Ring buffer:** SPSC correctness under a hammering writer thread; seqlock torn-read detection; wrap and overwrite-oldest semantics; power-of-two capacity assumptions. Include the **one-full-lap case**: a reader stalled exactly `capacity` records must not validate a different frame as unchanged (this is what the never-reset `seq` counter defends, `07_IPC` §Protocol rules).
|
||||
- **Drop accounting:** the reader-side computation (`writeIndex - readIndex > capacity`) reports the right count and resumes at the right index. The writer has no drop counter to test — by design.
|
||||
- **Torn records produce gap markers,** not silently shortened streams; a golden test asserts the gap does not appear as a stutter.
|
||||
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all three header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`) — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
|
||||
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all ~~three~~ four header structs** (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`, and `FlDisplayState` since layout 4, beta.10) — plus D33's `FlTolerance`, mirrored the same way *(corrected 2026-10-04)* — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
|
||||
- **Fault policy:** injected SEH faults in a fake hook body → counter increments, original still called, self-disable at 3.
|
||||
- **Hook index verification, by behaviour.** A vtable slot carries no identity, so "check that slot 8 *is* `Present`" is not a question the runtime can answer — the earlier wording here required something unimplementable. What is answerable: patch the slot, call the method, see whether the detour ran (`17_HOOK_ENGINE` §Getting vtable addresses; proved for slots 8, 13 and 22 in `spike-notes.md` §H4). Runs headless on CI via WARP and `CreateSwapChainForComposition`. A deliberate mismatch aborts installation instead of patching.
|
||||
- **Every probe must be shown to fail.** A probe that ends in an unconditional assertion is green by construction and its ctest is decorative — `fl_proxy_swapchain` shipped in exactly that state. Before a probe counts as a regression net, break the thing it watches and watch it go red.
|
||||
@@ -44,6 +51,52 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
- Blob codecs round-trip for every series in `frame_blobs` (NaN forbidden — assert), including the two-pair `render_res` encoding and the three-bit `rt_flags` byte. SQLite migrations apply cleanly from an empty file to the current schema, and re-applying is a no-op. (There is no v1→v2 upgrade to test — `06_DATA_MODEL` §Migrations.)
|
||||
- IPC pipe: framing, split reads, oversize rejection, unknown fields/types ignored, protocol mismatch.
|
||||
|
||||
### What the App draws (beta.14)
|
||||
|
||||
A page or dialog that only *loads* has proved nothing about how it looks: `PagesLoadTests` counted the import list's
|
||||
rows while every row was white text on white in the dark theme (`08_UI` §Contrast). The rendered checks run on the one
|
||||
STA thread with the App's three dictionaries (`PagesLoadTests.OnStaAsync`) and look at the result: `Visuals` lays a
|
||||
control out at a window's size, pumps the dispatcher (a `NavigationViewContentPresenter`'s navigation), swaps the theme
|
||||
dictionary for one check and puts Dark back, and composites every Border and Panel background between a text and the
|
||||
window into the colour actually painted under it; `Wcag` is the arithmetic. `ImportReviewRenderTests` measures each text
|
||||
cell against that colour in both themes and counts the accent pixels of each ticked box in a `RenderTargetBitmap`; the
|
||||
paging checks navigate a real page in WPF UI's presenter and send it the wheel. Each was run red against the unfixed XAML
|
||||
first — a rendered check that cannot fail is the counted-rows check again.
|
||||
|
||||
**A theme switch needs a window (beta.17).** A change to `Application.Resources` reaches only the trees of
|
||||
`Application.Windows`, and a `Window` registers itself there when it is constructed, shown or not. So
|
||||
`PagesLoadTests.EveryTextFollowsAThemeSwitch` hosts each surface in a `FluentWindow` it never shows, swaps the theme
|
||||
dictionary as `ApplicationThemeManager.Apply` does, and compares every text's colour with the same surface made fresh
|
||||
under the new theme. `PagesLoadTests.Surfaces` builds every page, window and dialog content from loaded view models, for
|
||||
any check that wants all of them. Colours are compared and texts only reported: another test class may change
|
||||
`Strings.Culture` between the two builds.
|
||||
|
||||
**A page is measured in the Frame the App shows it in, and a theme brings its accent (beta.18).** WPF UI's
|
||||
`NavigationViewContentPresenter` is a `Frame`, which passes no inherited value into the page, the text colour included, so
|
||||
a page laid out straight in a window measures the window's colour and not the App's: the theme-switch check above did, and
|
||||
stayed green over every page title drawn black (`08_UI` §Contrast, fifth hole). The rendered checks host a page in the
|
||||
presenter (`PagesLoadTests.Hosted`), and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface's shown
|
||||
texts at ≥ 3:1 in both themes. `Visuals.UnderTheme` switches as the App does — the accent resources derived for the theme
|
||||
from Windows' default accent (`Visuals.DefaultAccent`, the App's derivation rather than the machine's own palette), then
|
||||
the dictionary — and puts the application's own resources back afterwards. The accent lives in `Application.Resources`,
|
||||
not in a theme dictionary; until then a check under Light measured the dark theme's link blue on the light window, 1.9:1,
|
||||
a colour the App never shows. The theme-switch check compares what can be seen: a text only one of the two instances holds
|
||||
counts where it shows, and a collapsed part is not compared (a switch re-applies the template of a DataGrid's idle scroll
|
||||
bar, and its glyphs exist in the switched instance only).
|
||||
|
||||
**Loaded needs a shown window, and even then it is not raised everywhere (beta.17).** A tree laid out by hand never raises
|
||||
Loaded, and a shown one raises it only where a subtree listens for it (`16_WPFUI_SYNTAX` §Gotchas) — so a test that calls
|
||||
`RaiseEvent(Loaded)` proves a handler, never that WPF reaches it. `ScrollBarHidingTests.EverySurfaceShownWithTheOptionOnDrawsNoBar`
|
||||
shows each surface in a real window, off the screen and never activated, with the option on before anything is built as
|
||||
at start-up; `WpfRaisesLoadedOnlyWhereASubtreeListensForIt` checks the harness against WPF itself (a scroller holding a
|
||||
Border is never loaded, one holding a CheckBox is), on CI too.
|
||||
|
||||
**A test that sends input must also say which keys are held.** `Keyboard.Modifiers` is the machine's real keyboard, read
|
||||
from any thread (a fresh background thread's `GetKeyState` reports the machine's NumLock — measured 2026-10-06), so a
|
||||
wheel test that read it held whatever key a person pressed while the gate ran: `ChartWheelTests`' plain half went red once
|
||||
on the developer's machine and never on CI. The handlers read `ChartWheel.CurrentModifiers`, which the test sets inside its
|
||||
own work item on the STA thread and puts back — and with the keys a parameter, the Ctrl half is driven end to end too.
|
||||
|
||||
## Integration tests (CI-runnable, no game, no anti-cheat surface)
|
||||
|
||||
`hook-harness` is what makes this architecture testable without touching a real title:
|
||||
@@ -62,6 +115,16 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
|
||||
caused when its run ends, and `tools/test-artifacts-check.ps1` fails the gate for one left behind
|
||||
(`17_HOOK_ENGINE` §Native logging, 2026-09-15). A new native test binary that starts the harness needs the listener;
|
||||
a managed test project that stages it gets the sweep from `FrameLedger.DrainFixtures.targets`.
|
||||
- **Test isolation: a suite whose host resolves its target BY NAME consents to a run-unique copy of the harness**
|
||||
(beta.16). `build.ps1` runs the test projects as parallel processes, and `TargetResolver` counts every process of the
|
||||
consented executable's name — an unreadable one too, which is what a `hook-harness.exe` another project is still
|
||||
starting is (its module list a partial copy). #269's first CI run lost `AgentEndToEndTests` that way:
|
||||
`TargetAmbiguous`, exit 6. `AgentEndToEndTests`, `PartialRecoveryEndToEndTests` and `CaptureHostEndToEndTests` now copy
|
||||
the staged harness to `hook-harness-<their scratch directory>.exe` beside their data, as `PipeEndToEndTests` already
|
||||
did, register that directory with the sweep, and pin the copy to the staged harness byte for byte;
|
||||
`AnotherHookHarnessRunningBesideTheSuiteDoesNotMakeTheTargetAmbiguous` runs a second harness beside the capture (red
|
||||
against the shared name: `TargetAmbiguous`). A suite that attaches by pid (`ShmDrainIntegrationTests`, the native
|
||||
`fl_guard_test`) is not exposed and keeps the staged name.
|
||||
- Guard integration: harness loads a **dummy DLL named like an anti-cheat module** → injection refused pre-launch; loaded late → safety unhook. (A renamed harmless DLL, not real anti-cheat software.)
|
||||
|
||||
## Hook overhead measurement (NFR-1, per release)
|
||||
@@ -131,7 +194,8 @@ that it was checked against anything.
|
||||
| Mode | launch mode · attach mode · mid-session settings change |
|
||||
| Safety | game with anti-cheat → toggle disabled · simulated late AC load → unhook · double-crash → auto-disable |
|
||||
| Tier | forced Tier 2 (records duration, available sensors and the reason — and nothing else) · Tier 1 → Tier 2 degradation notice |
|
||||
| Update | Velopack delta; update deferred while a game is hooked (FR-12) — *a delta needs a previous release, so this row is reachable from the second release, not the first* |
|
||||
| Update | Velopack delta; update deferred while a game is hooked (FR-12) — *a delta needs a previous release, so this row is reachable from the second release, not the first* *(corrected 2026-10-04: no release has carried a delta — `release.yml` never fetches the previous release before `vpk pack`, `11_UPDATER` §Built — so the update leg is a full package; **since beta.13** a release carries a delta against the previous one, and the first
|
||||
update that can use it is beta.12 → beta.13 — HANDOFF owner-only item 10)* |
|
||||
|
||||
## Release smoke
|
||||
|
||||
|
||||
+16
-8
@@ -151,7 +151,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> the hard gate, against NFR-10 — but the evidence changed, and the consequence is
|
||||
> live: the drain tests are skipped in CI until it is fixed.
|
||||
|
||||
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. **◐ Every documented check now has a call site; one half of one check does not.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
|
||||
0. **The guard.** Module + driver enumeration, blocklist matching, fail-closed behaviour on every error path. **Moved from item 8**: items 1 and 6 below inject into real games, and CLAUDE.md rule 2 plus P1's own "it ships before the first real injection, not after" both forbid that ordering. ~~**◐ Every documented check now has a call site; one half of one check does not.**~~ **Every documented check has a call site since 2026-09-25 (§S14) — corrected 2026-10-04.** `EvaluateImpl` runs checks 1, 2, 2b, 3 (executable half) and 4 — five, not four, because 2b (`services`) is the only tier ever measured firing on real anti-cheat and every count that says "four" omits it. The guard is built (`FrameLedger.Injector`, native per §S13(a)), owns the chokepoint, and its fail-closed matrix is Catch2-driven. The injection primitive landed after it, in that order. Reached from managed code through one P/Invoke facade — never a second matcher (§S15). Evidence: `spike-notes.md` §1; §S7, §S8, §S16 closed.
|
||||
|
||||
> **This line said ✅ DONE, and it was wrong in a way worth recording.**
|
||||
> `19_SAFETY` specifies four pre-injection checks. **Check 4** (the static
|
||||
@@ -174,6 +174,12 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> > deleted: it is the third place that had to be corrected for one PR, and the
|
||||
> > count is the point.
|
||||
> >
|
||||
> > *(Corrected 2026-10-04: the paragraphs below were overtaken on 2026-09-25 — both halves of check 3 are wired
|
||||
> > and seeded. `CheckBlockedStoreId` reads Steam's `appmanifest_*.acf` and GOG's `goggame-*.info` through a
|
||||
> > guard-owned seam; an install no store names is not refused, unreadable store metadata is; Epic has no reader.
|
||||
> > Rules 2026.10.1 list 33 executables and 33 Steam ids, floored. The owner question about a permanently
|
||||
> > uncallable sub-check is moot.)*
|
||||
> >
|
||||
> > **This item stays ◐, on a different and narrower reason.** Check 3's
|
||||
> > **store-id half** has no call site and cannot be given one: nothing produces
|
||||
> > a `store_id` — the platform metadata extractors are unbuilt, which is the
|
||||
@@ -186,7 +192,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> > uncallable is an owner decision, not a coding one. And unchanged either way:
|
||||
> > `blockedExecutables` **ships empty**, so check 3 refuses nothing today. What
|
||||
> > #52 changed is that populating it would now do something.
|
||||
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, interception not started.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. `vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.
|
||||
1. **Vulkan layer passthrough.** Minimal implicit layer registered under `HKCU`, with the opt-in checks that keep it passthrough for non-enabled processes. **Moved from item 7**: a passthrough bug loads FrameLedger into every Vulkan process on the machine, which is the highest blast radius in the spike. **◐ Gates done, ~~interception not started~~.** `enable_environment` measured against loader 1.4.357, blast radius verified, in-layer blocklist self-scan built and proven both directions. ~~`vkQueuePresentKHR` is **not** hooked — that is P1, and §S2's in-layer supervision check lands with it.~~ *(Corrected 2026-10-04: landed 2026-09-06, P1 item 3 — present and swapchain interception plus §S2's in-layer supervision, ctests `fl_vklayer_real` and `fl_vklayer_supervision`. The ray-tracing and pipeline entries are still unbuilt.)*
|
||||
2. **Hook viability.** `hook-harness` (D3D11 + D3D12) + MinHook: dummy-device vtable probe, verify present indices at runtime, install/uninstall cleanly, measure per-present cost. Confirm `/MT` DLL loads into a real (offline, non-AC) game without incident. **✅ DONE.** Vtable indices proved by behaviour (§H4), unhook proved not to clobber a later hooker (§H7), per-present cost measured at 8.4 ns against a 1,000 ns budget — and **the `/MT` DLL is now loaded into a real title**: Lies of P, attach mode, guard passing, module verified present by re-enumeration, game still rendering afterwards (`spike-notes.md` §7).
|
||||
|
||||
> **Attach mode only when this ran.** Launch mode was blocked by §S18 — the
|
||||
@@ -224,7 +230,9 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
> (Steam `.acf`, GOG `.info`, Epic `.item`) — every platform rule is
|
||||
> `sibling_glob`/`path_contains`, so identification is unaffected but
|
||||
> **`store_id` is null for every title**. No SQLite, so nothing is persisted
|
||||
> and `field_provenance` is decided-but-unimplemented (P2). The engine and
|
||||
> and `field_provenance` is decided-but-unimplemented (P2). *(Overtaken — corrected 2026-10-04: the store import
|
||||
> writes `store_id` since P4 PR-4, the guard reads the stores' metadata for check 3 since 2026-09-25, and
|
||||
> `field_provenance` is written since 2026-09-14.)* The engine and
|
||||
> platform fixture families are **P4 library metadata shipped early** under
|
||||
> P0's name.
|
||||
>
|
||||
@@ -264,7 +272,7 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
8. **Telemetry layering.** Fill the `18_GPU_VENDOR_APIS` capability matrix on real hardware:
|
||||
- L1 baseline (DXGI + PDH counters) working vendor-neutrally; decide whether the `D3DKMT` perf-data probe is stable enough on Win 10 **and** Win 11 to keep. **🅓 Deferred to Win 11 only, 2026-08-05** — one machine, and it is Win 11. Win 10 22H2 stays a supported floor and is explicitly unmeasured; the deferral holds only for as long as the probe stays non-load-bearing, which `18_GPU_VENDOR_APIS` §L1 now states as the condition rather than as advice.
|
||||
- L2: which fields LibreHardwareMonitor actually returns per vendor, and **whether GPU sensors work unelevated without PawnIO** — this decides whether the default unelevated Agent has temperatures. **◐ NVIDIA measured 2026-09-03: yes (§M5 row R1), eight fields unelevated, `LhmTelemetrySource` written.** AMD / Intel remain 🅓 (§R5/§R6).
|
||||
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation.
|
||||
- L3: NVAPI linked from vendored MIT headers; Reflex latency, throttle reasons, per-domain utilisation. *(Status added 2026-10-04: built 2026-09-10, P2 PR-E2, as `FrameLedger.NvapiBridge.dll` — throttle reasons and utilisation; Reflex latency has no producer.)*
|
||||
- ~~**Licence confirmations:** LHM free of MPL-2.0 Exhibit B; NVAPI SPDX blocks intact~~ — **done before P0 began, both clear** (`spike-notes.md` §0). `tools/license-check` is in place and proven to fail on a planted violation.
|
||||
|
||||
*(The former items 7 "Vulkan layer" and 8 "Guard prototype" are now items 1 and 0. §R1/§R2 are folded in, not pending.)*
|
||||
@@ -313,14 +321,14 @@ Findings written to `docs/spike-notes.md`. Nothing in P1 starts until the exit c
|
||||
## P2 — Capture pipeline (1 week)
|
||||
Agent: watcher, tier selection, injection orchestration, shm drain, telemetry poller (NVAPI first), session recorder, segments, `.partial` recovery, ~~Tier-2 `EtwFrameSource` retained as fallback.~~ **There is nothing to retain: Tier 2 has no mechanism as of 2026-08-27** (§G). `EtwFrameSource` is a port with no adapter, and P2 should not be planned as though writing one were scoped. SQLite v2 schema + migrations. Domain metric calculators + golden tests. **Milestone: first real hooked session persisted with measured upscaler/RT data.** *Technical half reached 2026-09-10 (P2 PR-F): the shipped `FrameLedger.Agent.exe --console capture` against `hook-harness` ends as one hooked `sessions` row, in the merge gate (`AgentEndToEndTests`). **P2's code is complete as of PR-G (2026-09-10)** — kill-and-recover is in the gate too (`PartialRecoveryEndToEndTests`) and `tools/fps-impact-runbook.ps1` exists. What P2 still owes is two MEASUREMENTS, not code: the real-title milestone read against the game's own menus, and the ≤ 0.5 % FPS-impact run. Both are the owner's; `spike-notes` §14 holds their slots and the exact commands. **The milestone's row half exists as of 2026-09-16** — the shipped Agent's Lies of P session with `fsr3`, 1506×848 → 2560×1440, FG ×2.04 and `rt = no` (`spike-notes` §14.1); the menu column is still the owner's, as is the FPS-impact run.*
|
||||
|
||||
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; the owner's merges of the stack are the remaining act)**
|
||||
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). *Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*
|
||||
## P3 — UI (1 week) — **code-complete 2026-09-14 (P3 PR-0 … PR-9; `docs/HANDOFF.md` §P3 carries the slice table, each row struck with its PR; ~~the owner's merges of the stack are the remaining act~~ merged 2026-09-13/14, #152–#165)**
|
||||
WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashboard live card showing *measured* settings, session summary, ScottPlot charts, game detail tabs, Compare with tier guarding, segment ribbon, tri-state chips with override, refusal/degradation/unhook notices as first-class UI. **Plus, moved here from P4 on 2026-09-13 (owner):** the command pipe (`07_IPC` §C — P2's decision D10 put it here), i18n en/vi/ja with `tools/resx-audit` (the consent dialog is the first thing that needs a reviewed `.resx`, so it cannot wait), the Legal Gate (FR-11), Settings (FR-10, the kill switch first), the Logs page, tray + toasts. The owner chose the whole of `08_UI` over a shell-first cut; HANDOFF §P3 carries the slice order and the decisions (D11–D17). ~~*Not started as of 2026-09-13: `FrameLedger.App` is the scaffold, `FrameLedger.Shared` has no IPC type, and no `.resx` exists in the tree.*~~ *(Struck 2026-10-04: false since PR-2 — the App shell, the en/vi/ja `.resx`, `Shared/Ipc`.)*
|
||||
|
||||
## P4 — Detection & product polish (1 week)
|
||||
~~Static rules engine + `detection-rules.json` (engines, platforms, capabilities, **anticheat blocklist**) + validator + fixtures~~ **landed 2026-09-14 (P4 PR-1: the engine existed since P0; the Agent's `DetectionSweep` is its first caller, `ApplyDetectionAsync` its first writer — HANDOFF §P4)**; ~~store auto-import~~ **landed 2026-09-14 (P4 PR-4)**; ~~capability-vs-measured UI separation~~ **(PR-1: the Supports row reads the sweep's flags)**; ~~i18n en/vi/ja; Legal Gate;~~ ~~Velopack + updater (with the hooked-session deferral)~~ **landed 2026-09-14 (P4 PR-5 — the deferral is `UpdateService`'s shape, not a flag)**; ~~bug bundle incl. overlay logs~~ **landed (overlay logs since P3 PR-8a; 2026-09-15, P4 PR-9: the crash dialog, the minidump in both processes and the dump as the bundle's opt-in — `10_LOGGING` built notes)**; ~~tray + toasts; Settings;~~ ~~DB maintenance~~ **landed 2026-09-15 (P4 PR-7: the sweep is the Agent's over `SweepRetention`; integrity, backup and compaction in the App)**; ~~accessibility pass~~ **landed 2026-09-15 (P4 PR-8: `08_UI` §Accessibility written first — Ctrl+1…5, Esc on every dialog, an automation name on every textless input, theme colours only — each held by `AccessibilityTests`)**; ~~the scheduled task (`--install-task`)~~ (P3 PR-8b) and ~~the Velopack install hooks~~ **(PR-5: the uninstall hook; install registers nothing, by design — `12_BUILD` §The Vulkan layer is not registered at install time)**. *(The struck items moved to P3 on 2026-09-13 — see §P3.)*
|
||||
|
||||
## P5 — Ship (3–4 days)
|
||||
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — ~~untested by a tag yet~~ **ran on the first tag 2026-09-16** (`13_CI_CD` §release.yml: cancelled by a test hang once, green on the re-run); **rehearsable without one since 2026-09-16**, `13_CI_CD` §release.yml's dry run); CodeQL (C# + C++); Dependabot; CHANGELOG; README with the P0 accuracy comparison — **which is not a percentage, and this line used to send its author looking for one**. The decision is recorded under item 3 and in `spike-notes.md` §8: the baseline can answer **none** of item 4's four runtime questions, so the defensible claim is *"the baseline cannot answer four of these five questions at all"*, not *"N% more accurate"*. Overhead + tier cross-validation measurements; release smoke on clean VMs; ~~`v0.1.0-beta.1`~~ **tagged and published 2026-09-16** (pre-release, unsigned, `SHA256SUMS.txt` beside the assets). What P5 still owes: the clean-VM smoke (`14_TESTING` §Release smoke — Win 10 22H2 is unmeasured), the overhead run (`spike-notes` §14.3), and the README's accuracy comparison sentence.
|
||||
CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 — ~~untested by a tag yet~~ **ran on the first tag 2026-09-16** (`13_CI_CD` §release.yml: cancelled by a test hang once, green on the re-run); **rehearsable without one since 2026-09-16**, `13_CI_CD` §release.yml's dry run); CodeQL (C# + C++); Dependabot; CHANGELOG; README with the P0 accuracy comparison — **which is not a percentage, and this line used to send its author looking for one**. The decision is recorded under item 3 and in `spike-notes.md` §8: the baseline can answer **none** of item 4's four runtime questions, so the defensible claim is *"the baseline cannot answer four of these five questions at all"*, not *"N% more accurate"*. Overhead + tier cross-validation measurements; release smoke on clean VMs; ~~`v0.1.0-beta.1`~~ **tagged and published 2026-09-16** — eleven pre-releases through `0.1.0-beta.11` (2026-10-03), added 2026-10-04 — (pre-release, unsigned, `SHA256SUMS.txt` beside the assets). What P5 still owes: the clean-VM smoke (`14_TESTING` §Release smoke — Win 10 22H2 is unmeasured), the overhead run (`spike-notes` §14.3), and the README's accuracy comparison sentence.
|
||||
|
||||
**Total ≈ 5.5–6.5 weeks full-time** — roughly 1.5–2 weeks more than the ETW design, which is the honest price of the accuracy.
|
||||
|
||||
@@ -339,7 +347,7 @@ CI/CD with the native build (`release.yml` exists since P4 PR-5, 2026-09-14 —
|
||||
- Microsoft Store / Game Pass titles (packaged-app injection constraints)
|
||||
- AFK segmentation via `GetLastInputInfo`
|
||||
- GPU frame time via timestamp queries (needs care: injecting queries into the game's command lists is more invasive than anything in v1 — needs its own risk review)
|
||||
- Beta update channel; ARM64
|
||||
- ~~Beta update channel;~~ ARM64 *(struck 2026-10-04: the beta channel shipped with P4 PR-5 — `update.channel`, Settings ▸ Updates; `13_CI_CD` §Branch & release policy)*
|
||||
|
||||
## Permanently out of scope
|
||||
|
||||
|
||||
+89
-9
@@ -7,7 +7,7 @@ Mandatory conventions for all XAML/C# in `FrameLedger.App`. WPF UI = lepoco's Fl
|
||||
| Package (NuGet id) | Pin | Notes |
|
||||
|---|---|---|
|
||||
| `WPF-UI` | **= 4.3.0** (exact; bump deliberately) | Assembly/namespace is `Wpf.Ui`. Targets `net8.0-windows` → resolves cleanly for our `net10.0-windows10.0.22621.0` TFM (`12_BUILD` §Managed build; this row said `19041` until 2026-09-21, which is no TFM this repository ever built — `Directory.Build.props` has been `22621` with a 19045 floor throughout) |
|
||||
| `WPF-UI.Abstractions` | transitive | Navigation abstractions (`INavigationViewPageProvider`) |
|
||||
| `WPF-UI.Abstractions` | ~~transitive~~ **= 4.3.0**, referenced directly (corrected 2026-10-04) | Navigation abstractions (`INavigationViewPageProvider`) |
|
||||
| `WPF-UI.DependencyInjection` | match `WPF-UI` | DI glue (`services.AddNavigationViewPageProvider()`); verify exact id/version at scaffold |
|
||||
| `WPF-UI.Tray` | **not used** | Tray stays on H.NotifyIcon.Wpf (CLAUDE.md stack table) |
|
||||
|
||||
@@ -81,7 +81,7 @@ Theme rules:
|
||||
<RowDefinition Height="*"/> <!-- NavigationView -->
|
||||
</Grid.RowDefinitions>
|
||||
|
||||
<ui:TitleBar Grid.Row="0" Title="FrameLedger" Icon="pack://application:,,,/Assets/icon.ico" />
|
||||
<ui:TitleBar Grid.Row="0" Title="FrameLedger" /> <!-- no Icon: no icon file exists yet (corrected 2026-10-04) -->
|
||||
|
||||
<Menu Grid.Row="1"> <!-- classic menu, Fluent-restyled automatically --> </Menu>
|
||||
|
||||
@@ -103,7 +103,7 @@ Theme rules:
|
||||
</ui:NavigationView>
|
||||
|
||||
<ui:SnackbarPresenter x:Name="SnackbarPresenter" Grid.Row="2" VerticalAlignment="Bottom" />
|
||||
<ContentPresenter x:Name="DialogHost" Grid.Row="2" /> <!-- ContentDialogService host -->
|
||||
<ui:ContentDialogHost x:Name="DialogHost" Grid.Row="2" /> <!-- §Dialogs; a ContentPresenter stood here until 2026-10-04 -->
|
||||
</Grid>
|
||||
</ui:FluentWindow>
|
||||
```
|
||||
@@ -121,7 +121,7 @@ Code-behind wires services once: `navigationService.SetNavigationControl(RootNav
|
||||
| Need | Use | Not |
|
||||
|---|---|---|
|
||||
| Button | `ui:Button` with `Appearance="Primary/Secondary/Danger"`, `Icon="{ui:SymbolIcon Play24}"` | bare `Button` |
|
||||
| Text | `ui:TextBlock` with `FontTypography="Caption/Body/BodyStrong/Subtitle/Title"` | hardcoded FontSize |
|
||||
| Text | `ui:TextBlock` with `FontTypography="Caption/Body/BodyStrong/Subtitle/Title"`; muted text with `Style="{StaticResource SecondaryText}"` or `TertiaryText` (beta.17) | hardcoded FontSize; `Appearance="Secondary"` on a TextBlock (§Gotchas) |
|
||||
| Text input | `ui:TextBox` (`PlaceholderText`, `Icon`) | native TextBox |
|
||||
| Numbers | `ui:NumberBox` (`Minimum/Maximum/SmallChange`, `SpinButtonPlacementMode="Compact"` — needs ≥ 4.3.0) | TextBox + parsing |
|
||||
| Toggle | `ui:ToggleSwitch` | CheckBox for on/off settings |
|
||||
@@ -132,9 +132,9 @@ Code-behind wires services once: `navigationService.SetNavigationControl(RootNav
|
||||
| Busy | `ui:ProgressRing` | |
|
||||
| Contextual popup | `ui:Flyout` | Popup hand-rolling |
|
||||
| Hyperlink-ish | `ui:HyperlinkButton`, `ui:Anchor` | |
|
||||
| Grid of records | native `DataGrid` (WPF UI restyles it) | third-party grids |
|
||||
| Grid of records | native `DataGrid` (WPF UI restyles it — through the grid's own `RowStyle`/`CellStyle`/`ColumnHeaderStyle` setters, so a local one is based on WPF UI's keyed style: §Gotchas, added 2026-10-05) | third-party grids |
|
||||
|
||||
Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `ControlsDictionary` restyles standard WPF controls to Fluent automatically.
|
||||
Native `Menu`, `TabControl`, `ComboBox`, `Slider`~~, `ListView`~~ are fine — the `ControlsDictionary` restyles standard WPF controls to Fluent automatically. *(Corrected 2026-10-05: 4.3.0 has no implicit style for the native `ListView`, `ListViewItem` or `GridViewColumnHeader` — only `ui:ListView` is restyled — nor for `DataGridRow`, `DataGridCell`, `DataGridColumnHeader` or `FlowDocumentScrollViewer`; read from the loaded `ControlsDictionary`.)*
|
||||
|
||||
## Icons
|
||||
|
||||
@@ -143,7 +143,7 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
|
||||
|
||||
## Theming & brushes
|
||||
|
||||
- Colors **only** via `{DynamicResource …}` theme keys, e.g. `TextFillColorPrimaryBrush`, `TextFillColorSecondaryBrush`, `ControlFillColorDefaultBrush`, `CardBackgroundFillColorDefaultBrush`, `ApplicationBackgroundBrush`, `AccentTextFillColorPrimaryBrush`, `SystemFillColorCriticalBrush`. `DynamicResource` always (theme can change at runtime); `StaticResource` for theme brushes is a review-blocking bug.
|
||||
- Colors **only** via `{DynamicResource …}` theme keys, e.g. `TextFillColorPrimaryBrush`, `TextFillColorSecondaryBrush`, `ControlFillColorDefaultBrush`, `CardBackgroundFillColorDefaultBrush`, `ApplicationBackgroundBrush`, `AccentTextFillColorPrimaryBrush`, `SystemFillColorCriticalBrush`. `DynamicResource` always (theme can change at runtime); `StaticResource` for theme brushes is a review-blocking bug. *(Added 2026-10-07: so is a property that looks like a theme colour but is looked up once — `ui:TextBlock Appearance`, §Gotchas.)*
|
||||
- **`ui:Badge` `Appearance="Info"` / `Caution` / `Danger` / `Success` are NOT theme colours.** Their backgrounds are
|
||||
`Palette*Brush` from WPF UI's `Palette.xaml` — one fixed Material palette shared by both themes — under the theme's
|
||||
text: Info is white on `#03A9F4` in dark (2.6:1), measured 2026-09-16 on the Games card. ~~Use `Secondary` (theme
|
||||
@@ -152,7 +152,24 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`, `ListView` are fine — the `
|
||||
styles (`Styles/FrameLedger.xaml`), or the `Pill` style with a `SystemFillColor*BackgroundBrush` and an explicit text
|
||||
brush; `ContrastTests` refuses all five (`08_UI` §Contrast).
|
||||
- Do **not** set `Background` on `FluentWindow` (kills Mica). Page backgrounds transparent by default.
|
||||
- Exception to the no-hex rule: the chart palette — defined once per theme in `Styles/ChartPalette.xaml` (two dictionaries), never inline.
|
||||
- **Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`** (2026-10-07): the navigation's
|
||||
Frame passes no text colour into a page, and a text with none is black (§Gotchas).
|
||||
- Exception to the no-hex rule: the chart palette — defined once per theme in ~~`Styles/ChartPalette.xaml` (two dictionaries)~~ `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml` (corrected 2026-10-04), never inline.
|
||||
|
||||
## FlowDocument (rendered documents, beta.12)
|
||||
|
||||
- **WPF UI 4.3.0 styles no `FlowDocument`.** Its own defaults are black Georgia on white, so a document in the dark theme
|
||||
is unreadable unless the document is themed in code: `Markdown/MarkdownRenderer` sets `TextElement.Foreground` to
|
||||
`TextFillColorPrimaryBrush` and `TextElement.FontFamily` to `ContentControlThemeFontFamily` **by resource reference**
|
||||
(`SetResourceReference`, the code form of `DynamicResource`), a transparent background, and resource references for
|
||||
every other colour (`AccentTextFillColorPrimaryBrush` links, `SubtleFillColorSecondaryBrush` code and table headers,
|
||||
`ControlStrokeColorDefaultBrush` rules, quote bars and table borders). Never a literal brush.
|
||||
- Host it in `Controls/MarkdownView` (a `FlowDocumentScrollViewer`, toolbar hidden) — not a `RichTextBox`, which is an
|
||||
editor. A `Hyperlink` there does not navigate by itself: the view handles `RequestNavigate` and decides
|
||||
(`Markdown/MarkdownLinks`).
|
||||
- `AccentTextFillColorPrimaryBrush` is the light accent in the dark theme only after `ApplicationThemeManager.Apply(…,
|
||||
updateAccent: true)` — measured 2026-10-03 in the test host, which skips it: links drew #003E92 on #202020 there and
|
||||
#73C2FF once the accent was applied as `WpfThemeApplier` applies it.
|
||||
|
||||
## Custom controls (`FpsReadout`, `TriStateChip`, sparklines)
|
||||
|
||||
@@ -176,7 +193,7 @@ var box = new Wpf.Ui.Controls.MessageBox
|
||||
var result = await box.ShowDialogAsync(); // Wpf.Ui.Controls.MessageBoxResult.Primary
|
||||
```
|
||||
|
||||
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` and ban the System one (BannedSymbols/analyzer note).
|
||||
⚠ Name clash with `System.Windows.MessageBox` — in App code, `using MessageBox = Wpf.Ui.Controls.MessageBox;` ~~and ban the System one (BannedSymbols/analyzer note)~~ *(corrected 2026-10-04: nothing bans it. Three paths use the Win32 box on purpose — the crash dialog, the startup-failure dialog and the uninstall question — because they run when the shell's dialog host cannot be trusted. Use the WPF UI one everywhere else.)*
|
||||
- Rich in-flow dialogs: `IContentDialogService` (host wired in MainWindow — a `ui:ContentDialogHost`, since 4.3.0 marks `SetDialogHost(ContentPresenter)` obsolete).
|
||||
- Transient in-app: `ISnackbarService.Show(title, message, ControlAppearance.Success, new SymbolIcon(SymbolRegular.Checkmark24), TimeSpan.FromSeconds(4))`.
|
||||
- System/tray notifications: H.NotifyIcon only (08_UI §Notifications policy).
|
||||
@@ -212,9 +229,72 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
|
||||
bar with no exit, which is exactly how the safety notices shipped (2026-09-14). `Styles/FrameLedger.xaml` carries
|
||||
the upstream template plus one presenter column; `PagesLoadTests.TheInfoBarTemplateRendersItsContent` renders both
|
||||
templates and turns red when upstream gains a presenter, which is when the copy comes out.
|
||||
- [ ] **WPF UI 4.3.0 keys its DataGrid parts' styles and defines no implicit one** (`DefaultDataGridRowStyle`,
|
||||
`DefaultDataGridCellStyle`, `DefaultDataGridColumnHeaderStyle`, handed to the grid by its implicit `DataGrid` style's
|
||||
`RowStyle`/`CellStyle`/`ColumnHeaderStyle` setters). A local `RowStyle` replaces WPF UI's; based on
|
||||
`{StaticResource {x:Type DataGridRow}}` it falls through to Aero2's row, whose `SystemColors.WindowBrush` no theme
|
||||
reaches: the import list was white text on white in the dark theme (owner's screenshot, beta.14). Base it on
|
||||
`DefaultDataGridRowStyle`. `AccessibilityTests.NoStyleIsBasedOnAnImplicitStyleTheThemeDoesNotDefine` refuses any
|
||||
`BasedOn` a type the App's dictionaries hold no style for, and `ImportReviewRenderTests` measures the rendered rows.
|
||||
- [ ] **WPF UI's `CheckBox` is `MinWidth` 120 with an 11 px padding**: in a narrow grid column it draws a sliver of the box.
|
||||
`MinWidth="0" Padding="0"` there. A `DataGridCheckBoxColumn` uses WPF's own element style, an Aero2 box — use a template
|
||||
column (`AccessibilityTests.NoDataGridCheckBoxColumn`).
|
||||
- [ ] **Every page sets `ScrollViewer.CanContentScroll="False"`.** `NavigationViewContentPresenter` changes that property's
|
||||
default to true for `Page` and, on each navigation, wraps a page that keeps it in a `DynamicScrollViewer`. A page with
|
||||
its own root `ScrollViewer` inside that wrapper has infinite height, nothing to scroll — and a stock `ScrollViewer`
|
||||
marks every wheel handled even then, so the wheel scrolled nothing on five pages until beta.14 (owner: "I have to drag
|
||||
the scroll bar"); the Logs tail grew to hold every line and never followed the end.
|
||||
`AccessibilityTests.EveryPageOptsOutOfTheDynamicScrollViewer`, `PagesLoadTests.ANavigatedPageIsNot…`.
|
||||
- [ ] **A stock `ScrollViewer` nested in a scroller takes the wheel at its ends too.** Inside a dialog use
|
||||
`ui:PassiveScrollViewer`, which hands the wheel on when it cannot scroll (`AccessibilityTests.NoPlainScrollViewerInsideADialog`).
|
||||
A `ContentDialog` whose content should not scroll as a whole sets `ScrollViewer.VerticalScrollBarVisibility="Disabled"`
|
||||
on the dialog: its content row then has the window's height, and a `*` row inside it can hold a list that scrolls alone
|
||||
(`ImportReviewPrompt`).
|
||||
- [ ] **A `ScrollViewer` moves a FIXED 48 DIP per wheel message, whatever its delta** (`ScrollViewer._mouseWheelDelta`,
|
||||
read from .NET 10.0.12; measured on a `FlowDocumentScrollViewer`: deltas of −1, −15, −120 and −360 each moved 48). It
|
||||
ignores Windows' *lines to scroll*, and a precision touchpad's small deltas each jump the whole step — a long document
|
||||
read as slow and jerky while its layout cost about a millisecond a step. `Controls/MarkdownView` handles
|
||||
`PreviewMouseWheel` itself (beta.21): the delta in proportion at Windows' lines, eased, unhandled at its ends.
|
||||
- [ ] **ScottPlot 5 zooms on every wheel and never marks it handled.** Without `Charts/ChartWheel` a wheel over a chart
|
||||
zoomed it and scrolled the page at once; a plain wheel is the page's, Ctrl+wheel the chart's, for every plot that
|
||||
`ChartTheme.Attach` registers.
|
||||
- [ ] **A scroll bar's visibility is bound inside its scroller's template** (`ComputedVerticalScrollBarVisibility`), so a style
|
||||
on `ScrollBar` or `ui:DynamicScrollBar` cannot hide it. Set the scroller's own `ScrollBarVisibility` to `Hidden` — no
|
||||
bar, and the wheel, the keyboard and touch still scroll (`ui:PassiveScrollViewer` treats only `Disabled` as "cannot
|
||||
scroll") — as `Services.ScrollBarHiding` does for `ui.hide_scrollbars` (beta.14), reaching each scroller from a class
|
||||
handler on `ScrollChanged` since beta.17 rather than from `Loaded` alone (next item).
|
||||
- [ ] **A class handler on `Loaded` is not a load hook.** WPF raises Loaded only on an element whose subtree listens for it
|
||||
with a handler of its own — an instance handler, a style's `EventSetter`, a template's trigger
|
||||
(`BroadcastEventHelper.OnBroadcastCallback` walks only into `SubtreeHasLoadedChangeHandler`;
|
||||
`FrameworkElement.ThisHasLoadedChangeEventHandler`) — and `EventManager.RegisterClassHandler` counts as none of them.
|
||||
WPF UI 4.3.0's `ToggleSwitch`, `CheckBox` and `ProgressRing` templates carry a Loaded trigger, so a scroller over those
|
||||
loads and a scroller over plain cards and text never does: `ScrollBarHiding` hid Settings' bar and not the Dashboard's
|
||||
(beta.17). To reach every instance, hook an event the element raises itself — a scroller's `ScrollChanged` comes from its
|
||||
first layout. `ScrollBarHidingTests.WpfRaisesLoadedOnlyWhereASubtreeListensForIt` keeps the behaviour visible, and a test
|
||||
that raises Loaded with `RaiseEvent` proves the handler, never that it is reached.
|
||||
- [ ] **No dialog in 4.3.0 closes on Esc.** Neither `ContentDialog.cs` nor `MessageBox.cs` at the 4.3.0 tag handles a
|
||||
key (read 2026-09-15), and `ContentDialog.CloseButtonText` DEFAULTS to "Close" — an empty string is how a dialog
|
||||
says it has no Close button. `MessageBox.Close()` is `[Obsolete("Use Close with MessageBoxResult instead")]` while no
|
||||
such overload is public; the Close button's own path is `TemplateButtonCommand.Execute(MessageBoxButton.Close)`.
|
||||
`Services/DialogKeyboard` registers one class handler on `Window` (bubbling `KeyDown`, so a dropdown's Esc wins) and
|
||||
closes through those paths; `AccessibilityTests.EscapeClosesTheOpenDialogWithNoResult` holds it (`08_UI` §Accessibility).
|
||||
- [ ] **`ui:TextBlock Appearance` keeps the theme a text was made under (4.3.0).** `TextBlock.OnAppearanceChanged` stores
|
||||
`TryFindResource(…)` in the internal `AppearanceForeground`, and `TextBlockMetadata` coerces every TextBlock's `Foreground`
|
||||
to it — the brush found when the element was made, never looked up again (read at tag 4.3.0, 2026-10-07; `main` is the
|
||||
same). After a theme switch the page on screen kept the old theme's secondary text: light grey on white, dark grey on dark
|
||||
(the owner's screenshots of Settings, beta.17). The property also inherits, so the attached form on a container pins every
|
||||
text under it. Muted text takes `Style="{StaticResource SecondaryText}"` or `TertiaryText` (`Styles/FrameLedger.xaml`,
|
||||
`DynamicResource`). `ContrastTests.NoTextBlockTakesItsColourFromAppearance` refuses every form in the App's XAML and code,
|
||||
`PagesLoadTests.EveryTextFollowsAThemeSwitch` renders every surface through a switch both ways, and
|
||||
`PagesLoadTests.WpfUisAppearanceStillKeepsTheThemeATextWasMadeUnder` turns red the day upstream follows a switch.
|
||||
- [ ] **A page in the `NavigationView` inherits nothing, its text colour included.** `NavigationViewContentPresenter` is a
|
||||
`Frame`, and `Frame` sets `InheritanceBehavior.SkipToAppNow`: the window's `Foreground` stops there, and a text that sets
|
||||
no colour falls to the TextBlock default, which WPF UI 4.3.0's `TextBlockMetadata` makes `Brushes.Black`. Cards, grids
|
||||
and controls set their own colour in their templates; the bare texts did not — every page's title and section headings
|
||||
were black on the dark window, 1.3:1 (the owner's screenshots of beta.17; beta.16's show it too). It came and went: a
|
||||
page on screen during a theme switch did take the window's new colour through the switch, and every navigation makes a
|
||||
new page that does not. Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`
|
||||
(`AccessibilityTests.EveryPageSetsItsOwnTextColour`). A check that lays a page out straight in a window measures the
|
||||
window's colour, not the App's — beta.17's theme-switch check did and was green over the black titles — so the rendered
|
||||
checks host a page in the presenter, and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface so
|
||||
hosted at ≥ 3:1 in both themes.
|
||||
+38
-21
@@ -22,7 +22,7 @@ The injected DLL. Its whole job: install hooks, write 64-byte records into a rin
|
||||
> ⚠ The CFG result was measured with **strict mode off**. A host that enables CFG strict mode does not auto-validate dynamically generated code and could still `__fastfail`. Rare, but real, and not something the fault policy can catch — see §Fault policy and `20_OPEN_QUESTIONS` §H8.
|
||||
- No STL container that allocates in a hook path. `std::atomic` and fixed arrays are fine.
|
||||
- VERSIONINFO populated (`ProductName=FrameLedger`, real company/version) — being identifiable is required by `19_SAFETY`.
|
||||
- Exports: `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
|
||||
- Exports: `FlGetLayoutVersion()` (added to this line 2026-10-04), `FlGetBuildId()`, `FlRequestUnhook()`, `FlGetStatus()`. Real names, no ordinal-only tricks.
|
||||
|
||||
## DLL entry
|
||||
|
||||
@@ -82,7 +82,7 @@ void** vtbl = *reinterpret_cast<void***>(dummySwapChain);
|
||||
MH_CreateHook(vtbl[kPresentIndex], &Hook_Present, reinterpret_cast<void**>(&Orig_Present));
|
||||
```
|
||||
|
||||
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in `HookIndices.h`.
|
||||
Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapChain1`, `ResizeBuffers = 13`) live in ~~`HookIndices.h`~~ `FrameLedger.Overlay/include/fl_dxgi_vtable.h`, shared with the harness; the D3D12 command-list slots in `fl_d3d12_vtable.h` (corrected 2026-10-04: no `HookIndices.h` exists).
|
||||
|
||||
> ⚠ **"Verified at runtime against the dummy object" is not implementable, and
|
||||
> must not be reintroduced.** A vtable slot holds a bare function pointer: no
|
||||
@@ -112,15 +112,18 @@ Index constants (`IDXGISwapChain::Present = 8`, `Present1 = 22` on `IDXGISwapCha
|
||||
> restore-only-if-unchanged rule matters, since another overlay may have
|
||||
> patched the same shared slot after us.
|
||||
|
||||
Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards); use MinHook inline hooks for flat C exports (`wglSwapBuffers`, NGX/FFX/XeSS entry points).
|
||||
~~Prefer hooking the **vtable entry** over inline-patching for COM methods (cleaner uninstall, no trampoline hazards);~~ *(corrected 2026-10-04: the Overlay swaps no vtable entry. It reads the slot off a throwaway object and MinHooks the function it points at, so one patch covers every instance (§Ray tracing); §Compare-and-restore explains why the swap is not the cleaner uninstall.)* Use MinHook inline hooks for flat C exports too (`wglSwapBuffers`, the Streamline and FidelityFX entry points ~~, NGX/FFX/XeSS~~ — NGX and XeSS have none).
|
||||
|
||||
## Hook inventory
|
||||
|
||||
Every hook must be listed here with a purpose. Anything not on this list is not allowed to exist (`19_SAFETY` review checklist).
|
||||
|
||||
> **This table is a SPECIFICATION. As of 2026-09-04 the Overlay installs TWELVE DETOURS —
|
||||
> **This table is a SPECIFICATION. ~~As of 2026-09-04 the Overlay installs TWELVE DETOURS —
|
||||
> the eight of 2026-09-03 plus four `ffxDispatch` trampolines, one per AMD module a game
|
||||
> calls — and the FidelityFX row below is the ninth ✅.** The counts differed until 2026-09-03, because a
|
||||
> calls — and the FidelityFX row below is the ninth ✅.~~** *(Corrected 2026-10-04: as of 2026-09-06 it installs up
|
||||
> to SIXTEEN — the nine `FL_HOOK_INVENTORY` rows (four Streamline including `slSetTagForFrame`, four `ffxDispatch`,
|
||||
> `ffxFsr3ContextDispatchUpscale`), the three DXGI slots, the two `ID3D12GraphicsCommandList4` methods,
|
||||
> `wglSwapBuffers` and `LoadLibraryExW`; four hooks landed without this banner moving.)* The counts differed until 2026-09-03, because a
|
||||
> row is a *capability* and a detour is a *patch*, and the FG-count row rode on the
|
||||
> evaluate detour; it has its own now, `sl.interposer.dll!slGetNewFrameToken`. The AMD row
|
||||
> is the opposite shape — **one row-family, four modules, four patches from one
|
||||
@@ -161,12 +164,12 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
> so a shipped hook missing from here is invisible to every gate. Flip the row **and this
|
||||
> banner** in the same PR that builds a hook.
|
||||
|
||||
### The one system-module detour — a hook, and the asymmetry stated
|
||||
### ~~The one system-module detour~~ The two system exports patched by name — a hook, and the asymmetry stated *(heading corrected 2026-10-04: `wglSwapBuffers` above is the other)*
|
||||
|
||||
| Hook | Purpose |
|
||||
|---|---|
|
||||
| ✅ `opengl32.dll!wglSwapBuffers` (2026-09-06, P1 item 4) | The OpenGL present hook (§Presentation). A system module, not a vendor one, so — like the row below — it is deliberately **not** in `FL_HOOK_INVENTORY` and `hookinventory-check` does not cover it; listed here so the table above and these two rows together are the whole inventory |
|
||||
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **It is the only hook on a system module, and it is deliberately not in `FL_HOOK_INVENTORY`:** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
|
||||
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **~~It is the only hook on a system module, and~~ Like `wglSwapBuffers` above it, it is deliberately not in `FL_HOOK_INVENTORY` (corrected 2026-10-04):** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
|
||||
|
||||
### Watchdog observations — not hooks, and listed here so nobody mistakes them for one
|
||||
|
||||
@@ -194,7 +197,7 @@ Every hook must be listed here with a purpose. Anything not on this list is not
|
||||
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
|
||||
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
|
||||
| ✅ **FidelityFX ffx-api: `ffxDispatch` on the FOUR modules a game calls** — `amd_fidelityfx_dx12.dll` (SDK 1.1.x monolith), `amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll`, **and `amd_fidelityfx_loader_dx12.dll`** (added the evening of 2026-09-04: three loader-shipping titles at FSR produced zero dispatches at any leaf export, so the loader is where their calls arrive) · ⏳ FSR 3.0 host route `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` / `ffxFsr3DispatchFrameGeneration` · ~~`ffxFsr2ContextCreate`~~ · ~~`ffxCreateContext`~~ | **Built 2026-09-04** (`HANDOFF` item 7c). One observer behind three trampolines reads the DESCRIPTOR the title passed — head type first, body only after the type matched a constant from the vendored MIT headers (`third_party/fidelityfx/`, tag v2.3.0): **UPSCALE** → identity (`FSR3` from the monolith, `FSR_UNVERSIONED` from the 2.x upscaler DLL, which hosts FSR 3.1 and FSR 4 behind one type) + `renderSize` → `renderW/H` (quality and sharpness `0xFF`: the dispatch carries neither) + one COUNT; **PREPARE / PREPARE_V2** → `frameID` counted on a *new* index only — this vendor's `slGetNewFrameToken`, the `fgEvaluations` producer once a title has ever prepared, with the UPSCALE count as the fallback for a title that never does; **FRAMEGENERATION** → `fgMode = FSR_FG` on that present. Rule 4: the argument of the API we hooked, never `context`, `pNext`, a command list or a resource. **Why all four:** a UE5 title ships the two leaves with no loader and calls their exports; a loader-shipping title calls the loader's export and the signed loader reaches its providers through an object, not the leaves' exports (measured: Dying Light: The Beast, KCD2, Wukong). The morning's "never the loader" rested on the export tables alone and was reversed by the run. What guards against a loader that DID re-enter a leaf's export is the K = 1 control with all four hooked and the consumer's `frames/upscale-drained`, both of which read 2× in that case. `ffxCreateContext` is deliberately NOT a row — nothing it carries fills a field the dispatch does not, and its honest family would collide with `slEvaluateFeature`'s under the installer's equality binding. The family is compound (`IDENTITY \| PARAMS \| FG_EVALUATIONS`), pinned by `static_assert`s that also bind the leaf table to the rows both ways and refuse the loader as a row. Streamline keeps precedence for the count once it has ever issued a token, so every §S31-validated title is byte-identical. Second count: the consumer prints `frames/upscale-drained`, the AMD `tokens/batch`. **FSR 3.0 — BUILT 2026-09-05 as a fifth AMD target:** `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale` (Cyberpunk's copy; named export, its own descriptor, vendored from tag **`fsr3-v3.0.4`** — the tag whose twelve `ffxFsr3*` declarations match the shipped module, not the `v1.1.4` first named). Rule 4: the detour reads `renderSize` of the descriptor the title passed and nothing else — never the context, a resource or the command list; the offset is pinned to a literal (1256) so a re-vendoring that moved it fails to compile. Same family and publish point as the four rows (`PublishFfxFamilyIfWhole` waits for a loaded host too), keyed by module in the installer; identity `FSR3` as a fact. `ffxFsr3DispatchFrameGeneration` is deliberately not a row (§H11 carries the reversal condition); the `ffx_fsr3upscaler_x64.dll` leaf is the pre-committed alternative if the facade reads silent (row B2) — never both, or `frames/upscale-drained` reads 2.00 |
|
||||
| XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute` | `outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG |
|
||||
| ~~XeSS: `xessD3D12CreateContext`, `xessD3D12Init`, `xessD3D12Execute`~~ **Closed at the census by licence, 2026-09-04** (`20_OPEN_QUESTIONS` §Scope decisions, `18_GPU_VENDOR_APIS` §Intel XeSS SDK): no hook on any `libxess*.dll` export *(corrected 2026-10-04)* | ~~`outputResolution`, `qualitySetting`, XeSS version; `xess_fg` variants for XeFG~~ |
|
||||
| ✅ **Application frames per present** (`fgEvaluations`) — **`sl.interposer.dll!slGetNewFrameToken` since 2026-09-03** | Native vs Displayed frame counts at Tier 1 — see `03_METRICS` §Frame Generation. **The producer is the frame-token export**: Streamline hands a title one token per application frame and the title must ask; the detour counts distinct tokens between two presents (pointer changes, nothing dereferenced), `FL_HOOK_FG_EVALUATIONS` is its family, and it installs on every Streamline 2 title including the ones that evaluate nothing through `slEvaluateFeature`. Rule 4: the out-parameter of an API we hooked. Premise and its gate in `03_METRICS`; pre-committed table in `20_OPEN_QUESTIONS` §S31. *The row as it stood before:* ~~NGX/SL/FFX/XeSS FG feature evaluations per present. **Built 2026-08-15 for Streamline, and MEASURED TO YIELD NOTHING ON THAT ROUTE**~~ — `slEvaluateFeature(kFeatureDLSS_G)` is never called by Cyberpunk 2077 (0 across ~14,000 batches, four FG settings), so this row installs, is honest, and counts zero; see `docs/HANDOFF.md` item 3. Built on the detour that was already there: `kFeatureDLSS_G` contributes to a saturating COUNT in the same word the feature bits live in (`fl_sl_seen.h`) rather than to a bit, because a bit collapses several evaluations between two presents into one — and under multi-frame generation that is the common case, not the edge. The row's family is therefore compound (`FL_HOOK_UPSCALER_IDENTITY \| FL_HOOK_FG_EVALUATIONS`), pinned by a `static_assert` because `hookinventory-check` reads that column as an opaque identifier. **Counts EVALUATIONS, not generated frames** — the 2026-08-14 owner ruling; the multiplier lives in `sl::DLSSGOptions`, which is only reachable by the route §2b refused. ~~Non-NVIDIA FG vendors are **deferred with a written rationale**: `amd_fidelityfx_framegeneration_dx12.dll` 3.1.5 exports only the five generic `ffx*` entry points, identical to five sibling modules, so identity is in the arguments and we have no headers~~ — **AMD has a producer since 2026-09-04** (the FidelityFX row above: the PREPARE dispatch's `frameID`, or the UPSCALE count on a title that never prepares, feeds `fgEvaluations` when Streamline has never issued a token); Intel stays at the census (`20_OPEN_QUESTIONS` §Scope decisions, by licence); the FSR 3.0 host DLL's UPSCALE (`ffxFsr3ContextDispatchUpscale`, since 2026-09-05) counts like an ffx-api UPSCALE when neither Streamline nor a PREPARE has spoken |
|
||||
|
||||
> `GetFrameStatistics().PresentCount` is **not** in this inventory and must not be
|
||||
@@ -328,7 +331,7 @@ So:
|
||||
### Memory / latency
|
||||
| Hook / call | Yields |
|
||||
|---|---|
|
||||
| `IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread) | **Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact |
|
||||
| ~~`IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread)~~ | ~~**Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact~~ **Never built; superseded 2026-10-03 (D43):** the game's memory is read from OUTSIDE the game by the Agent (`18_GPU_VENDOR_APIS` §The game process's memory), so nothing in the Overlay calls it. Only the budget would need it, and that stays open (`20_OPEN_QUESTIONS` §M11) |
|
||||
| NVAPI Reflex: hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`; call `NvAPI_D3D_GetLatency` | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
|
||||
|
||||
### Explicitly not hooked
|
||||
@@ -359,7 +362,9 @@ Vulkan gets an **implicit layer** (`FrameLedger.VkLayer`), not injection — it
|
||||
DLL**, and it compares the variable's **value**, so a stray
|
||||
`FRAMELEDGER_ENABLE_VK_LAYER=0` does not enable us. **This makes Vulkan
|
||||
Tier 1 launch-mode-only** — the Agent sets the variable when it starts an
|
||||
opted-in game, so a Vulkan title launched from Steam or GOG is not hooked.
|
||||
opted-in game, so a Vulkan title launched from Steam or GOG is not ~~hooked~~ observed by the layer *(corrected
|
||||
2026-10-04: attach mode has no Vulkan rule, so such a title gets the Overlay injected like a D3D one, and what its
|
||||
DXGI hooks record there is unverified; `kTargetIsVulkanLayered` applies to launch mode only)*.
|
||||
It is a *loading* gate, not a security gate: anything running as the user can
|
||||
set the variable.
|
||||
|
||||
@@ -487,7 +492,9 @@ struct alignas(64) FlFrameRecord { // 64 bytes exactly, static_assert'd
|
||||
uint8_t fgEvaluations; // @43 FG feature evaluations observed this frame
|
||||
uint32_t vramUsedMb; // @44 MiB, matching vramBudgetMb
|
||||
uint32_t reflexLatencyUs; // @48 0 = unavailable
|
||||
uint32_t reserved; // @52 must be zero
|
||||
uint8_t dxgiUnseen; // @52 DXGI-counted presents the hook did not see (2026-09-05; this listing
|
||||
// showed a uint32 reserved here until 2026-10-04)
|
||||
uint8_t reserved[3]; // @53..55 must be zero
|
||||
uint32_t seq; // @56 seqlock counter (see 07_IPC §Protocol rules)
|
||||
uint32_t swapchainId; // @60 which swapchain this present came through; 0 = unidentified
|
||||
};
|
||||
@@ -525,8 +532,9 @@ Field notes — each of these was a defect in an earlier revision:
|
||||
uncomputable from a pinned counter. `rays_per_pixel` divides this by output
|
||||
pixels.
|
||||
- **`maxTraceRecursionDepth`** is the second of the four stated inputs to
|
||||
`pt_confidence`. It is read at `CreateStateObject` (§Hook inventory) but
|
||||
previously had no transport to the Agent and no column to land in.
|
||||
`pt_confidence`. It ~~is~~ would be read at `CreateStateObject` (§Hook inventory) but
|
||||
previously had no transport to the Agent and no column to land in. *(Corrected 2026-10-04: `CreateStateObject` is
|
||||
not hooked, so nothing writes it yet.)*
|
||||
- **`_pad0` and `_pad1` were explicit holes and are now carrying data.** Both were
|
||||
named only so every offset could be asserted; spending them costs nothing,
|
||||
because both bytes ranges were already inside the record and already written
|
||||
@@ -561,14 +569,15 @@ Field notes — each of these was a defect in an earlier revision:
|
||||
- **SPSC lock-free ring**, capacity a power of two (default 8192 records = 512 KB), overwrite-oldest.
|
||||
- Writer/reader seqlock protocol, including the rule that the payload write must
|
||||
**exclude** the `seq` field and that `seq` is never reset: `07_IPC` §Protocol rules.
|
||||
- Header: three separate 64-byte lines before the ring — `FlShmHandshake` (write-once),
|
||||
- Header: ~~three~~ **four** separate 64-byte lines before the ring *(corrected 2026-10-04: since layout 4, 2026-09-27,
|
||||
beta.10, `FlDisplayState` at 0xC0 — Overlay-written at most every 500 ms; the ring starts at 0x100)* — `FlShmHandshake` (write-once),
|
||||
`FlWriterState` (Overlay-written: `writeIndex`, `status`, `apiMask`, `faultCount`),
|
||||
and `FlControlBlock` (**Agent**-written: `pauseRequested`, `unhookRequested`,
|
||||
`overlayEnabled`, `guardTicks`). The control flags are *not* in the Overlay's
|
||||
header — they are written by the other process, and mixing them into an
|
||||
Overlay-written line reintroduces exactly the false sharing the split exists to
|
||||
prevent. Layout is normative in `07_IPC` §A + B.
|
||||
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present.
|
||||
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)*
|
||||
- Per-frame mutable state (current upscaler, render res, dispatch counts) lives in a small struct updated by the feature hooks and *read* by the present hook; counters reset at present.
|
||||
|
||||
## The watchdog thread — the only thread we add to the game
|
||||
@@ -577,6 +586,11 @@ One thread, started on the init thread *after* the hooks are installed, sleeping
|
||||
`1000 ms` at a time. It evaluates `unhookRequested` and the `guardTicks` deadline,
|
||||
calls `StopObserving` when either fires, and **exits** once stopped.
|
||||
|
||||
> **Corrected 2026-10-04 — this describes the thread as it was first written.** Since the lazy installers landed
|
||||
> (`slEvaluateFeature`, 2026-08-09) the loop also installs feature hooks, runs the runtime census, publishes counters,
|
||||
> appends the native log, and stops on the loader detour's early-stop family; it waits on that detour's wake event with
|
||||
> a 1000 ms timeout rather than sleeping. `legal/DISCLAIMER.md` §2 says so to users since beta.12 (Disclaimer 2.10).
|
||||
|
||||
**Why it exists.** Both stops used to be evaluated only on the present path, and
|
||||
`MayObserve` is reachable only from `RecordPresent`, which is reachable only from
|
||||
the two present hooks. In a process that had stopped presenting — hung,
|
||||
@@ -600,9 +614,12 @@ we do not own; the re-scan it would have run allocates ~1.15 MB transiently; and
|
||||
it would have called `NtQuerySystemInformation` and probed the SCM from inside a
|
||||
game, which is the behavioural signature of anti-analysis code (CLAUDE.md rule 3).
|
||||
None applies to the Overlay, which is loaded by documented `LoadLibraryW` and is
|
||||
never `FreeLibrary`'d from a live process. **This thread enumerates nothing,
|
||||
never `FreeLibrary`'d from a live process. ~~**This thread enumerates nothing,
|
||||
probes nothing and allocates nothing** — it reads two `uint32`s from our own
|
||||
mapping and sleeps. That distinction is the whole justification and must survive
|
||||
mapping and sleeps.~~ *(Corrected 2026-10-04: it enumerates no process, module list or service — the rule-3 line, which
|
||||
holds — but it asks the loader for fixed module names, allocates through MinHook and, for ray tracing, creates one
|
||||
command allocator and list on the game's own D3D12 device, and writes the log file. The justification below is
|
||||
restated for that scope: what it must never start doing is scanning.)* That distinction is the whole justification and must survive
|
||||
any future change: a watchdog that starts scanning is a different object under
|
||||
rule 3.
|
||||
|
||||
@@ -645,7 +662,7 @@ Every hook body is wrapped:
|
||||
> against the injected Overlay in ctest `fl_guard` `[log]`, where every patch reads `UNHOOK_RESTORED`
|
||||
> because the harness is alone in its process.
|
||||
|
||||
`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status. **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
|
||||
~~`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status.~~ *(Corrected 2026-10-04: both reach `StopObserving` — compare-and-restore per patch as the note above says, then the status; there is no `MH_ALL_HOOKS`, no vtable entry and no ring flush. The watchdog flushes the native log on its way out.)* **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
|
||||
|
||||
### Compare-and-restore, never unconditional restore
|
||||
|
||||
@@ -714,7 +731,7 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
|
||||
|
||||
## Test harness
|
||||
|
||||
`src/native/tools/hook-harness` — a minimal D3D11 app that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
|
||||
`src/native/tools/hook-harness` — a ~~minimal D3D11~~ D3D11/D3D12 app (plus `--vulkan` / `--opengl` modes — corrected 2026-10-04) that presents at a controlled rate. It lets CI and local dev exercise hook paths with **no game and no anti-cheat surface at all** (`14_TESTING`).
|
||||
|
||||
Two choices make it run on a hosted CI runner, which is what made vtable-index
|
||||
verification a dev-machine-only affair before:
|
||||
@@ -722,8 +739,8 @@ verification a dev-machine-only affair before:
|
||||
- **WARP** (`D3D_DRIVER_TYPE_WARP`) — a software rasteriser, so no adapter is required.
|
||||
- **`CreateSwapChainForComposition`** — no `HWND`, so no dependency on a window station or an interactive session.
|
||||
|
||||
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI).
|
||||
Current modes: `--probe-vtable` (§H4, ctest `fl_vtable_indices`), `--probe-proxy` (§H5, ctest `fl_proxy_swapchain`), `--probe-unhook` (§H7, ctest `fl_unhook_preserves_foreign`), `--probe-cost` (NFR-1, measurement only), **`--probe-frames`** (ctest `fl_frame_identity` — what counts as a frame, against `GetLastPresentCount`), **`--probe-d3d12`** (ctest `fl_d3d12_acquisition` — device → command queue → swapchain), `--present N`, `--hold N`, **`--real`** and **`--plus-ui K``**, **`--vulkan --hold-presenting N`** (P1 item 3, real loader, exit 77 = cannot run here) and **`--opengl --hold-presenting N`** (P1 item 4, gdi32 `SwapBuffers` on a hidden window, Microsoft's generic renderer — runs on CI). *(Added 2026-10-04, each with its own ctest: `--probe-d3d12-vtable`, `--probe-dxr`, `--probe-dxr-inputs`, `--probe-upscaler-resolve`, `--probe-sl-abi`, `--probe-ffx-resolve`, `--probe-sl-inputs`, `--probe-sl-seen`, `--probe-dxgi-count`; and the `--hold-presenting-*` injection fixtures with `--load` / `--load-after-ms`.)*
|
||||
|
||||
> **Every present here used to carry `DXGI_PRESENT_TEST`, which submits nothing.** Measured: 500 of them leave `GetLastPresentCount` at 0 while 37 real presents move it by 37. "N presents → N records" was therefore satisfiable only by a writer counting non-frames. `--real` issues real presents; the test-present path is kept as a named mode because it is what an alt-tabbed title actually runs.
|
||||
|
||||
Still to add as the hook layer grows: Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names, a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
|
||||
Still to add as the hook layer grows: ~~Vulkan devices, RT PSO creation and ray dispatch, stub upscaler exports with the real vendor names,~~ *(the struck three exist — corrected 2026-10-04)* a PSO-compile spike generator, and a fault-injecting hook body for the self-disable path (`14_TESTING` §Integration tests).
|
||||
+51
-11
@@ -33,7 +33,7 @@ public interface IGpuTelemetrySource : IDisposable
|
||||
Implementations compose rather than compete:
|
||||
|
||||
- `BaselineTelemetrySource` (L1) — always constructed.
|
||||
- `LhmTelemetrySource` (L2) — constructed when LHM initialises.
|
||||
- `LhmTelemetrySource` (L2) — ~~constructed when LHM initialises~~ always constructed; a `Computer` that will not open disables the layer for the session (corrected 2026-10-04).
|
||||
- `NvapiTelemetrySource` (L3) — ~~constructed only on NVIDIA hardware~~ **always constructed since 2026-09-10 (P2 PR-E2)** and disables itself when the bridge DLL or the NVIDIA driver is absent, so the composite's descriptor simply omits `nvapi` and no caller has to know the vendor before composing.
|
||||
- `CompositeTelemetrySource` merges them with a fixed precedence per field (**L3 > L2 > L1**) and records which layer supplied each value.
|
||||
|
||||
@@ -52,20 +52,58 @@ Implementations compose rather than compete:
|
||||
> `LayerOf(field)` answers per field. It also applies the two-fault rule one level up — a layer
|
||||
> whose `TryRead` throws (which the port forbids) is excluded on the second throw, the others
|
||||
> untouched. (3) Identity is its own record, `GpuAdapterIdentity` (name, LUID, ids, memory sizes,
|
||||
> user-mode driver version), read once per session from DXGI; the Agent hands the handshake's
|
||||
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on. Every
|
||||
> user-mode driver version), read once per session from DXGI; ~~the Agent hands the handshake's
|
||||
> `adapterLuid` to `SelectAdapter` so samples describe the adapter the game presented on.~~ *(Corrected 2026-10-04:
|
||||
> nothing calls `SelectAdapter` outside tests. L1 stays on the first hardware adapter in DXGI's high-performance order,
|
||||
> as `HardwareSnapshotSource` does, and the handshake's `adapterLuid` is read by no managed code — so on a
|
||||
> multi-adapter machine L1 can describe an adapter the game did not present on. The game's own memory, D43, is
|
||||
> summed over every adapter and is not affected.)* **Built in beta.13:** the recorder hands the handshake's
|
||||
> `adapterLuid` to the poller at the first tick that carries one (`CaptureProgress.AdapterLuid`, noted in the
|
||||
> `.partial`), and `CompositeTelemetrySource.SelectAdapter` points L1 at it (`IGpuAdapterSelector`) and tells the layers
|
||||
> that read their own GPU its vendor (`IGpuVendorFollower`): L2 maps that vendor's GPU node instead of the first one
|
||||
> LibreHardwareMonitor lists (on a laptop often the integrated GPU), and L3 contributes nothing when the game's adapter
|
||||
> is not NVIDIA's — N/A rather than another card's temperature. **What stays first-found:** a session before the game's
|
||||
> first present, a Tier-2 session (no handshake), a game presenting through OpenGL or Vulkan (they publish no LUID), two
|
||||
> GPUs of one vendor (L2 and L3 take that vendor's first), and the session's hardware snapshot
|
||||
> (`HardwareSnapshotSource`, taken before the first present). Every
|
||||
> poller sample is stamped with QPC (`TelemetrySample.QpcTicks`), the ring's clock, and
|
||||
> `QpcClockTests` pins `Stopwatch` / `TimeProvider.GetTimestamp` to the real counter.
|
||||
|
||||
> Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here. Adapter-wide VRAM is a separate series with a different label — they answer different questions and users will otherwise think one of them is broken.
|
||||
> ~~Per-process VRAM comes from the **Overlay** (`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game), not from here.~~
|
||||
> **Corrected 2026-10-03 (beta.12, D43): the game process's memory is read from OUTSIDE the game** — §The game process's
|
||||
> memory below; the Overlay never called `QueryVideoMemoryInfo`. Adapter-wide VRAM is a separate series with a different
|
||||
> label — they answer different questions and users will otherwise think one of them is broken.
|
||||
|
||||
### The game process's memory (beta.12, owner decision D43)
|
||||
|
||||
`FrameLedger.ProcessStats.dll` — the third native facade the Agent loads beside itself (`NativeProcessStats`, after the
|
||||
guard's and the NVAPI bridge's), never into a game — reads one process's memory per call:
|
||||
|
||||
- **Video memory:** the documented performance counters `\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated
|
||||
Usage` and `\Shared Usage` (`PdhAddEnglishCounterW` with a `*` instance, so a localised counter name does not matter;
|
||||
`PdhGetFormattedCounterArrayW` after each collection), every instance naming the pid **summed** — each adapter and
|
||||
physical index the process allocated on. This is the per-process figure, so the adapter-wide rule below ("filter to our
|
||||
adapter, don't sum blindly") does not apply to it. **No handle to the game is needed.**
|
||||
- **System memory:** `GetProcessMemoryInfo` with `PROCESS_MEMORY_COUNTERS_EX2` (its `PrivateWorkingSetSize` is Task
|
||||
Manager's "Memory"), retried with `PROCESS_MEMORY_COUNTERS_EX` where the OS refuses the larger structure; an EX2
|
||||
answer whose private working set was left as written (a sentinel) or reads zero beside a nonzero working set is N/A,
|
||||
never a measured zero. It needs `PROCESS_QUERY_LIMITED_INFORMATION` and
|
||||
nothing more: the session's held handle when it has one, else a handle opened for the read and closed after it, whose
|
||||
creation time must be the watcher's (a reused pid is refused, not read).
|
||||
- **Not `D3DKMTQueryStatistics`.** It answers the same per-process segment figures, but Microsoft documents it as
|
||||
"Reserved for system use"; the counters are the documented face of the same accounting.
|
||||
- Measured on the dev box (`spike-notes` §16): one collect + read costs 0.1 ms (max 0.22 ms), a 512 MiB allocation reads
|
||||
+512.0 MiB, the private working set equals `\Process V2(…)\Working Set - Private`, 600 collections leak nothing. One
|
||||
`GameMemoryReader` per session, on the session's `fl-telemetry` thread (`TelemetryPoller`'s third source).
|
||||
|
||||
## L1 — baseline (no licence, all vendors)
|
||||
|
||||
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition — which is exactly why the Overlay reads it inside the game for `vram_proc` — and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
|
||||
- **DXGI:** `IDXGIFactory6::EnumAdapterByGpuPreference` → adapter description, LUID (matches the swapchain adapter from the Overlay handshake), dedicated/shared memory sizes. ~~`IDXGIAdapter3::QueryVideoMemoryInfo` for adapter-wide usage/budget.~~ **Measured wrong, 2026-09-09:** `DXGI_QUERY_VIDEO_MEMORY_INFO.CurrentUsage` is the *calling process's* usage by the structure's own definition ~~— which is exactly why the Overlay reads it inside the game for `vram_proc` —~~ *(corrected 2026-10-04: the Overlay never read it, and `vram_proc` was never produced — §The game process's memory)* and from the Agent it read **0 bytes** beside a 16 GB adapter. Adapter-wide usage is the PDH counter below, as this list always said; DXGI is identity only (`DxgiAdapters`, the first CsWin32 consumer in the tree).
|
||||
- **PDH performance counters** — the same source Task Manager uses, fully documented, vendor-neutral:
|
||||
- `\GPU Engine(*)\Utilization Percentage` (sum per engine type: 3D, Compute, Copy, VideoDecode)
|
||||
- `\GPU Adapter Memory(*)\Dedicated Usage`
|
||||
- `\GPU Process Memory(*)\Dedicated Usage` (cross-check against the Overlay's figure)
|
||||
- `\GPU Process Memory(*)\Dedicated Usage` ~~(cross-check against the Overlay's figure)~~ — **read since 2026-10-03
|
||||
as the game process's own figure** (§The game process's memory; the Overlay never produced one)
|
||||
- Instance names embed the LUID — parse and filter to our adapter, don't sum blindly across GPUs.
|
||||
|
||||
> **Built 2026-09-09 (PR-E1), one counter of the three:** `PdhAdapterMemoryCounter` binds
|
||||
@@ -75,8 +113,10 @@ Implementations compose rather than compete:
|
||||
> idle desktop, moving tick to tick. A machine without the counter set fails the open and the
|
||||
> field is N/A with the layer standing — not a fault. **`Utilization Percentage` is deliberately
|
||||
> not read** (`20_OPEN_QUESTIONS` §M10, decided): `LoadPct` is L2's vendor-reported load and is
|
||||
> labelled as such. `GPU Process Memory` is not read either — the Overlay's in-process figure is
|
||||
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.
|
||||
> labelled as such. ~~`GPU Process Memory` is not read either — the Overlay's in-process figure is
|
||||
> the one the pipeline stores, and a cross-check is a diagnostic, not a field.~~ **Since 2026-10-03 (D43) `GPU Process
|
||||
> Memory` IS read** — by `FrameLedger.ProcessStats.dll`, as the game process's dedicated and shared GPU memory; there was
|
||||
> never an in-process figure to cross-check.
|
||||
- **Driver version:** ~~`SetupAPI` / registry adapter properties.~~ **`IDXGIAdapter::CheckInterfaceSupport(IDXGIDevice)`** — its documented second output is the user-mode driver version for that interface, four 16-bit fields of one 64-bit value (`32.0.16.1664` on the dev box, 2026-09-09; the WARP adapter answers with the OS build). Neither SetupAPI nor the registry is walked: both need a device-instance enumeration nothing else here has a reason to carry. Feeds the hardware snapshot and the trend-chart change markers (`06_DATA_MODEL`). This is the four-part form the vendor's own tooling shows, not the marketing number (`561.09`), which only L3 knows.
|
||||
- **Optional probe, P0 evaluation only:** `D3DKMTQueryAdapterInfo` with `KMTQAITYPE_ADAPTERPERFDATA` reportedly exposes temperature, power and fan for any vendor. The D3DKMT structures are **not fully documented and have changed across Windows builds**. Treat as an experiment: if it proves stable on both Win 10 22H2 and Win 11 during P0, keep it as an L1 extra behind a capability flag; if it looks fragile, drop it and let L2 handle temperatures. Never let it be load-bearing.
|
||||
|
||||
@@ -105,7 +145,7 @@ L1 gives no temperatures on its own (unless the D3DKMT probe pans out). That is
|
||||
|
||||
`LibreHardwareMonitorLib` ≥ 0.9.6, consumed as an **unmodified NuGet package**. It already implements per-vendor GPU sensor access internally — which means the vendor-interop licensing problem is one LHM has solved upstream, under a licence that works for us. That is the entire reason this layer exists.
|
||||
|
||||
- `Computer` opened with `IsGpuEnabled` always; `IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available.
|
||||
- `Computer` opened with `IsGpuEnabled` always; ~~`IsCpuEnabled` + `IsMemoryEnabled` only when the Agent is elevated and PawnIO is available~~ nothing else, ever — the CPU temperature uses a separate `Computer` (below) (corrected 2026-10-04).
|
||||
- Poll on a dedicated thread: `computer.Accept(updateVisitor)` then read mapped sensors. Never faster than 500 ms; default 1000 ms.
|
||||
- Sensor mapping by `SensorType` + name heuristics per vendor (`GPU Core`, `GPU Hot Spot`, `GPU Memory`, `GPU Package Power`, …), kept in `SensorMap.cs` with unit tests against captured sensor-tree fixtures.
|
||||
- **P0 verification items:** (a) which fields LHM actually returns per vendor on real hardware — fill the capability matrix below — **NVIDIA filled 2026-09-03, AMD/Intel deferred (§R5/§R6)**; (b) ~~whether GPU-only usage works **without** elevation and without PawnIO (expected yes, since GPU sensors go through user-mode vendor paths, but confirm — it determines whether the default unelevated Agent has temperatures at all)~~ — **confirmed 2026-09-03, §M5 row R1**: eight fields unelevated, the same eight elevated, PawnIO never opened; (c) ~~confirm LHM's sources are not marked with MPL-2.0 Exhibit B~~ — **done, 2026-08-02: clear.** No source file applies the notice; the only repository hit is the `LICENSE` template itself, and every file we depend on carries the permissive Exhibit A. Method and evidence in `docs/spike-notes.md` §0. Re-check on every version bump, and check *source headers*, never the LICENSE file — MPL-2.0's own text contains Exhibit B as a template, so grepping the licence finds it in every MPL project ever published.
|
||||
@@ -118,7 +158,7 @@ CPU and motherboard sensors remain LHM-only, elevated-only, PawnIO-dependent, an
|
||||
> attribution above mean nothing for "how busy was the CPU". Two unprivileged Win32 calls, no process opened:
|
||||
> `GetSystemTimes` (busy = (kernel + user) − idle over the interval; kernel INCLUDES idle in that API; the first tick has
|
||||
> no interval and is null) and `GlobalMemoryStatusEx` (physical memory in use). **CPU temperature is the one privileged
|
||||
> reading**: `LhmCpuTemperatureReader.TryOpen` opens a SEPARATE `Computer` (CPU group only — L2's stays GPU-only and
|
||||
> reading**: `LhmCpuTemperatureReader.TryOpen` opens a SEPARATE `Computer` (~~CPU group only~~ CPU and memory groups, GPU off — corrected 2026-10-04 — L2's stays GPU-only and
|
||||
> unelevated by design, so the unprivileged layer's behaviour never depends on privilege) only when the process is
|
||||
> elevated AND `PawnIo.IsInstalled`; it takes the package sensor (`CPU Package`, `Core (Tctl/Tdie)`) and falls back to the
|
||||
> hottest core. **Unmeasured on real hardware**: exercised against a fake `ILhmComputer` only; the first elevated run
|
||||
@@ -338,7 +378,7 @@ as the same thing.
|
||||
|---|---|---|---|
|
||||
| GPU utilisation | **deferred by decision** (§M10, 2026-09-09) — L2's vendor-reported load is what `LoadPct` carries, labelled as such; the engine counters are not read | untested | untested |
|
||||
| Adapter VRAM | ✓ **measured 2026-09-09** — PDH `GPU Adapter Memory … Dedicated Usage`, 1301 MB at an idle desktop, RTX 5080 (`QueryVideoMemoryInfo` measured **not** adapter-wide: 0 bytes from the Agent) | untested | untested |
|
||||
| Per-process VRAM | `arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read | `arch` | `arch` |
|
||||
| Per-process VRAM | ~~`arch` for L1 — the Overlay's in-process `QueryVideoMemoryInfo` is the figure stored; `GPU Process Memory` is not read~~ ✓ **measured 2026-10-03** — `GPU Process Memory` Dedicated/Shared by pid from outside the game, +512.0 MiB for a 512 MiB buffer (`spike-notes` §16) | untested | untested |
|
||||
| Driver version | ✓ **measured 2026-09-09** — `CheckInterfaceSupport(IDXGIDevice)` → `32.0.16.1664` | untested | untested |
|
||||
| Core temp | ? (D3DKMT probe, Win 11 only — see below) | untested | untested |
|
||||
| Power | ? (D3DKMT probe) | untested | untested |
|
||||
|
||||
+115
-27
@@ -22,7 +22,7 @@ These are permanently out of scope. A PR implementing any of them is rejected re
|
||||
- Reading or writing game memory outside the arguments of APIs we hooked
|
||||
- Kernel drivers of our own
|
||||
|
||||
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature.
|
||||
The DLL ships with its real filename, a populated VERSIONINFO block (`CompanyName`, `ProductName=FrameLedger`, version), and named kernel objects that clearly say `FrameLedger`. Being identifiable is a feature. Since beta.14 (D50) the Agent — the process that injects — and the App say the same about themselves: `FrameLedger` as company and product, *FrameLedger Agent* as the Agent's description, the native binaries' copyright line (`12_BUILD` §Version, *Identity*; `tools/versioninfo-check.ps1` reads both kinds).
|
||||
|
||||
## The anti-cheat guard (hard gate)
|
||||
|
||||
@@ -51,6 +51,19 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> handle rights above are confirmed sufficient for every target this call can
|
||||
> legitimately reach.
|
||||
>
|
||||
> **Amended 2026-10-05 (owner decision D48, beta.14): one re-read, never a pass.** A member of the scan set that
|
||||
> is still being created answers `ERROR_PARTIAL_COPY` (its loader has not built a module list), and one that exited
|
||||
> between the snapshot and the open answers `ERROR_INVALID_PARAMETER`. Both refused the whole session — and at the
|
||||
> 30 s re-scan an engine's crash reporter starting as its game died, or any helper started a moment before the scan,
|
||||
> turned an ordinary exit into a "safety" unhook, which ends a user-mode exception's trial for good. Such a member
|
||||
> (`Collected::kRetry`, `fl_guard.h`) is now read once more: the pass finishes (a finding in any member still refuses
|
||||
> at once), waits `kScanRetryPauseMs` (250 ms), takes a **fresh** scan set and scans it whole. A member still unreadable
|
||||
> then refuses `kProcessUnreadable`, as before; one that has gone is not in the new set; a target that has gone leaves
|
||||
> no set, which refuses `kProcessTreeUnavailable`. **`ERROR_ACCESS_DENIED` — a protected process — is never retried**,
|
||||
> and no other answer of any source is. The sentence above stands: every failure still means REFUSE; what changed is
|
||||
> how many times "still loading" is asked before it counts as one. ctest `fl_guard` `[D48]` holds both directions,
|
||||
> against fakes and against the real source (a process created suspended, a pid with no process).
|
||||
>
|
||||
> **Launch mode (2026-09-06, P1 item 2) does not weaken this.** `FlGuardedInjectWhenReady` polls
|
||||
> the same enumeration to learn *when* the launched target has mapped a presentation runtime, and a
|
||||
> failing enumeration there means "not yet" — the poll continues. That is not a pass: the poll
|
||||
@@ -91,6 +104,23 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> inspected (`ERROR_ACCESS_DENIED`) refuses too — there is no "scanned what we
|
||||
> could" state.
|
||||
>
|
||||
> **Amended 2026-10-06 (owner decision D51, beta.15): a parent link is followed only while creation times allow it.**
|
||||
> The set is walked over one process snapshot, which links a process to its parent by pid alone, and Windows reuses
|
||||
> pids. A launcher that exits after starting its game leaves the game naming a pid that may now belong to anything:
|
||||
> until beta.15 the walk scanned whatever held it — a protected process refused the session as unreadable, a
|
||||
> blocklisted one turned the game's hooking off for good — and a cycle of reused pids sent the same processes round
|
||||
> again. A parent/child link is now cut **only when it is proven wrong**: both creation times read (`GetProcessTimes`,
|
||||
> under the module scan's own read-only right) and the child created **before** the process whose pid it names as its
|
||||
> parent, which no real child can be. A cut ancestor link ends the ancestor walk there; a cut child is not walked, nor
|
||||
> is anything below it. A time that cannot be read keeps the link, equal times keep it, and each pid is walked and
|
||||
> scanned once (`WalkScanSet`, `fl_guard_scanset.cpp`). Nothing else about the set moved: the launcher boundary, the
|
||||
> depth (16 ancestors), the frontier (512 — one more refuses) and "a member that cannot be read refuses". **The
|
||||
> residual:** creation times are wall-clock, so a clock set *backwards* between a parent's start and its child's makes a
|
||||
> real link look wrong and drops that branch from the module check; the install-folder scan and the machine-wide driver
|
||||
> and service checks do not depend on the tree. ctest `fl_guard` `[D51]` holds the walk against fixtures (a reused
|
||||
> parent, an older "child", unread times, equal times, cycles, the limits) and the real source against a child this
|
||||
> process starts.
|
||||
>
|
||||
> **One reviewed exception, decided 2026-08-03 and implemented 2026-08-04
|
||||
> (§S18), then re-keyed the same day (§S22(b)).** A module that is FrameLedger's
|
||||
> own does not trip the *fuzzy* fragment tier. The exact blocklist still applies
|
||||
@@ -217,8 +247,10 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> `NtQuerySystemInformation` is a documented-as-unsupported API and its
|
||||
> `RTL_PROCESS_MODULE_INFORMATION` layout is version-sensitive; the struct
|
||||
> offsets must be asserted, not assumed. Treat a parse failure as *refuse*,
|
||||
> never as *clean*. `20_OPEN_QUESTIONS` §S7 tracks the remaining work.
|
||||
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, updatable independently of app releases (`05_DETECTION` §Rules updates).
|
||||
> never as *clean*. ~~`20_OPEN_QUESTIONS` §S7 tracks the remaining work.~~ *(Corrected 2026-10-04: done —
|
||||
> `fl_guard_sources.cpp` asserts the layout and refuses a parse that yields non-native paths; §S7, closed, is about
|
||||
> handle rights and WOW64.)*
|
||||
3. **Rules blocklist** — `detection-rules.json` carries `anticheat.blockedExecutables` (exe names) and `anticheat.blockedStoreIds` (Steam appids etc.) for known competitive/online titles, ~~updatable independently of app releases (`05_DETECTION` §Rules updates)~~ shipped with each release; there is no rules-update path yet *(corrected 2026-10-04: `20_OPEN_QUESTIONS` §S20 feed half; `05_DETECTION` §Trust and staleness of the rules feed)*.
|
||||
|
||||
> **Both halves are wired and seeded since 2026-09-25** (owner: "as many and as strict as possible"; rules
|
||||
> `2026.09.4`). The block below is the history it replaces, kept for the reasoning.
|
||||
@@ -235,13 +267,17 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> be read (a manifest that will not open, more than 4096 of them, a listing error) refuses as `PreScanFailed`. With
|
||||
> nothing listed, nothing is read. Epic has no reader: an Epic install carries no identity to this check.
|
||||
>
|
||||
> **What is listed, and why a title list at all:** 33 Steam app ids and 33 executable names across ten families —
|
||||
> **What is listed, and why a title list at all:** ~~33~~ 34 Steam app ids and 33 executable names across ten families —
|
||||
> Valve VAC (CS2, Dota 2, TF2, Deadlock and Valve's older VAC titles), Riot Vanguard, Roblox Hyperion, Blizzard's
|
||||
> online titles ("Blizzard Warden"), Call of Duty (Activision Ricochet), NetEase (Marvel Rivals, NARAKA, FragPunk,
|
||||
> Once Human), ACE (Delta Force, Arena Breakout: Infinite), HoYoverse and EA (Battlefield 2042/6, EA SPORTS FC 25/26),
|
||||
> and since 2026-10-03 (rules `2026.10.1`, owner's list) HyperTech's **CrackProof** (Umamusume: Pretty Derby
|
||||
> `3224770`, Heaven Burns Red `1973710`, Madoka Magica Magia Exedra `2987800` — Steam ids only: no executable name
|
||||
> was verified, and a guessed one is a false refusal waiting for an unrelated game).
|
||||
> was verified, and a guessed one is a false refusal waiting for an unrelated game). **Since 2026-10-13 (rules
|
||||
> `2026.10.4`, owner decision D58) Wuthering Waves `3513350`, under ACE**, by its Steam id alone (its executable,
|
||||
> `Client-Win64-Shipping.exe`, is a name Unreal games share): its ACE sits beside the executable, where check 4 did
|
||||
> not reach until the same rules (item 4 below), and a session was hooked for 37 s on 2026-10-12 before the 30 s
|
||||
> re-scan met the driver — a machine-wide finding, which turned nothing off (`spike-notes.md` §19).
|
||||
> These are the titles whose anti-cheat leaves nothing of the game's own for checks 1, 2 and 4 to find — VAC runs
|
||||
> inside Steam, Blizzard's scanner is built into the game — or whose kernel driver loads only after the checks run.
|
||||
> CrackProof is the second kind: a Proton log of Umamusume shows its driver loaded from `C:\Windows\System32` under a
|
||||
@@ -305,7 +341,8 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> `ResolveInstallRoot`, plus check 3 on the executable's name and the install's store identity.
|
||||
|
||||
> **Implemented, and stated narrowly.** `fl_prescan.cpp` walks the target's
|
||||
> own directory (derived from its pid, never from a caller-supplied path) to
|
||||
> install root and, since 2026-10-13, its executable's own folder (both derived from its pid, never from a
|
||||
> caller-supplied path — "Which directory" below) to
|
||||
> **depth 3** — raised from 2 on 2026-08-04 (§S22, `spike-notes.md` §13), because a
|
||||
> title shipping its own kernel driver two levels below the install root was
|
||||
> invisible from where the scan starts, so the blocklist row naming it could not
|
||||
@@ -316,7 +353,7 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> nothing produced either.
|
||||
>
|
||||
> **It runs inside the chokepoint**, as the last of the four checks in
|
||||
> `EvaluateImpl`. `FlStaticPreScan` also exports it for FR-2.2's pre-launch
|
||||
> `EvaluateImpl`. ~~`FlStaticPreScan`~~ `FlStaticPreScanGame` (since 2026-09-25 — corrected 2026-10-04) also exports it for FR-2.2's pre-launch
|
||||
> question, but that export is **advisory**: it gates nothing, and a caller who
|
||||
> never asks it — or ignores the answer — changes nothing about what injection
|
||||
> allows.
|
||||
@@ -325,9 +362,11 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> could. Since 2026-08-04 `FrameLedger.Guard.dll` ships beside the **Agent
|
||||
> only** (`FrameLedger.Guard.targets`, §S18 blocker 3), so `FrameLedger.App`
|
||||
> has no `FlStaticPreScan` call site and no DLL to load. FR-2.2's advisory
|
||||
> answer reaches the UI through the Agent over IPC (`07_IPC`) when that exists.
|
||||
> answer reaches the UI through the Agent over IPC (`07_IPC`) ~~when that exists.
|
||||
> Recorded rather than quietly reworded: an advisory export with no consumer is
|
||||
> a claim about the product that is not true yet.
|
||||
> a claim about the product that is not true yet.~~ *(corrected 2026-10-04: it does — the Agent's
|
||||
> `SetHookEnabled` answer carries it since P3, `HookEnabledAck.Prescan`, and the library sweep's
|
||||
> `hook_prescan_state` since beta.8 is shown on the game's page)*.
|
||||
>
|
||||
> **Which directory.** The **install root**, resolved by walking up from the
|
||||
> executable to a known platform boundary (`steamapps\common\<X>` and
|
||||
@@ -348,19 +387,37 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> appeal. A nested executable outside a recognised store layout is therefore
|
||||
> still scanned narrowly; that residual is stated, not closed.
|
||||
>
|
||||
> **Amended 2026-10-13: the root AND the executable's folder.** The root replaced the executable's folder, and
|
||||
> that was half the answer. The walk reaches three levels below where it starts, and an Unreal executable is
|
||||
> already three below its root, so a folder **beside** the executable is four: MEASURED on Wuthering Waves, whose
|
||||
> Tencent ACE lives in `Client\Binaries\Win64\AntiCheatExpert\` (with `ACE-BASE.sys` and `ACE-CORE.sys` in it). The
|
||||
> walk from the root listed `Win64` and never opened it, so the library pre-scan read the game clean three times,
|
||||
> hooking stayed available, and the first session was hooked for 37 s until the 30 s re-scan met ACE's driver —
|
||||
> machine-wide, so nothing was turned off (`spike-notes.md` §19). Neverness To Everness keeps a second
|
||||
> `AntiCheatExpert\` beside its `HTGame.exe`, six levels down, that no walk had seen either. Check 4 now walks the
|
||||
> root and then, when the executable lives below it, the executable's own folder — same walk, same reach, its own
|
||||
> 4096-entry budget, the same matcher and the same D33 tolerance (`ScanGameFolders`). `ImageDirectory` names the
|
||||
> executable's folder and the checks resolve the root from it. Raising the reach instead was measured and rejected:
|
||||
> depth 4 still misses NTE's folder, and at depth 5 three installed titles overrun 4096 entries (Yu-Gi-Oh! Master
|
||||
> Duel: 41,251), which would refuse them. Measured across the owner's 83 Steam installs, the second walk costs at most
|
||||
> 103 entries and newly finds exactly those two folders.
|
||||
>
|
||||
> **What it does not cover.** Beyond the above, the residual is an anti-cheat
|
||||
> SDK sitting on disk whose service is not installed and whose module is not
|
||||
> loaded; checks 1, 2 and 2b already cover the rest. And today the `directories` + `files`
|
||||
> groups carry only three tokens between them, so "check 4 ran" is a much
|
||||
> groups carry ~~only three tokens~~ 67 tokens between them since 2026-09-25, plus any `.sys` by code *(corrected
|
||||
> 2026-10-04; documented names, not measured ones)*, so "check 4 ran" is a much
|
||||
> narrower statement than "this game ships no anti-cheat". Widening it needs
|
||||
> **verified** file and directory names — the seed table below deliberately
|
||||
> carries "no data yet" rows rather than guesses, because a wrong token fails
|
||||
> closed by never firing, which is a silent hole.
|
||||
>
|
||||
> **Every uncertainty refuses**, with `Reason::kPreScanFailed` rather than a
|
||||
> hit: directory absent or unlistable, either bound exceeded, a name we could
|
||||
> hit: directory absent or unlistable, ~~either bound exceeded~~ the 4096-entry bound exceeded, a name we could
|
||||
> not convert, or a reparse point — which is never followed, because a
|
||||
> junction can hide an `EasyAntiCheat/` beneath it. **Unmeasured:** how often
|
||||
> junction can hide an `EasyAntiCheat/` beneath it. *(Corrected 2026-10-13: the DEPTH bound never refused. It is a
|
||||
> reach — a folder at the last level is named and not opened, and the walk still reads as complete — which is how
|
||||
> Wuthering Waves' ACE was missed; the paragraph above is what answers it.)* **Unmeasured:** how often
|
||||
> a legitimate library trips the reparse-point rule or the 4096-entry bound.
|
||||
> That needs a real game library, and it is a false-refusal path, so it is
|
||||
> recorded rather than assumed benign.
|
||||
@@ -464,7 +521,10 @@ card is back with the finding under its disabled switch. The finding itself is o
|
||||
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
|
||||
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
|
||||
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
|
||||
exception.)*
|
||||
exception.)* *(And under D55, beta.19: the Agent removes an entry whose game is no longer installed and that has no session,
|
||||
but never one that carries a block, an exception's grant or a failed trial — the delete's own SQL refuses them
|
||||
(`SqliteGamePrune`), so an uninstall is not how a block, a grant or D38's "never again" disappears. Only the user's
|
||||
*Remove… ▸ Delete sessions too* deletes such a row, as before.)*
|
||||
|
||||
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
|
||||
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
|
||||
@@ -502,10 +562,11 @@ says so, including that a ban can arrive days later and that FrameLedger cannot
|
||||
- every finding about the game is `BlockedModule`, `AntiCheatFile` or `AntiCheatDirectory` of **one** family;
|
||||
- that family's whole footprint is user-mode — no `drivers` entry, no `services` entry and no `*.sys` among its `files`, in
|
||||
the compiled floor or the rules file (`fl::guard::FamilyIsUserModeOnly`). The floor cannot be shrunk, so data can make a
|
||||
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain and
|
||||
FredaikisAntiCheat; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
|
||||
family kernel-level and never the reverse. On today's data that leaves NetEase Yidun, AhnLab HackShield, Anybrain,
|
||||
FredaikisAntiCheat and Roblox Hyperion *(Hyperion added 2026-10-04: its rows are one module and one file; its only title
|
||||
is on the executable list, so it is never excepted in practice)*; Easy Anti-Cheat, BattlEye, ACE, NetEase Anti-Cheat, mihoyo protect, Vanguard, Ricochet and every
|
||||
other family carry a driver or a service and are never excepted;
|
||||
- no `*.sys` anywhere in the install tree — the kernel-driver rule (D30) is never excepted, whichever family a driver
|
||||
- no `*.sys` anywhere in the install tree *(within check 4's reach: three levels under the install root and, since 2026-10-13, under the executable's own folder)* — the kernel-driver rule (D30) is never excepted, whichever family a driver
|
||||
belongs to (so *Aniimo*, which unpacks `NEPKernel.sys` beside `NEP2.dll` on its first run, stays blocked);
|
||||
- the game is on no title list (`BlockedExecutable`, `BlockedStoreId` — the notorious titles are there by design);
|
||||
- ~~the ledger holds **at least two successful Tier-1 sessions** of the game: hooked, frames recorded, `exit_status = normal`
|
||||
@@ -544,7 +605,9 @@ its trial, and the App says so ("trial: 1 of 2"). During the trial **any** end o
|
||||
end is recorded with its own reason and `ac_exception_trial_failed_at` is set. While it is set the sweep writes the game
|
||||
not eligible, the Agent refuses a grant (`Refused.reason = TrialFailed`, the signal is when) and the store refuses one in
|
||||
SQL; withdrawing, a game update, *Change executable* and a twin merge all keep it. A session too short to be stored, or
|
||||
one that was never hooked, proves nothing either way and is not judged. After the trial, an end is what it was under
|
||||
one that was never hooked, is not judged by its frames or its exit — it neither counts toward the two nor fails the
|
||||
trial that way — but an end of the list above still ends the exception for good during the trial: a crash while
|
||||
hooked, however short, or a finding about the game at the start. After the trial, an end is what it was under
|
||||
D33: the exception may be made again once the sweep finds the game eligible. Deleting sessions can only lengthen a trial
|
||||
— the count is read, never stored as a grant's own fact.
|
||||
|
||||
@@ -685,10 +748,13 @@ normative documentation. Write tokens here exactly as the data must hold them.
|
||||
| mihoyo protect | `services` | name | `mhyprot2`, `mhyprot3`, `HoYoKProtect` | 2026-09-25 |
|
||||
| mihoyo protect | `files` | name | `mhypbase.dll`, `mhyprot2.sys`, `mhyprot3.sys`, `HoYoKProtect.sys` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `modules` | prefix | `SGuard`, `AntiCheatExpert` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `modules` | exact | `ACE-Base64.dll` | 2026-10-13 |
|
||||
| Anti-Cheat Expert | `drivers` | exact | `ACE-BASE.sys`, `ACE-ADVT.sys`, `ACE-GAME.sys` — **machine-wide refusal** (check 2) | seed |
|
||||
| Anti-Cheat Expert | `drivers` | exact | `ACE-CORE.sys` — **machine-wide refusal** (check 2) | 2026-10-13 |
|
||||
| Anti-Cheat Expert | `directories` | name | `AntiCheatExpert`, `AceAntibotClient` | 2026-09-25 |
|
||||
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service` | seed |
|
||||
| Anti-Cheat Expert | `services` | name | `AntiCheatExpert Protection`, `AntiCheatExpert Service`, `ACE-BASE` | seed; `ACE-BASE` 2026-10-13 |
|
||||
| Anti-Cheat Expert | `files` | name | `PGameProtectDriver_X64.sys`, `SGuard64.exe`, `SGuardSvc64.exe` | seed; `SGuard64.exe`, `SGuardSvc64.exe` 2026-09-25 |
|
||||
| Anti-Cheat Expert | `files` | name | `ACE-BASE.sys`, `ACE-CORE.sys`, `ACE-Base64.dll`, `ACE-Service64.exe`, `ACE-Setup64.exe` (measured in Wuthering Waves' folder) | 2026-10-13 |
|
||||
| EA AntiCheat | `modules` | prefix | `EAAntiCheat` | 2026-09-25 |
|
||||
| EA AntiCheat | `drivers` | exact | `EAAntiCheat.sys` — **machine-wide refusal** (check 2) | 2026-09-25 |
|
||||
| EA AntiCheat | `files` | name | `EAAntiCheat.Installer.exe`, `EAAntiCheat.GameServiceLauncher.exe`, `EAAntiCheat.GameServiceLauncher.dll` | 2026-09-25 |
|
||||
@@ -723,7 +789,8 @@ normative documentation. Write tokens here exactly as the data must hold them.
|
||||
|
||||
The "no data yet" rows are deliberately kept rather than deleted. An admitted
|
||||
gap is reviewable; a deleted row is invisible. ~~Activision Ricochet's was one of them~~ — it has data since
|
||||
2026-09-25 (below); VAC's stays until its per-title route exists.
|
||||
2026-09-25 (~~below~~ above); ~~VAC's stays until its per-title route exists~~ VAC's became per-title lists the same day,
|
||||
13 Steam ids and 8 executables *(corrected 2026-10-04)*.
|
||||
|
||||
> **Expanded 2026-09-25 (owner: "as many anti-cheats and as strict as possible").** Eleven families became
|
||||
> twenty-two and 19 entries became 74: EA AntiCheat, Activision Ricochet, NetEase Anti-Cheat, NetEase Yidun, Nexon
|
||||
@@ -770,7 +837,7 @@ gap is reviewable; a deleted row is invisible. ~~Activision Ricochet's was one o
|
||||
> *every* title, which is how a user ends up hunting for the override that
|
||||
> CLAUDE.md rule 2 says does not exist.
|
||||
|
||||
The list is data, versioned in `detection-rules.json`, expandable without a release. Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
|
||||
The list is data, versioned in `detection-rules.json`, expandable without ~~a release~~ a code change, still delivered by a release (§S20 feed half — corrected 2026-10-04). Unknown-but-suspicious modules (filename containing one of the `nameFragments` — today `anticheat`, `antitamper`, `guard`, `protect` — plus unsigned-by-known-vendor) produce a **warn-and-refuse** with a "report this to us" link rather than silently allowing.
|
||||
|
||||
> **Three corrections to that sentence, all recorded in §S19; one is now closed.**
|
||||
> It listed four fragments while the data carried five (`gameguard` was missing
|
||||
@@ -827,6 +894,15 @@ checked stays untrusted and refuses — that direction is deliberate.
|
||||
Re-run **every pre-injection check** every 30 s, for **every Tier-1 session —
|
||||
injected or layered**.
|
||||
|
||||
> **A refused re-scan of a game that has already exited is that exit (owner decision D48, beta.14).** When the re-scan
|
||||
> refuses only because it could not read the game's tree (`ProcessUnreadable`, `ModuleScanFailed`,
|
||||
> `ProcessTreeUnavailable` — never a finding) and the game itself has exited by the time the session concludes, the
|
||||
> session ends as `TargetExited`, its exit code deciding normal or crashed, with `scan_at_exit=<reason>` in its notes
|
||||
> (`Application.Capture.ExitScanRelabel`). The stop was still published to the Overlay — the game it would have stopped
|
||||
> is gone. A finding, any refusal while the game still runs, and a refusal of another check (drivers, services, the
|
||||
> pre-scan) are a safety unhook exactly as before. `CaptureSessionTests.AnUnreadableRescanOfAGameThatHasExited…` and
|
||||
> its three refusing neighbours.
|
||||
|
||||
> **This said "both the module scan and the driver scan" until 2026-08-05, and
|
||||
> the loop runs four checks, not two** (`20_OPEN_QUESTIONS` §S23-4).
|
||||
> `FlGuardEvaluate` → `EvaluateImpl` runs `CheckDrivers`, `CheckServices`,
|
||||
@@ -895,7 +971,7 @@ injected or layered**.
|
||||
> stop). Modules loaded **before** the Overlay attached are the pre-injection scan's, as always. The
|
||||
> detour supplements the poll; it replaces nothing (§S6's own ruling).
|
||||
|
||||
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
|
||||
> **This sentence used to say the hook "already exists and is currently unused", which was false.** Corrected 2026-08-04: the Overlay installs no hooks at all — `dllmain.cpp` exports one function and nothing in the tree calls `MH_CreateHook` outside a probe. *(Overtaken 2026-09-06: P1 installed the hooks and the `LoadLibraryExW` detour above; the Overlay exports four functions. Marked 2026-10-04.)* §S6 is therefore downstream of the whole P1 hook layer, not "the cheapest available improvement to the most important behavior in the product". A reader planning work off this paragraph was being told a mechanism was sitting there ready.
|
||||
|
||||
### Elevated / protected targets
|
||||
|
||||
@@ -984,7 +1060,12 @@ Consent is stored per game (`games.hook_consent_at`), **stamped by the Agent, ne
|
||||
> publishing `unhookRequested`, and keeps the Vulkan layer off by never setting `FRAMELEDGER_ENABLE_VK_LAYER`
|
||||
> on a launch.
|
||||
|
||||
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection).
|
||||
The default for every newly added game is **hooking off — Tier 2**. Nothing is ever injected because the user merely added a game — and since 2026-09-22 nothing is *opened* either: a hooking-off row's Tier-2 session is held by ~~the executable's name~~ the executable's image path in the watcher's own snapshot (2026-09-23), with no `OpenProcess`, no resolver and no gate (`04_CAPTURE` §Tier selection). *(Corrected 2026-10-03, beta.12, owner
|
||||
decision D43: such a hold now reads the game process's own memory once a second — its video memory from performance
|
||||
counters that open nothing, its system memory through a handle opened with `PROCESS_QUERY_LIMITED_INFORMATION` for the
|
||||
read and closed after it, the same least right the watcher's snapshot already opens every process with, each second. No
|
||||
handle is held, nothing is injected, the guard is not involved, and what is read is the kernel's accounting about the
|
||||
process, never its memory — rule 4 is untouched. A process that refuses even that right reads N/A.)*
|
||||
|
||||
### A moved drive is the same executable — owner ask 2026-09-22
|
||||
|
||||
@@ -1050,20 +1131,27 @@ game's executable** (path, size or mtime). If it now matches:
|
||||
§games), so this needs no schema change, and a non-null value already means
|
||||
"toggle disabled in the UI".
|
||||
3. `hook_consent_at` is **preserved**. The user did consent; the block is not a
|
||||
withdrawal of consent and must not silently require them to consent again if
|
||||
the title is later cleared.
|
||||
withdrawal of consent and must not silently require them to consent again ~~if
|
||||
the title is later cleared~~ *(corrected 2026-10-04: nothing clears a block since D22; the stamp is kept for the
|
||||
record and for a D33 exception)*.
|
||||
4. The UI shows a persistent notice, not a transient toast — the user needs to
|
||||
understand why a game they enabled stopped being captured at Tier 1.
|
||||
|
||||
A rules update that *removes* a match does **not** re-enable hooking on its own.
|
||||
A rules update that *removes* a match does **not** re-enable hooking ~~on its own.
|
||||
Turning it back on is a user action, because re-enabling silently would mean the
|
||||
rules feed can switch injection on for a game without anyone looking.
|
||||
rules feed can switch injection on for a game without anyone looking.~~ — nothing does *(corrected 2026-10-04: the block
|
||||
outlives a rules change, a game update and *Change executable*; §What a finding does to the game)*.
|
||||
|
||||
## Crash & stability safety
|
||||
|
||||
- Two crashes of the same game within 60 s of injection ⇒ hooking auto-disabled for that game, UI explains, Tier-2 takes over. Recorded in `games.hook_autodisabled_reason`. *"Crash" here is any abnormal end: since beta.8 a session whose exit code is not an exception's (End task's 1) is `normal` on its row, and this policy still counts it inside the window — a hang our hook caused, ended by the user, is the case it exists for. The row's reason says "ended abnormally twice within 60 s of injection" (`04_CAPTURE` §Crash & exit classification).*
|
||||
- **What reads as a crash changed in beta.14, in both directions** (`04_CAPTURE` §Crash & exit classification): a
|
||||
Windows report that is not a crash (a memory-leak or hang report) no longer makes one, and an engine's crash reporter
|
||||
started by a game that then left does — Unreal's crash ended with exit code 3 and read `normal`. Both feed this policy,
|
||||
the D33 lapse and D38's trial as `crashed` always has: an Unreal game that crashes under a user-mode exception ends it
|
||||
now, where before beta.14 the crash went unseen; a leak report no longer ends one.
|
||||
- The Overlay DLL self-disables after 3 faults in hook bodies (`17_HOOK_ENGINE` §Fault policy) and reports it.
|
||||
- Every hooked session writes a breadcrumb file before injection; if the game process dies before the first frame record arrives, the next run is recorded as suspect.
|
||||
- Every hooked session writes a breadcrumb file before injection~~; if the game process dies before the first frame record arrives, the next run is recorded as suspect~~ *(corrected 2026-10-04: no "suspect" mark exists; the breadcrumb is the `.partial` file, and an early death counts toward the two-within-60-s auto-disable above)*.
|
||||
|
||||
> **"Cautious mode" is deferred to v1.1 (`20_OPEN_QUESTIONS` §S12).** It was
|
||||
> described as "hooks installed, overlay drawing disabled" — but **v1 draws no
|
||||
|
||||
+40
-23
@@ -58,7 +58,7 @@ Rules for this document:
|
||||
| — | **D3D9 is not a Tier-1 API in v1.** The Overlay is x64-only; an x64 DLL cannot load into a 32-bit process, and D3D9 titles are almost entirely 32-bit | **The consequence hardened on 2026-08-28 without a word of this row changing**, which is why it is called out: that catalogue used to be "Tier 2", meaning frame times without injection. Tier 2 now measures nothing, so those titles are **unmeasurable in v1**. The VN / JRPG / older-indie catalogue is Tier 2. Reversing this means a second 32-bit Overlay **and** injector, doubling the native build matrix and adding a second struct-mirror surface. Revisit only with evidence that users care more about those titles than about the maintenance cost |
|
||||
| — | **`ci.yml` is repo-local**, not a caller stub | The ops repo's `reusable-desktop-csharp.yml` runs `dotnet` directly with no native pre-step input, and `12_BUILD` requires CI and local to run the same script |
|
||||
| — | **No `v1 → v2` migration** | Nothing shipped, so no such database exists. `0001_init.sql` creates the current schema |
|
||||
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. **Still unmeasured:** whether the Overlay loads and sees presents inside that browser process |
|
||||
| — | ~~**Multi-process titles are refused as `TargetAmbiguous` in v1**~~ — **the Chromium case is RESOLVED the same day (2026-09-03), by the vendor's own label** | Chromium-based runtimes — NW.js, Electron, RPG Maker MV/MZ, a large share of the VN catalogue — run several processes from ONE image path (browser, renderer, GPU), and *Flower in Us* refused as `TargetAmbiguous`. The presenting process is Chromium's GPU process, which owns no window, so "the one with the window" and "the parent" were both wrong picks. **What resolves it:** Chromium marks that process with `--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — **served by the kernel, no `ReadProcessMemory`, no PEB walk, `PROCESS_QUERY_LIMITED_INFORMATION` only**, which is the rule-4 line `HeldProcessHandle` already draws — and resolves only when **exactly one** readable candidate carries the flag as a whole argument. Two GPU processes (two instances), none, or any unreadable candidate still refuse. §S27 is untouched: consent is keyed on the path, every candidate is that path, the guard scans the pid chosen, and `--pid` stays forbidden. **Measured the same evening, and the first rule did not fire:** *Flower in Us* runs **six** processes — browser, `crashpad-handler`, three `utility`, `renderer` — and **no `--type=gpu-process` at all**. NW.js runs the GPU **in-process, in the browser**, which is the one process Chromium leaves untyped. Second rule added: exactly one untyped candidate, every other candidate typed, no GPU process ⇒ the browser is the target; two untyped candidates are two instances and refuse. The refusal line now prints the tree (`browser=1, renderer=1, utility=3, …`) so the next unknown shape is data rather than a bare `TargetAmbiguous`. ~~**Still unmeasured:**~~ **Measured 2026-09-04** (`spike-notes` §9, run 3): the Overlay loads and sees presents inside that browser process — Flower in Us resolved, injected, captured, 3,587 records over three swap chains *(corrected 2026-10-04)* |
|
||||
| — | **Intel XeSS / XeFG identity is closed at the census — no hook on any `libxess*.dll` export** (decided 2026-09-04, delegated by the owner) | The XeSS SDK failed `18_GPU_VENDOR_APIS` §Checklist (Intel Simplified Software License: binary-only grant, no reverse engineering, termination; headers forbid copying), so no declaration may be vendored or re-declared. The signature-free counter that seemed to survive that — an assembly thunk on a named export — still inline-patches Intel's code inside the game process, which the same licence forbids as *modification*; it would also be the only entry outside `FL_HOOK_GUARD` and a second build language, for identity alone. An Intel title therefore reports upscaler `NOT_REPORTED` and, with `libxess_fg.dll` in the census, Presented FPS under rule 6's *"MAY include generated frames"* qualifier — honest, and the same answer NGX-direct got. **Reversal condition:** Intel relicenses the headers so the checklist clears; then §H11's AMD route applies to Intel verbatim |
|
||||
| — | **A title whose upscaler or frame generation is compiled into its executable is Presented FPS + the census's qualifier, in attach mode, and that is the ceiling for IDENTITY** (recorded 2026-09-04; **two such titles found the same night — Rune Factory, and Black Myth: Wukong for its upscaling, which ships and loads the 1.1.x monolith and never dispatches to it**) | No module for the census, no export for the inventory: nothing by name. What survives static linking is behaviour on interfaces we hook — the FSR3 frame-generation proxy swapchain at *creation* (launch mode only, §S1 deferred) and queue-side cadence with no vendor name on it. ~~**No installed title has this shape**~~ — **Rune Factory: Guardians of Azuma has it**: `amd_fidelityfx_dx12.dll` ships beside the executable and is never loaded (the census has no AMD module), FSR frame generation is on, and the report read `59.99 → 119.95 (×2 FG)`, *technology not identified* — because on a UE5 title **Streamline's frame token is requested whether or not NVIDIA's features are the ones running**, so the application-frame COUNT survives static linking even though the identity cannot. The ceiling is therefore lower than this row first said: the trio with an unidentified technology, not Presented FPS alone (§H11's run table). Identity for such a title stays out of reach by name |
|
||||
| — | ~~**Tier 2 requires an elevated Agent**~~ | **CLOSED 2026-08-28 by the two-rung ladder.** The requirement came from Windows restricting ETW trace sessions; there is no ETW rung, so **no capture tier needs elevation**. Elevation is optional everywhere and buys exactly two things (CPU temperatures via PawnIO, attaching to elevated targets — ADR-9). An unelevated Agent whose Tier-1 attempt fails lands on Tier 2, which is what every unhooked session lands on regardless of privilege |
|
||||
@@ -101,7 +101,7 @@ or it becomes the next stale status claim this file exists to record.
|
||||
| S3, S5, S7, S8, S9, S10, S11, S15, S16, S17, S18, S21, S22 | ✅ **resolved** | Thirteen. Reasoning kept in place rather than deleted |
|
||||
| **S25, S26** | ✅ **resolved 2026-08-05** | The two runtime stops unreachable in a non-presenting process; occlusion probes recorded as frames |
|
||||
| **S28** | ✅ **resolved 2026-08-05** | The guard's entry points share process-wide statics; a concurrent call cleared the blocklist mid-match and every check fell through to `Allow`. Reproduced by CI, not argued |
|
||||
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj. `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
|
||||
| **S27** | ✅ **resolved, and restated 2026-08-06** | The chokepoint is the anti-cheat gate, not the consent gate. It was closed by *not building* a capture host; item 1 built one, and ~~the ✅ survives on the clause that was always load-bearing — **no injecting entry point on any SHIPPED binary**. `FrameLedger.CaptureHost` is unpublished, and `tools/package-closure-check.ps1` makes that a gate rather than a fact about today's csproj.~~ *(Corrected 2026-10-04: ✅ restated 2026-09-10 in the entry below — the shipped Agent injects by design, and the four properties in the entry hold rule 1; `package-closure-check` keeps its meaning for the CaptureHost only.)* `HookRequest` is get-only behind one factory, so this entry's own rejected synthesis no longer compiles |
|
||||
| S12 | 🅓 **deferred, rationale written** | Cautious mode → v1.1; it disabled nothing in v1. *(Marked ✅ until 2026-08-27 — same disposition, different glyph.)* |
|
||||
| **S1** | ◐ **launch mode built as "inject late" 2026-09-06 (P1 item 2); the cost is now measured per title** | `FlGuardedInjectWhenReady` polls until a presentation runtime is mapped, then runs the full guard; `dxgiPresentsBeforeHook` and the reported wait are the input the 2026-08-05 deferral lacked. The ruling "inject late vs. no launch mode" is answered by construction — inject late exists — and whether it is *preferred* per title is what the numbers decide |
|
||||
| **S13(c)** | ✅ **salvageable, and salvaged 2026-09-06** | The externally observable proxy the entry proposed is what was built; the missing input is produced by every launched session |
|
||||
@@ -110,13 +110,13 @@ or it becomes the next stale status claim this file exists to record.
|
||||
| **S23-1** | ✅ **resolved 2026-08-05** | `FlGuardBuildId` gives the Agent a build id of its own, and `ShmHandshakeValidator` performs the comparison `07_IPC` and `04_CAPTURE` both specify. Every refusal path is driven, including **both ids empty** — the shape the feature shipped in, where `"" == ""` reported `Ok` for every process on the machine |
|
||||
| **S23-4** | ✅ **resolved 2026-08-05** | `19_SAFETY` §During a session said "the module scan and the driver scan"; `EvaluateImpl` runs four. Reworded to "every pre-injection check" so it cannot go stale when a check is added, with the two omissions named — `services` is the only tier measured firing on real anti-cheat, and the pre-scan is the only one touching the filesystem |
|
||||
| **S2 part three** | ✅ **built 2026-09-06 (P1 item 3)** | In-layer supervision on the present path, landed with `vkQueuePresentKHR`; `unhookRequested` and the tick deadline both stop the layer (passthrough with the reason on the mapping), proven by a fake loader chain and a 1.5 s test-only flavour of the DLL |
|
||||
| **S4 signing** | 🅓 **deferred to P4, rationale written 2026-09-06** | Signing is a property of the feed and there is no feed (§S20); every rules file today shipped inside a release whose checksum attests it. The P4 decision (compiled-in key, detached signature, fail-closed) is written in the entry |
|
||||
| **S4 signing** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | Signing is a property of the feed and there is no feed (§S20); every rules file today shipped inside a release whose checksum attests it. The P4 decision (compiled-in key, detached signature, fail-closed) is written in the entry |
|
||||
| **S6** | ✅ **built 2026-09-06 (P1 item 1)** | The detour on `kernelbase!LoadLibraryExW` stops the Overlay from inside on an exact-floor MODULE match, within one present or one watchdog iteration, and wakes the lazy installers within milliseconds for an inventoried module; measured against the real Overlay in ctest `fl_guard` `[loader]`/`[S6]`. Exact names only — fragment and signer stay the host's 30 s scan, so the disclosure does not change |
|
||||
| **S19(a)** | ✅ **resolved 2026-08-05** | `gameguard` could never fire — `guard` subsumed it. Removed; `rules-validate` now fails when any fragment contains another, so the class cannot return. Zero coverage lost: nProtect has its own named module family |
|
||||
| **S19(c)** | ✅ **resolved 2026-09-06** | The fields are constants the schema pins and the guard never reads, because the policy is code by CLAUDE.md rule 2 and `19_SAFETY`; `rules-validate` now proves the schema rejects `action: "allow"` and `signerField: "CN"` (canary 3), so the data cannot say otherwise |
|
||||
| **S19(d) residual** | ✅ **resolved 2026-08-05** | A second canary, **derived from the shipped document** rather than hand-written, carries `nameFragments: []` and must be rejected. The entry's stated consequence was overstated and is corrected in place: the generated floor would not have disappeared, `gen-ac-floor.ps1` hard-errors and the native build fails — what was unguarded is the *schema* half |
|
||||
| **S20 feed half** | 🅓 **deferred to P4, rationale written 2026-09-06** | **FR-7.3 stays unmet and written as unmet**: the fetch needs a shipped Agent, §S4's signing and the privacy policy's rows, all P4; until then a rules edit ships with the next release, checksum-attested |
|
||||
| **S23-3** | 🅓 **deferred to P3, rationale written 2026-09-06** | `08_UI`'s refusal notice is wrong in the commonest case; the requirement reaches `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI — a string with no view would read as done |
|
||||
| **S20 feed half** | 🅓 **deferred ~~to P4~~, unscheduled — P4 closed without it (corrected 2026-10-04); rationale written 2026-09-06** | **FR-7.3 stays unmet and written as unmet**: the fetch needs a shipped Agent, §S4's signing and the privacy policy's rows, all P4; until then a rules edit ships with the next release, checksum-attested |
|
||||
| **S23-3** | ~~🅓 **deferred to P3, rationale written 2026-09-06**~~ ~~🔴 **open: P3 shipped the refusal UI without it**~~ ✅ **closed in beta.13** — the events carry the guard's own reason and a `BlockedService` / `BlockedDriver` notice says the family is running on this PC (`08_UI` §Safety events) *(it was 🔴 from 2026-10-04: a machine-wide notice still read "… was detected in this game")* | `08_UI`'s refusal notice is wrong in the commonest case; the requirement reaches `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI — a string with no view would read as done |
|
||||
| **S23-5** | ✅ **resolved 2026-08-05** | Closed the way §S23-4 closed the same class — by **removing** the restatement, not correcting it — and `rules-validate` now fails when any `$comment` enumerates checks again. The rule's own first version was scoped to the wrong object and could not fire; it now walks every `$comment` and fails if it finds none |
|
||||
| **S23-6** | ✅ **closed 2026-09-06** | `license-check` binds `THIRD_PARTY_NOTICES` bidirectionally, and the accuracy blocks are now ONE text — `legal/ACCURACY.md`, embedded verbatim in `README.md` and `DISCLAIMER.md` §4, gated by `tools/accuracy-check.ps1` (self-tested both directions). Truth stays a human's job; drift between copies no longer is |
|
||||
| **S23-2** | 🚫 **owner only — no PR can close it** | `Rules / validate` is **not** a required status check on `main`. **Re-verified against the live branch protection 2026-08-05**, not repeated from the entry: `required_status_checks.contexts` is exactly `["check", "analyze (csharp, none)", "analyze (cpp, manual)"]` (`strict: true`, `enforce_admins: true`, `required_linear_history: true`). The `validate` job is path-filtered and `pull_request`-only, so a red removal check does not block the merge button. **The gate that exists to make the anti-cheat blocklist un-removable is advisory.** This is a branch-protection setting |
|
||||
@@ -137,7 +137,7 @@ either work or a rationale written down:
|
||||
correction. **S30 closed 2026-08-15 and S31 opened 2026-08-20**, and this bullet went on
|
||||
naming S30 until 2026-08-27 — so the total below stayed right by coincidence rather than
|
||||
by count.)*
|
||||
- **three ⏳** — S2 part three, S4 signing, S23-3
|
||||
- **three ⏳** — S2 part three, S4 signing, S23-3 *(S2 part three built 2026-09-06 and S23-3 closed in beta.13 — noted 2026-10-04; S4 signing stays deferred)*
|
||||
- ~~two ◐~~ ~~**three ◐**~~ **two ◐ (2026-09-04)** — S14, S23-6. ~~**S31**~~ *(moved out of ❓ on 2026-08-27 when its test landed on row P2; **resolved 2026-09-04** when the token count landed on row P1 with `tokens/batch = 1.00` — the question answered by a second count rather than by an oracle)*
|
||||
- **one 🔴** — S29, added by the audit that produced this recount; **five of its seven
|
||||
findings are now closed**, and the residue is (a) the ungated managed drain and (d) the
|
||||
@@ -1495,7 +1495,7 @@ there is no way to point the layer at a different rules file (§S3), so without
|
||||
it the test silently skipped on any machine that had not run the product — and a
|
||||
ctest that always skips is a gate that cannot fail.
|
||||
|
||||
### ◐ Part three: mid-session guard inside a layered process — decided, half built
|
||||
### ~~◐~~ ✅ Part three: mid-session guard inside a layered process — decided, ~~half built~~ built 2026-09-06 (heading corrected 2026-10-04)
|
||||
|
||||
> #### ✅ Built 2026-09-06 (P1 item 3), in the PR that added the present hook — as the deferral below said it would be
|
||||
>
|
||||
@@ -1557,7 +1557,8 @@ the layer already has — every uncertainty resolves to inert.
|
||||
> file and exits. What is built and tested is the *counting discipline*: the tick
|
||||
> counts evaluations rather than seconds. What is not built is the supervision.
|
||||
> A reader ticking this off as delivered would then find `07_IPC` §Supervision
|
||||
> loss unimplementable, which is exactly what happened.
|
||||
> loss unimplementable, which is exactly what happened. *(Overtaken in P2: `ShmRingReader` publishes the tick from
|
||||
> `GuardSupervisor`, which `CaptureSession` runs on every Tier-1 session. Marked 2026-10-04.)*
|
||||
|
||||
**✅ The Agent half's counting discipline is built and proven.** `GuardSupervisor`
|
||||
(`FrameLedger.Application`) computes what will become `guardTicks`, and the load-bearing property
|
||||
@@ -1812,6 +1813,12 @@ refuses too. Sibling *services* are covered by name via the rules data rather
|
||||
than by tree walking, which is more reliable. The runtime re-scan recomputes the
|
||||
set rather than caching it.
|
||||
|
||||
**Amended 2026-10-06 (D51, beta.15).** The set's parent links come from a snapshot that links by pid alone, and pids
|
||||
are reused: the walk followed a launcher's pid after the launcher had exited and something else had taken it, and a
|
||||
cycle of reused pids was walked round. A link is now cut only when creation times prove it wrong (the child created
|
||||
before its named parent); an unread time keeps it, and each pid is walked once. `19_SAFETY` §Pre-injection checks item 1
|
||||
carries the rule and its one residual — a clock set backwards between a parent's start and its child's.
|
||||
|
||||
<details><summary>The question as originally recorded</summary>
|
||||
|
||||
Found 2026-08-02. Not previously recorded anywhere, and it changes the guard's
|
||||
@@ -2668,19 +2675,21 @@ disproved:
|
||||
which used to claim a bump check that does not exist.
|
||||
- **`trustedSigners` is the one allow-widening field a foreign file still
|
||||
controls.** Deliberately not floored, because flooring an allowlist has the
|
||||
wrong polarity. Inert today — `IsTrustedSigner` has no production call site
|
||||
while §S19(b) is deferred — and **live the moment the signer half is wired**,
|
||||
wrong polarity. ~~Inert today — `IsTrustedSigner` has no production call site
|
||||
while §S19(b) is deferred — and~~ **live the moment the signer half is wired** *(corrected 2026-10-04: wired since
|
||||
§S19(b), 2026-09-06, and bounded by `IsCompiledTrustedSigner`)*,
|
||||
which makes gating it a prerequisite of §S19(b) rather than of this item.
|
||||
- **This is what arms the Vulkan layer's self-scan for the first time.** `layer.cpp`
|
||||
§S2's second half could only ever answer "inert" while the file never existed.
|
||||
It is now reachable, on a machine where the file is present. The layer still
|
||||
It is now reachable, on a machine where the file is present. ~~The layer still
|
||||
intercepts nothing (`vkQueuePresentKHR` is P1), so nothing observable changes
|
||||
yet — recorded here so it is not discovered as a surprise when the present hook
|
||||
lands.
|
||||
lands.~~ *(Corrected 2026-10-04: `vkQueuePresentKHR` is intercepted since 2026-09-06, §S2 part three.)*
|
||||
- **A seed replacement is a rules update in FR-2.3's sense**, and the obligation
|
||||
attached to that event — re-run the pre-scan, force-disable a game that has
|
||||
started matching — is unimplemented. There is no `games` table yet, so there is
|
||||
nothing to write; named here so whoever builds persistence has an anchor.
|
||||
started matching — ~~is unimplemented. There is no `games` table yet, so there is
|
||||
nothing to write; named here so whoever builds persistence has an anchor.~~ *(corrected 2026-10-04: built —
|
||||
`UpdateRules` wakes `AntiCheatPreScanSweep`, beta.8, keyed per rules version by schema 0010.)*
|
||||
|
||||
### S21 ✅ · The hard gate's data source was caller-nameable, and its completeness floor never read the values — **closed**
|
||||
|
||||
@@ -3080,7 +3089,7 @@ required contexts are exactly `check`, `analyze (csharp, none)` and
|
||||
the gate that exists to make the anti-cheat blocklist un-removable is advisory.
|
||||
Fixing it is a branch-protection change, i.e. the owner's, not a code change.
|
||||
|
||||
**3. 🅓 Deferred to P3, rationale written 2026-09-06 — `08_UI` describes a refusal notice that is wrong in the commonest case.** *(The requirement below must reach `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI, and not before: there is no UI to be wrong in yet, and a `.resx` string with no view is the kind of fix that reads as done. The spike log carries the measurement; this line is the reminder.)* It
|
||||
**3. ~~🅓 Deferred to P3, rationale written 2026-09-06~~ ~~🔴 Open~~ ✅ Closed in beta.13 (`08_UI` §Safety events: a driver or service is said as running on this PC) — P3 built the refusal UI without it (corrected 2026-10-04: `SafetyNotices.RefusalText` formats every named refusal as "… was detected in this game", so the measured case below still reads wrong) — `08_UI` describes a refusal notice that is wrong in the commonest case.** *(The requirement below must reach `08_UI` and the `Safety_*` keys in the PR that creates the first refusal UI, and not before: there is no UI to be wrong in yet, and a `.resx` string with no view is the kind of fix that reads as done. The spike log carries the measurement; this line is the reminder.)* It
|
||||
promises "the specific signal named in plain language". Measured (`spike-notes`
|
||||
§13): while any Easy Anti-Cheat title is running, **every** target — including a
|
||||
freshly spawned, unrelated process — refuses with `BlockedService` naming
|
||||
@@ -3968,7 +3977,7 @@ make us miss the present.
|
||||
Needs a real Streamline/DLSS-G title, ideally with RTSS and the Steam overlay
|
||||
also active (`spike-notes.md` §Environment — that machine already has both).
|
||||
|
||||
### H6 · D3D12 command-list hooks count recorded, not executed, work
|
||||
### H6 ✅ · D3D12 command-list hooks count recorded, not executed, work — **answered 2026-08-20 with the RT hooks** *(marked 2026-10-04: per-present atomics drained once per present; the unit is "recorded between two presents", `03_METRICS` §RT)*
|
||||
|
||||
`DispatchRays`, `BuildRaytracingAccelerationStructure` and pipeline creation are
|
||||
recorded into command lists, possibly on many threads, possibly re-executed or
|
||||
@@ -4277,6 +4286,11 @@ this item defers, and whether generated presents reach our vtable is what §H5 t
|
||||
|
||||
### H10 · Per-process VRAM thread inside the game process
|
||||
|
||||
🅓 **The usage half is answered from outside the game — 2026-10-03 (beta.12, owner decision D43); the budget half is
|
||||
deferred with §M11.** The game's dedicated and shared GPU memory are read by the Agent from the `GPU Process Memory`
|
||||
counters (`18_GPU_VENDOR_APIS` §The game process's memory), so no thread and no DXGI call is added inside the game for
|
||||
them. What only an in-process call could give is the budget, and nothing reads it. *(The question as it stood:)*
|
||||
|
||||
`17_HOOK_ENGINE` §Memory calls `QueryVideoMemoryInfo` "once per second from our
|
||||
own thread". Spawning a thread inside a host process we do not own is a heavier
|
||||
footprint than the rest of the design's posture, and DXGI calls off the render
|
||||
@@ -4300,10 +4314,11 @@ instead, which needs no thread at all.
|
||||
| M2 ✅ | ~~Does the pinned console binary still exist, run unelevated, and emit the 2.x column set?~~ | **Answered, then closed 2026-08-27.** It exists (2.5.1, 956,768 bytes, SHA256 `9BEC…A191`, **no VERSIONINFO at all**); it does **not** run unelevated (exit 6 — the account is in neither Administrators nor Performance Log Users, and the running `PresentMonSharedService` does not help because the console starts its own session); and the 2.x column set **is measured** — 24 columns, `spike-notes` §11. The parser ate three real CSVs and resolved `FrameType` correctly against a first column literally named `Application`. Closed because the binary is dropped, and kept in full because every one of those facts cost a measurement |
|
||||
| M5 ✅ | **Do LHM GPU sensors work unelevated, without PawnIO?** **YES — measured 2026-09-03, row R1 of the pre-committed table below**, NVIDIA RTX 5080 / 616.56 / LHM 0.9.6: eight fields unelevated (core and memory temperature, load, VRAM used, core and memory clock, package power, fan), the identical eight in the elevated control, PawnIO never opened. The three user-facing sentences stand. Numbers in `spike-notes` §10. *(The row as it stood while open follows, unchanged.)* This decides whether the default unelevated Agent has temperatures at all, and therefore how ADR-9 reads to users. **SEVERITY PROMOTED 2026-08-28, and the promotion is the point.** It used to decide how a design note read. It now decides whether a **user-facing claim is true**: the two-rung ladder says a Tier-2 session records duration and hardware telemetry, and that sentence is heading for `README`, the consent dialog and `legal/EULA.md`. If LHM needs elevation for GPU sensors, then the DEFAULT Agent's Tier-2 session is **duration only** and every one of those documents is wrong. Until it is measured, all three are worded *"whatever hardware telemetry this machine can provide"* — honest under either outcome, at the cost of vagueness. `18_GPU_VENDOR_APIS` §P0(b) already specifies the test and the dev box can run it |
|
||||
| M6 ✅ | ~~Elevation-free Tier 2~~ | **Closed by decision 2026-08-27.** Half was answered on 2026-08-20 in the direction nobody expected: `PresentMonSharedService` is installed and `Running` as LocalSystem and the console **still** fails, because it starts its own trace session. The other half — whether `Performance Log Users` suffices without admin — stays unmeasured and now has no subject. **The elevation question does not disappear with the tool**: ETW trace sessions are restricted by Windows, not by PresentMon, so whatever §G chooses inherits it. Re-ask it there |
|
||||
| M7 ✅ | ~~`18_GPU_VENDOR_APIS` §Runtime policy says telemetry is never read from the game process, but `17_HOOK_ENGINE` reads per-process VRAM and Reflex latency there. Reconcile the wording — the rule means "no vendor SDK polling loops in the game", not "no measurement in the game"~~ **Closed 2026-09-09 (PR-E1) by the code taking exactly that shape.** The rule is *no telemetry polling loop in the game*: the one 1 Hz loop is `TelemetryPoller` on the Agent's `fl-telemetry` thread, and it reads L1/L2/L3 only. Per-process VRAM stays an in-process read on the present path (`vram_proc`, `17_HOOK_ENGINE`), and PR-E1 measured why that must be so: `IDXGIAdapter3::QueryVideoMemoryInfo`'s `CurrentUsage` is the *calling process's* figure — 0 bytes from the Agent — so it is a measurement only where the game is. Adapter-wide usage is L1's PDH counter. §Runtime policy's sentence stands as written; this row is the reconciliation |
|
||||
| M7 ✅ | ~~`18_GPU_VENDOR_APIS` §Runtime policy says telemetry is never read from the game process, but `17_HOOK_ENGINE` reads per-process VRAM and Reflex latency there. Reconcile the wording — the rule means "no vendor SDK polling loops in the game", not "no measurement in the game"~~ **Closed 2026-09-09 (PR-E1) by the code taking exactly that shape.** The rule is *no telemetry polling loop in the game*: the one 1 Hz loop is `TelemetryPoller` on the Agent's `fl-telemetry` thread, and it reads L1/L2/L3 only. Per-process VRAM stays an in-process read on the present path (`vram_proc`, `17_HOOK_ENGINE`), and PR-E1 measured why that must be so: `IDXGIAdapter3::QueryVideoMemoryInfo`'s `CurrentUsage` is the *calling process's* figure — 0 bytes from the Agent — so it is a measurement only where the game is. **Corrected 2026-10-03 (beta.12, D43): "only where the game is" holds for `QueryVideoMemoryInfo` and not in general** — the `GPU Process Memory` performance counters give any process's dedicated and shared GPU memory from outside it, with no handle, and the Agent reads them since that day (`18_GPU_VENDOR_APIS` §The game process's memory; `spike-notes` §16). The in-process read was never built. Adapter-wide usage is L1's PDH counter. §Runtime policy's sentence stands as written; this row is the reconciliation |
|
||||
| M8 ✅ | ~~The `GpuSample` type has no latency field, yet L3 is credited with Reflex/PC latency. Latency is per-frame and arrives via the ring, not the 1 Hz sample. Fix the layering description~~ **Closed 2026-09-09 (PR-E1): the description now matches the type.** `GpuSample` has no latency field by design (its own remarks said so since 2026-09-03), `TelemetrySample` carries a 1 Hz reading stamped with QPC, and per-frame latency is `FlFrameRecord.reflexLatencyUs` in the ring. The §L3 table row "Reflex / PC latency" is an *in-process hook fact* the Overlay records (`SetSleepMode` / `SetLatencyMarker`, `17_HOOK_ENGINE`), never a poller field; `NvapiTelemetrySource` (PR-E2) will not call `NvAPI_D3D_GetLatency` |
|
||||
| M9 ✅ | **Closed 2026-08-02 by a decision.** The old file/module detection does not exist in this repository and the owner confirmed there is no copy elsewhere, so **"build a minimal static-hint detector as the measurement baseline" is now P0 item 3** (`15_ROADMAP`). It needs no guard and no injection. Until it exists, ADR-7's headline claim stays out of the README rather than being asserted unmeasured |
|
||||
| M10 ❓ | **§CPU — is the CPU temperature this build reads the right sensor, and does it read at all on the owner's machine?** `LhmCpuTemperatureReader` (2026-09-21) opens a CPU-only LibreHardwareMonitor `Computer` when the Agent is elevated AND `PawnIo.IsInstalled`, takes the package sensor (`CPU Package` / `Core (Tctl/Tdie)`) and falls back to the hottest core. It was written against LHM's sensor names and a fake `ILhmComputer`; **no elevated run with PawnIO has been taken.** | **The measurement is one session:** Agent elevated, PawnIO installed, a five-minute capture with HWiNFO or Ryzen Master open beside it. Pre-committed: `max_cpu_temp` within 3 °C of the reference's package peak → keep; a core sensor picked where a package sensor exists, or a reading tens of degrees off (a distance-to-TjMax sensor mistaken for a temperature) → fix `Pick` and re-run; nothing read at all → `cpu_temp` stays N/A and `legal/ACCURACY.md` says processor temperature is not measured. CPU **load** and memory are not in question: `TheRealCountersAnswerOnThisMachine` reads them on every gate run. |
|
||||
| M11 🅓 | **The game's VRAM budget and `budget_exceeded_pct` (FR-4.5's second half), 2026-10-03.** D43 reads the game's usage from outside (the `GPU Process Memory` counters); the budget the OS grants the process is what DXGI's `QueryVideoMemoryInfo` returns to the *calling* process (§M7), so only an in-process call — the Overlay's background thread, which today only checks for a stop — or `D3DKMTQueryStatistics`' `PROCESS_SEGMENT_GROUP` query (documented "Reserved for system use") could read it. **Deferred by decision:** neither is built; `vram_budget_exceeded_pct` stays NULL and the budget N/A, and the in-process route would change what the Disclaimer says the Overlay's thread does. Reopening it needs that decision, not a measurement. | — |
|
||||
| M10 ✅ | ~~PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly~~ **Decided 2026-09-09 (PR-E1): L1 does not read the engine counters at all.** `LoadPct` is L2's vendor-reported `GPU Core` load (measured ✓ on NVIDIA, §M5 row R1) and is labelled *GPU load (vendor)* wherever it is shown; on a machine without L2 the field is N/A, never a sum that is not the number the user expects. What L1 does read from PDH is one counter, `\GPU Adapter Memory(luid_…_phys_0)\Dedicated Usage`, bound by LUID — the figure Task Manager labels "Dedicated GPU memory", measured 1301 MB at an idle desktop on the RTX 5080. Reopening this needs a measurement of `max(engine)` against Task Manager's own number, not a decision |
|
||||
|
||||
#### §M5 — the decision table, pre-committed 2026-09-03 BEFORE the first run
|
||||
@@ -4350,13 +4365,13 @@ Each of these is referenced by an existing doc but specified nowhere.
|
||||
|
||||
| Area | What is missing | Referenced by |
|
||||
|---|---|---|
|
||||
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) ~~elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator~~ **closed 2026-09-27 (beta.10, owner decision D34): chosen** — `capture.run_elevated`, a UAC prompt at every Agent start, the logon task's Agent asking through its own prompt, and with the option off an administrator's App starts the Agent with the shell's token (`01_ARCHITECTURE` ADR-9). "How elevation is requested and persisted" is that: requested by the prompt, persisted as one settings row and never as a task's run level | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
|
||||
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** What stays open here is the pipe's use of the guid (P3) | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
|
||||
| **Agent lifecycle** | Scheduled-task definition, start-at-logon, how elevation is requested and persisted, what "Repair" repairs. **`--serve` exists since 2026-09-10 (P2 PR-F)** — a Generic Host around the watcher, stopped by Ctrl+C with a 15 s finalize grace — and `--install-task` / `--uninstall-task` answer "not implemented in P2"; the task definition and start-at-logon are what stays open *(corrected 2026-10-04: built in P3 PR-8b — `LogonTask` behind both flags, and start-with-Windows as the HKCU Run value)*. **One Agent per data folder since 2026-09-17** (`01_ARCHITECTURE` §Lifecycle: `AgentInstanceLock`, exit 10; beta.1 ran four after an elevated App was refused by the pipe). **Still open from that morning:** (1) the ring's single consumer is enforced across data folders only by `NoSecondRingReaderTests`' source sweep — a developer's `--console --data-dir` capture beside the installed Agent can still attach a second reader to one game's `Local\FrameLedger.Ring.<pid>`, and a runtime claim beside the mapping would close it; (2) ~~elevation is inherited, not chosen — an App started as administrator starts an elevated Agent, which injects and writes the ledger as administrator~~ **closed 2026-09-27 (beta.10, owner decision D34): chosen** — `capture.run_elevated`, a UAC prompt at every Agent start, the logon task's Agent asking through its own prompt, and with the option off an administrator's App starts the Agent with the shell's token (`01_ARCHITECTURE` ADR-9). "How elevation is requested and persisted" is that: requested by the prompt, persisted as one settings row and never as a task's run level | `08_UI` Settings, `11_UPDATER`, `12_BUILD` flags |
|
||||
| **Session identity** | ~~`sessions` has no GUID column, yet `SessionStarted`/`StopSession`/`.partial` files are all keyed by `sessionGuid`.~~ **`sessions.session_guid` (UNIQUE) exists since 2026-09-09 (P2 PR-B), with `qpc_epoch` / `qpc_frequency` beside it.** ~~Still open: the `.partial` file format is undefined, and it is the crash-recovery artifact — PR-D's, pre-committed in HANDOFF §P2 (CRC-framed append-only chunks, the valid prefix wins)~~ **Built 2026-09-10 (P2 PR-D): `06_DATA_MODEL` §The `.partial` file, `PartialSessionFile` + `PartialRecovery`, killed at every byte in the merge gate.** ~~What stays open here is the pipe's use of the guid (P3)~~ *(built in P3 PR-1/1b: the session events and `StopSession` carry `SessionGuid` — corrected 2026-10-04)* | `07_IPC`, `04_CAPTURE`, `06_DATA_MODEL` |
|
||||
| ~~**Settings registry**~~ | ~~The `settings` table is key/value with no key list, defaults, types, or validation — and no message for the UI to push a changed setting to the Agent.~~ **Decided 2026-09-13 (HANDOFF §P3 decision D16)**: the key list with defaults and ranges, and *no* push message — the Agent re-reads its keys at each session start. **Built the same day (P3 PR-3):** `06_DATA_MODEL` §Settings registry (12 keys), `Application.Settings.SettingsRegistry` + `RegisteredSettings` (validating writes, tolerant reads), `SettingsRecorderPolicy` resolving `capture.min_session_s` / `telemetry.interval_ms` / `retention.raw_sessions_per_game` at each session start. **Row closed** | `06_DATA_MODEL`, FR-10 |
|
||||
| **Error taxonomy** | `07_IPC` lists `CaptureError` codes; no canonical mapping to resx keys and user-facing text, though `09_I18N` requires safety strings to be reviewed as legal text | `07_IPC`, `09_I18N` |
|
||||
| ~~**Threading model**~~ | ~~Which component owns which thread, UI-thread rules, and how the 1 Hz telemetry poller, 10 Hz drain and pipe reader interact~~ **Answered 2026-09-09 (P2 PR-C): `04_CAPTURE` §Threading model** — four threads, one owner per shared object, the pipe reader named as one more producer. This row was not struck when the section was written; struck 2026-09-13. What is still unspecified is the UI thread's own rules, which is `08_UI`'s in P3 | `04_CAPTURE`, `18_GPU_VENDOR_APIS` |
|
||||
| **Pipe/shm security** | Stated as policy ("DACL granting the current user's SID") but not as implementable SDDL, nor who creates the objects with what rights. The shm half is built (`fl_shm_host.h`, the Overlay creates the section under the current user's SID); the pipe half is **built 2026-09-13 (P3 PR-1, HANDOFF §P3 decision D11)**: `D:P(A;;GA;;;<user>)(A;;GA;;;BA)` (with the owner `O:<user>` stated since 2026-09-17, `07_IPC` §C) handed to `CreateNamedPipe` with `PIPE_REJECT_REMOTE_CLIENTS`, and the client's token user compared by impersonation on its first frame (`Infrastructure.Ipc.PipeAccessControl`, pinned by `PipeServerClientTests` including the refused stranger). **Row closed** | `07_IPC` |
|
||||
| ~~**Legal doc versioning**~~ | ~~FR-11 re-shows documents "when a document version increments". Nothing says where the current version lives, who writes `legal_acceptance.version`, or how the markdown is rendered in-app~~ **Answered 2026-09-14 (P3 PR-9):** the version is the document's own `**Version:**` line, read from the copy embedded in the App at build (`App.Services.LegalDocuments`); the App writes `legal_acceptance.version` on the one Accept and re-shows any document whose embedded version differs from its row; the markdown is shown as text with authoring comments stripped, not rendered (`08_UI` §First-run flow built note) | FR-11, `06_DATA_MODEL` |
|
||||
| ~~**Legal doc versioning**~~ | ~~FR-11 re-shows documents "when a document version increments". Nothing says where the current version lives, who writes `legal_acceptance.version`, or how the markdown is rendered in-app~~ **Answered 2026-09-14 (P3 PR-9):** the version is the document's own `**Version:**` line, read from the copy embedded in the App at build (`App.Services.LegalDocuments`); the App writes `legal_acceptance.version` on the one Accept and re-shows any document whose embedded version differs from its row; ~~the markdown is shown as text with authoring comments stripped, not rendered~~ the markdown is shown with authoring comments stripped and, since beta.12, rendered (`08_UI` §Menu, *Documents are rendered*; §First-run flow built note) | FR-11, `06_DATA_MODEL` |
|
||||
| **Accessibility / DPI** | NFR-9 states requirements; no design anywhere | NFR-9, `08_UI` |
|
||||
| **Uninstall / data deletion** | One Velopack clause. No in-app "delete all my data", despite the privacy position | `12_BUILD`, `legal/PRIVACY_POLICY.md` |
|
||||
| **Cover art** | Appears in the schema, the data directory and the UI; nothing says where it comes from or the licence position on downloaded store art | `06_DATA_MODEL`, `05_DETECTION` |
|
||||
@@ -4371,7 +4386,9 @@ the guard is **item 0**, the Vulkan passthrough test is **item 1**, the two
|
||||
licence checks were run first and came back clear (`spike-notes.md` §0), and
|
||||
P0's exit criteria no longer import P2 work — the FPS-impact measurement moves
|
||||
to the end of P1, while the harness-level per-present cost (no game, no Agent,
|
||||
no drain) stays in P0. Items 5–9 below are still open.
|
||||
no drain) stays in P0. ~~Items 5–9 below are still open.~~ *(Corrected 2026-10-04: 5 and 6 are deferred, 🅓 below; 7
|
||||
is moot — `ci.yml` has gated every PR since bootstrap; 8 is history, P1 having closed; 9 stays open — no `ja` string has
|
||||
been reviewed, an owner-only item.)*
|
||||
5. **P0 item 5 asks for an AFMF decision on an RTX 5080.** AFMF is AMD driver
|
||||
-side. Reword to "validate on NVIDIA; record AFMF as untested", per the
|
||||
precedent `14_TESTING` already sets for absent hardware.
|
||||
@@ -4423,9 +4440,9 @@ no drain) stays in P0. Items 5–9 below are still open.
|
||||
|
||||
| Named where | Artifact | State |
|
||||
|---|---|---|
|
||||
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet |
|
||||
| `12_BUILD:139`, `13_CI_CD:11`, `09_I18N:28`, `CLAUDE.md:66` | `tools/resx-audit` | ~~Absent. **Honestly handled** — `build.ps1:309` skips it loudly with a reason, and no `.resx` files exist yet~~ **✅ Built 2026-09-13 (P3 PR-2)**, a `build.ps1` step (marked 2026-10-04) |
|
||||
| `12_BUILD:136`, `13_CI_CD:11` | the managed **struct-mirror** test | ~~Absent. Nothing under `tests/` references `FlFrameRecord`.~~ **✅ Built in #47** — `ShmLayout.cs` + `ShmLayoutMirrorTests`, driven by `fl-layout-dump`'s JSON rather than a transcribed table, asserting blittability as well as offsets, and walking the field list in both directions. `build.ps1`'s gate now reads the run's `.trx` and fails when the class did not execute, so **deleting the test is red too** — it used to `Test-Path` a source file |
|
||||
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist |
|
||||
| `13_CI_CD:21`, `12_BUILD:121`, `CHANGELOG:9` | `.github/workflows/release.yml` | ~~Absent. `CHANGELOG`'s header instructs an author to write for a consumer that does not exist~~ **✅ Built 2026-09-14 (P4 PR-5)**; it published beta.1 through beta.11 (marked 2026-10-04) |
|
||||
| `12_BUILD` §Local quality gate | gates omitted from the list | ~~**Three documents give three different counts, which is the finding.** `build.ps1` has **15** `Write-Step` calls as of 2026-08-05 (14 before this PR's `changelog-check`); `12_BUILD` lists 10; this row said 13.~~ **Corrected 2026-08-06: `build.ps1` has 17 `Write-Step` calls** (`package-closure` added two), and `12_BUILD`'s list is rewritten to 16 numbered entries — the difference is that `Invoke-Native`'s three steps run under one heading there. `13_CI_CD` no longer restates the list at all; it points at `12_BUILD`, because restating it in two places is what let one of them rot. **Nothing still derives the list from the script**, so the drift is slowed rather than stopped, and this row remains open for that reason. **And it drifted again, exactly as predicted — re-counted 2026-08-28.** `hookinventory-check` had reached `build.ps1` and never reached the list; `frametype-oracle` had reached both and then been deleted with PresentMon, so the two errors happened to cancel and the *totals* matched while the *membership* did not — the same coincidence §S24's own recount was caught by. The list is rebuilt to **17 entries against 17 `Write-Step` calls, in script order** (re-deriving the order caught a second defect: two adjacent entries had been transposed relative to the script). **The row still does not close.** Aligning by hand is what was done in 2026-08-06 and again here; it lasts until the next gate lands. The fix is a gate that reads the `Write-Step` names out of `build.ps1` and fails when the list disagrees — until it exists, re-count rather than trusting the number |
|
||||
|
||||
The struct-mirror row is the one that matters. `CLAUDE.md` §Struct mirroring
|
||||
|
||||
+629
-13
@@ -1,6 +1,6 @@
|
||||
# HANDOFF — read this first, then stop reading it
|
||||
|
||||
The one file a new session opens to pick up P0. It carries **sequencing, decisions
|
||||
The one file a new session opens to pick up ~~P0~~ work (corrected 2026-10-04). It carries **sequencing, decisions
|
||||
and traps**. It deliberately carries **no status**.
|
||||
|
||||
> ## The rule this file lives under
|
||||
@@ -43,8 +43,9 @@ with §S2's in-layer supervision. **P1 item 1 — the `LoadLibrary` detour — l
|
||||
`04_CAPTURE` §Launch mode); item 3, the Vulkan layer to `vkQueuePresentKHR` with §S2's in-layer
|
||||
supervision, landed the same day (§S2 ✅; `17_HOOK_ENGINE` §Vulkan); item 4 — compare-and-restore per
|
||||
inline patch, the native log, `wglSwapBuffers` — landed the same day too, and D3D9 is struck per §Scope.
|
||||
P1's core is done; what stays ⏳ is the feature rows `15_ROADMAP` §P1 now lists, and P2 (the Agent, the
|
||||
recorder, SQLite) is next.** The ~~three~~ ~~two~~ one P1-deferred S-item (~~S6~~, ~~S2 part three~~, and
|
||||
P1's core is done; what stays ⏳ is the feature rows `15_ROADMAP` §P1 now lists, ~~and P2 (the Agent, the
|
||||
recorder, SQLite) is next~~.** *(Corrected 2026-10-04: P2–P4 closed 2026-09-10/14/15; later work is the dated train
|
||||
sections from §0.1.0-beta.3 on.)* The ~~three~~ ~~two~~ one P1-deferred S-item (~~S6~~, ~~S2 part three~~, and
|
||||
the hand-run blast-radius script behind S29(d)) are the reminders. The text below is
|
||||
P0's history and stays as it stood.
|
||||
|
||||
@@ -1203,7 +1204,8 @@ milestone must not wait on a new native target crossing every gate — it lands
|
||||
(§G). **D5 — `FileGameConsentStore` is retired in B**; the CaptureHost writes a build-tree `ledger.db`
|
||||
so the Agent stays the sole owner of `%LOCALAPPDATA%\FrameLedger`.
|
||||
- **D6 — `--data-dir` exists only under `--console`** (F; `12_BUILD` §Debugging), so `--serve` can never
|
||||
be pointed at a ledger that is not the Agent's own.
|
||||
be pointed at a ledger that is not the Agent's own. *(beta.15, D52: the App gained a `--data-dir` of its own — a
|
||||
viewer over a copy that starts and contacts no Agent; D6 itself is unchanged.)*
|
||||
- *(Numbering, recorded 2026-09-13: D1, D5, D6 and D10 were cited by number from `CHANGELOG`, `04_CAPTURE`,
|
||||
`12_BUILD` and `07_IPC` while this list carried them unlabelled — labels added above. **D2 and D3 were
|
||||
never assigned**; the numbering skips them. Nobody needs to hunt for a missing decision.)*
|
||||
@@ -1215,7 +1217,7 @@ election are **F** and **G**; the ⏳ feature rows in `17_HOOK_ENGINE` §Hook in
|
||||
their columns (`hdr_flag`, `pt_confidence`, `pso_stutter_pct`, `vram_proc*`, `latency_*`) are an
|
||||
honest NULL in P2's schema, never a 0.
|
||||
|
||||
## P4 — **START HERE** (2026-09-14: P3 is code-complete; the stack awaits the owner's merges) — **code-complete 2026-09-15 with PR-9**: every item below is struck; what follows is `15_ROADMAP` §P5 and §Owner-only
|
||||
## P4 — ~~**START HERE**~~ (2026-09-14: P3 is code-complete; ~~the stack awaits the owner's merges~~) — **code-complete 2026-09-15 with PR-9**: every item below is struck; what follows is `15_ROADMAP` §P5 and §Owner-only *(struck 2026-10-04: merged 2026-09-14/15; the live head is the newest dated train section below, and §Owner-only)*
|
||||
|
||||
P3's slices are all struck below. What is left of P3 is not code: the owner merges #154 → #155 → #156 → #158 →
|
||||
#159 → #160 → #161 → #162 → #163 → PR-9 in order (squash; after each merge the next branch is rebased
|
||||
@@ -1408,9 +1410,11 @@ stops there"~~ — the override itself is gone since 2026-09-22 (D22).
|
||||
**Found and NOT fixed — each needs its own PR.**
|
||||
- ~~**A refused session is not recorded, though the notice says it is.**~~ **Fixed 2026-09-22 (D23):** the loop holds a
|
||||
refused session open until the target exits, so Tier 2 has a producer and the sentence is true for every refusal.
|
||||
- **A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
|
||||
- ~~**A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
|
||||
`git describe`. Both sides of the handshake compile the same string, so nothing breaks; it is a release that calls
|
||||
itself dirty.
|
||||
itself dirty.~~ **Fixed 2026-10-07 (beta.18 PR-3):** the dirt was `release.yml`'s own date substitution in
|
||||
`legal/*.md`; the workflow reads describe from the clean checkout before it and hands it to CMake as `FL_BUILD_ID`,
|
||||
and `tools/buildid-check.ps1` reads it back out of the published binaries (`12_BUILD` §Release-time token substitution).
|
||||
- ~~**An install over a running Agent half-replaces the folder** (three failed starts, `Microsoft.Data.Sqlite` not
|
||||
found).~~ **A GUESS, WITHDRAWN the same evening, and it had already been published in beta.4's notes.** Nothing was
|
||||
installed between the failures (20:59–21:01) and the start that worked (21:02); the PC had been restarted at 20:57
|
||||
@@ -1490,7 +1494,8 @@ wrongly-named entry through `SessionRecorder`'s `EnsureAsync`); the running tabl
|
||||
launch election registers its session and defers to the watcher's. **What it costs:** a game whose FOLDER moved records
|
||||
nothing until *Change executable* — accepted, because the alternative is exactly what put HHW's sessions under Flower
|
||||
in Us. **D28 (owner, same day):** HHW itself is measured by pointing an entry at `swiftshader\Game.exe` (the NW.js
|
||||
runtime its .NET launcher starts); no launcher-following in beta.6.
|
||||
runtime its .NET launcher starts); no launcher-following in beta.6. *(Corrected 2026-10-13, D57: that ".NET launcher"
|
||||
is malware — `spike-notes.md` §20. Nothing here asks for it to be run.)*
|
||||
|
||||
**Decision (D26, owner: "the library still shows two entries side by side after the drive letter changed, with the
|
||||
data unchanged").** The Agent merges two entries for one executable under two drive letters by itself: the stale
|
||||
@@ -1557,7 +1562,9 @@ và legal"), so the Legal Gate shows both once.
|
||||
**Traps.**
|
||||
- **A pid the watcher matched stays matched.** Switching recording off stops the session but leaves the process in
|
||||
`ProcessWatcher`'s table, so switching it back on while the same process still runs starts nothing until it restarts.
|
||||
A process the watcher never matched (off from the start) is picked up by the next poll.
|
||||
A process the watcher never matched (off from the start) is picked up by the next poll. *(beta.15: one case of this is
|
||||
fixed — a process turned away because its executable's session was still running is remembered and recorded when that
|
||||
session ends, if it is then the executable's only process; 04_CAPTURE §Process watcher.)*
|
||||
- **A migration that changes data needs its own rewind in a test.** `RewindSchemaAsync` leaves columns in place, so
|
||||
`ScriptNineAddsTheRecordingSwitchOffForSteamToolsOnly` drops the column itself before re-applying 0009.
|
||||
- **`SqliteGameRepository._columns` is read by ordinal** (`ReadMore`): a new column goes at the end of the list, and the
|
||||
@@ -1751,6 +1758,525 @@ release.*
|
||||
|
||||
**Owner-only, added to the list below:** item 7.
|
||||
|
||||
## 2026-10-03 — the beta.11 train: the exception's trial, the library, sessions across
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.11]`; this is what no other file carries. The approved plan was five PRs: PR-1 the
|
||||
CrackProof titles (rules `2026.10.1`), PR-2 the exception's trial (schema 0017, Disclaimer 2.9, EULA 1.4), PR-3 the
|
||||
library and the import, PR-4 delete sessions, the charts across sessions and the Settings clean-up, PR-5 the release.*
|
||||
|
||||
**Decisions (owner, 2026-10-03, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D38 — the user-mode exception's evidence moved under the grant, as a trial.** The owner deleted their ledger and
|
||||
found GIRLS' FRONTLINE 2 "Not eligible: 0 successful hooked session(s), two are needed" for good: since beta.8 a game is
|
||||
blocked the moment it is added, a blocked game is never hooked without a grant, so D33's two sessions were unreachable
|
||||
for every game blocked from the start and lost with a reset ledger. Chosen: a grant needs no session; the first two
|
||||
hooked sessions under it are a trial; any end during the trial (every D33 end, or a stored hooked session with no frames
|
||||
or an abnormal exit) ends it for good (`games.ac_exception_trial_failed_at`). Every other condition is unchanged.
|
||||
Legal text: Disclaimer 2.9 (§2A) and EULA 1.4 — the EULA's "a game the Software has already measured successfully"
|
||||
would have become false (D36's rule).
|
||||
- **D39 — charts across a game's sessions: both** — *Sessions at a glance* on the Sessions tab, and *Also draw* on the
|
||||
Trend (two units at most, the second on the right axis).
|
||||
- **D40 — Delete all sessions: both places** — the game's page and Settings ▸ Data. The Agent deletes (the rows are its),
|
||||
never while a session it would delete under is being recorded.
|
||||
- **D41 — Refresh does all three**: reload the library, offer the games the stores installed since, mark the entries
|
||||
whose executable is gone (*Not installed*; nothing is removed).
|
||||
- **D42 — the library switches between a grid that fills the window and a list** (`ui.library_view`).
|
||||
- **CrackProof (owner's list, "a few, by Steam id")**: three titles whose own store pages say *"Uses Kernel Level
|
||||
Anti-Cheat"* and name CrackProof; ANOTHER EDEN, named only by a community list, is left out.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A fresh git worktree cannot configure the native build**: CMake's MinHook FetchContent clone runs `git submodule`,
|
||||
which fails there ("'submodule' appears to be a git command, but we were not able to execute it"). Run the gate in the
|
||||
primary checkout, whose `build/native/x64-release/_deps` is cached; a worktree is for writing code and managed tests.
|
||||
- **A `DataGrid` laid out outside a window draws its star columns at their minimum** (no Loaded pass): a visual check
|
||||
renders a hosted, off-screen `Window` and pumps the dispatcher (`Dispatcher.PushFrame`), not Measure/Arrange on a page.
|
||||
- **`Native FPS` includes a measured-none session**, whose native rate is the presented one: beside Presented it is a
|
||||
second line on the same points, so the overview keeps Native and Displayed to sessions that generated frames.
|
||||
- **Both processes may change the library while the Games page is open**, and WPF UI 4.3.0 does nothing on a navigation
|
||||
to the page already on screen: the page reloads on `SessionCompleted` and on the App's own `LibraryChanges`.
|
||||
- **A grant's trial is counted from the sessions, not kept as a counter**: the lapse policy counts at each finalize
|
||||
(`CountSuccessfulUnderGrantAsync`: that family, started at or after the grant), and `ac_exception_sessions` is only
|
||||
the sweep's copy for the card. Deleting sessions can only lengthen a trial; the mark that ends one for good
|
||||
(`ac_exception_trial_failed_at`) is the only stored decision.
|
||||
- **A session summary is a window of its own, outside every page**: deleting sessions must close the ones open on a
|
||||
deleted session and let go of File ▸ Export's selection, asking the ledger whether the session is still there (both in
|
||||
`SessionDeletion`, so Settings ▸ Data does it too) — ids are reused once the newest is gone. The plan said so; PR-4's
|
||||
first version did neither, and a self-review caught it before the merge.
|
||||
- **Analyzers met:** `MA0048` (one type per file), `CA1003`/`MA0046` (an `EventArgs` type for an event), `IDE1006` (a `_`
|
||||
prefix on private consts), `CA1030` (no method named `Raise`), `MA0051` (60 lines), and `RevokeAntiCheatExceptionAsync`'s
|
||||
new `bool` before the token turned every `(path, reason, ct)` call into a compile error — pass `ct: ct`.
|
||||
- **The Bash tool's heredocs break on an odd number of apostrophes and halve backslashes**: patch scripts are files.
|
||||
|
||||
**Owner-only, added to the list below:** item 8.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-04, the beta.12 train: the game's own memory, rendered documents, a user guide, the legal split *(struck the same day: the head is §beta.13 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.12]`; this is what no other file carries. The approved plan was eight PRs: PR-0 the
|
||||
recorder test that went red on a loaded runner, PR-1 `NOTICE` and the licence header (D45), PR-2 the game's memory
|
||||
measured from outside the game (C++ `FrameLedger.ProcessStats.dll`, schema 0018, D43), PR-3 the App showing it, PR-4
|
||||
Markdown rendered and a tabbed About, PR-5 the user guide and the documents a user accepts, PR-6 the documentation sweep,
|
||||
PR-7 the release.*
|
||||
|
||||
**Decisions (owner, 2026-10-03, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D43 — the game's memory is measured from OUTSIDE the game, in both tiers.** A new C++ library loaded by the Agent,
|
||||
never into a game: dedicated and shared GPU memory from the documented `GPU Process Memory` performance counters (no
|
||||
handle to the game), private working set / working set / commit from `GetProcessMemoryInfo` with
|
||||
`PROCESS_QUERY_LIMITED_INFORMATION` only — a hooked game through the handle the session holds, any other through a
|
||||
handle opened for the read and closed after it, the creation time checked, every process of the executable summed.
|
||||
Task Manager's figures are the definition; no budget (§M11 stays open); not `D3DKMTQueryStatistics` ("Reserved for
|
||||
system use"). Measured first: `spike-notes` §16.
|
||||
- **D44 — a user guide in English**, `guide/`, rendered in the App (Help ▸ User guide), linked from the README.
|
||||
- **D45 — the legal split.** `legal/TRADEMARKS.md`; `FORKING.md` and `CONTRIBUTING.md`; the GPL shown as information,
|
||||
not accepted (GPLv3 §9, FR-11 changed); GPLv3 §7(b)(c)(e) additional terms in `NOTICE` and named in every source file's
|
||||
header; the Appropriate Legal Notices in a tabbed About; the EULA's consumer-law carve-out and severability; the
|
||||
Privacy Policy's section on sharing exports and bug reports; `CODE_OF_CONDUCT.md`.
|
||||
- **D46 — documentation is corrected in place** (struck, dated) with an index, `docs/README.md`; history stays.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A test whose session length came from a fake clock but whose end came from a real 150 ms timer** went red whenever a
|
||||
loaded runner fitted fewer than six drains into it (PR-0): make the fake drive both.
|
||||
- **Two LibreHardwareMonitor `Computer`s updating in one process** threw a NullReferenceException in `GenericCpu.Update`
|
||||
in the local gate (`LhmRealHardwareTests` beside `PrivilegeFootprintTests`); the Agent's own read was already behind a
|
||||
catch. The two test classes share a collection now.
|
||||
- **A test reading resource text outside the culture collection** races a class that flips `Strings.Culture`; a class
|
||||
that adds many flips (`GameMemoryTextTests`) makes it likelier. `GamesViewModelTests` moved in; the rest are a chip. *(Ended in beta.13: the
|
||||
collection runs alone.)*
|
||||
- **`ShmDrainIntegrationTests.AnUnhookRequestStops…` failed once on CI at the injection step** (≈1 s, `IsAllowed`
|
||||
false) and passed on the re-run; it passed on the PR before. A flake to watch, not yet a fix.
|
||||
- **Markdig follows the table spec strictly**: a line without cells between a table's rows ends the table, and GitHub
|
||||
still draws it. `MarkdownRendererTests` fails any embedded document whose table would show as `|---|` text.
|
||||
- **`AccentTextFillColorPrimaryBrush` is the dark accent until `ApplicationThemeManager.Apply(…, updateAccent: true)`
|
||||
runs** — a test host that skips it draws links #003E92 on #202020; the App (and the Legal Gate, via `WpfThemeApplier`)
|
||||
applies it.
|
||||
- **`tools/license-gather.ps1` took an override only for a URL-only package**; Markdig declares BSD-2-Clause and ships no
|
||||
file, so the expression branch takes an override too now.
|
||||
- **A file git sees as mixed line endings is `-text`**: no EOL conversion, so a CRLF rewrite shows as a whole-file change.
|
||||
Keep such a file's working copy LF (`docs/legal-drift-history.md`).
|
||||
- **Inserting a `### Changed` heading after an entry in the middle of `### Added`** moves every later Added entry under
|
||||
it — read the section's headings back before committing.
|
||||
- **The stacked-branch recipe carried four PRs** (PR-3 on PR-2, PR-4 on PR-3, PR-5 on PR-4): after each squash merge,
|
||||
`git rebase --onto origin/main <old parent>` replays only the PR's own commit, and resx / CHANGELOG additions stay
|
||||
clean because each PR appends after the previous one's.
|
||||
|
||||
- **A test can hide the defect it exists to catch**: `LogTailTests` fed App-form lines into the fake *Agent* log, so
|
||||
the Logs page's level filter matched no real Agent line (Serilog's default template, a date first) and nobody saw
|
||||
it for three weeks. A fixture for another process's file is a copy of a real line from that process.
|
||||
- **A setting with `AgentReads = true` that no Agent code reads is a switch that lies**: Settings' *Record games
|
||||
launched outside FrameLedger* wrote `capture.background` and nothing read it (removed in PR-6, the key reserved).
|
||||
Before trusting a registry row's flag, grep for a reader.
|
||||
- **The audits (PR-6) found code gaps the docs had been describing as built**, each left for its own PR and named
|
||||
here so it is not rediscovered: L1 telemetry is never pointed at the game's adapter (`SelectAdapter` has no caller,
|
||||
`18_GPU_VENDOR_APIS`); a machine-wide service refusal still says "detected in this game" (§S23-3, 🔴); no release
|
||||
has carried a Velopack delta (`release.yml` never fetches the previous release); there is no rules feed (§S20). *(Three of the four closed in
|
||||
beta.13 — §S23-3, the adapter, the delta; the rules feed stays.)*
|
||||
|
||||
**Owner-only, added to the list below:** item 9.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-04, the beta.13 train: the four follow-ups the beta.12 audit left *(struck 2026-10-06: the head is §beta.14 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.13]`; this is what no other file carries. The owner asked (2026-10-04) for the
|
||||
four chips the beta.12 documentation audit had left — §S23-3's wording, the App tests' culture races, L1's adapter, the
|
||||
Velopack delta — then a release and the session closed. Two PRs: PR-1 the three code changes, PR-2 the release with the
|
||||
delta in `release.yml`.*
|
||||
|
||||
**No new owner decision.** The choices below follow rules already written: a figure from the wrong graphics card is worse
|
||||
than N/A (`FlShmHandshake.AdapterLuid`'s own comment), and a finding on the PC is not a finding in the game (§S23-3,
|
||||
2026-09-06).
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **Pointing L1 at the game's adapter changes nothing visible on its own**: `CompositeTelemetrySource` merges L3 > L2 >
|
||||
L1 per field, and L2 (LibreHardwareMonitor's first GPU node) and L3 (NVAPI's first physical GPU) read their own card.
|
||||
Every layer has to agree on the card — L1 by LUID (`IGpuAdapterSelector`), the others by the adapter's vendor
|
||||
(`IGpuVendorFollower`), and L3 says nothing for an AMD or Intel adapter. Two GPUs of one vendor stay first-found.
|
||||
- **A `CaptureRefused`'s `reason` is the session's end reason** (`RefusedByGuard`), not the guard's: the App could not
|
||||
tell a service from a module until the events carried `guardReason`. A `RefusedAck`'s `Reason`, by contrast, IS the
|
||||
guard's — two "reason" fields one pipe apart that mean different things.
|
||||
- **A collection definition must be public** (xUnit1027), which CA1515 then flags in a test project that is an exe — the
|
||||
suppression carries the reason. `TestContext.Current.TestCollection.TestCollectionClassName` proves the definition
|
||||
bound, so a definition xUnit did not find fails a test instead of bringing the races back silently.
|
||||
- **`vpk download github --pre` puts the previous release's full package in `out/release`**: `vpk pack` needs it there to
|
||||
write a delta, and nothing else may ship it — `assets.win.json` names what this pack built, the rest moves to
|
||||
`out/previous`, and the feed and `RELEASES` are filtered to this build, as `vpk upload github` writes them.
|
||||
- **A 120 ms wall-clock ceiling races the second scan on a loaded runner**: the release rehearsal failed on
|
||||
`CaptureSessionTests.AGuardThatThrowsMidSessionKeepsTheRecordsItAlreadyDrained`, which ended as `Running` before the
|
||||
guard's second evaluation threw — the class beta.12's PR-0 fixed in the recorder tests. The four tests whose ending is a
|
||||
scan, a throw, the kill switch or an exit take `EndsOnItsOwn` (a 30 s safety net); a test that EXPECTS `Running` keeps
|
||||
the short ceiling, because that ceiling is its ending.
|
||||
- **The beta.12 traps about the culture race and the four code gaps are closed here** (the rules feed stays open, §S20).
|
||||
|
||||
**Owner-only, added to the list below:** item 10.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-06, the beta.14 train: contrast and the wheel, the update audit, crash reporters, assembly metadata, new measurements *(struck the same day: the head is §beta.15 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.14]`; this is what no other file carries. The owner's list (2026-10-05, with a
|
||||
screenshot of the import list in the dark theme): the contrast, a review of the update logic, games recorded as crashed
|
||||
by an engine's crash reporter (prevention; SILENT HILL 2 as the example), assembly metadata, new metrics and charts, and
|
||||
a wheel that scrolls with an option to hide the scroll bars. Nine stacked PRs — PR-1 contrast and the wheel, PR-2 the
|
||||
scroll-bar option, PR-3 the update audit, PR-4 the guard's retry, PR-5 crash classification, PR-6 assembly metadata,
|
||||
PR-7 the metrics' Agent half (schema 0019), PR-8 their App half, PR-9 the release — plus one test fix (#268).*
|
||||
|
||||
**Decisions (owner, 2026-10-05, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D47 — the update channel follows the running copy.** `update.channel` gained `auto`, the default: a pre-release
|
||||
copy asks for pre-releases, a stable one for stable; an explicit *Stable* or *Beta* in Settings wins
|
||||
(`Update/UpdateChannelPolicy`). Until beta.14 the default was `stable` and every release is a pre-release, so an
|
||||
installed copy never found an update (the owner's own `velopack` log: "No releases found").
|
||||
- **D48 — the guard's narrow fix, both halves.** A scan-set member still loading (`ERROR_PARTIAL_COPY`) or already gone
|
||||
is read again once, ~250 ms later, before the guard refuses; still unreadable still refuses, and `ACCESS_DENIED` is
|
||||
never retried. A refused re-scan for a could-not-read reason (`ProcessUnreadable`, `ModuleScanFailed`,
|
||||
`ProcessTreeUnavailable` — never a finding) when the game itself had exited ends as the game's exit
|
||||
(`ExitScanRelabel`, the note `scan_at_exit=`). CLAUDE.md rule 2 is unchanged: a failure still refuses.
|
||||
- **D49 — all four metric groups.** The render scale over time; time below 30 / 60 / the refresh rate and frame to frame;
|
||||
the facts the row stored and nothing showed (VSync and tearing, ray tracing's share, focus, capture quality, the
|
||||
displayed 1 % low); the card's clocks, fan, memory temperature, limits, and frames per watt.
|
||||
- **D50 — the managed binaries' identity.** Company and Product "FrameLedger", the copyright the native `FL_COPYRIGHT`
|
||||
word for word; `versioninfo-check` reads both kinds and compares them.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **WPF UI 4.3.0 keys its DataGrid styles** (`DefaultDataGridRowStyle`) and defines no implicit row style: a `RowStyle`
|
||||
`BasedOn="{StaticResource {x:Type DataGridRow}}"` falls through to Aero2's row and `SystemColors.WindowBrush` — white
|
||||
under the dark theme's white text. Its `CheckBox` has `MinWidth` 120. Both in `16_WPFUI_SYNTAX` §Gotchas now.
|
||||
- **`NavigationViewContentPresenter` makes a `Page`'s `CanContentScroll` true and wraps it in its own scroller**; a page's
|
||||
own root `ScrollViewer` is then measured unbounded, has nothing to scroll, and still marks every wheel handled. ScottPlot
|
||||
never marks the wheel handled.
|
||||
- **`Keyboard.Modifiers` is the machine's real keyboard, from any thread** (a fresh background thread's `GetKeyState`
|
||||
reported the machine's NumLock): a local gate went red on the chart-wheel test while a Ctrl was held. A test that sends
|
||||
input sets the keys itself (`ChartWheel.CurrentModifiers`, #268).
|
||||
- **Velopack 1.2.0 applies a downloaded update at the next start by default** (`SetAutoApplyOnStartup`), before FR-12's
|
||||
check and with the Agent killed; `VelopackHooks` turns it off and a pending package is adopted instead.
|
||||
- **The plain "time below X" rule fabricates drops**: a game capped at 60 read 50.0 % "below 60" from present-timing
|
||||
jitter (measured on a copy of the owner's ledger); a rolling mean does not help. The margins of `FramePacing` and what
|
||||
they cost are in `03_METRICS` §Pacing.
|
||||
- **A WER 1001 is not a crash by its number**: `RADAR_PRE_LEAK_64` is Windows' memory-leak detector, and a substring match
|
||||
on the executable's name stored an ordinary The Witcher 3 session as crashed. `CrashEventMatcher` reads the event name
|
||||
and the typed process id.
|
||||
- **No chart palette colour was 60 apart from all six on the temperatures plot** — `Chart_Histogram` equals
|
||||
`Chart_Native` — so the seventh line got a key of its own (`Chart_SensorTertiary`); `ChartMathTests` caught it.
|
||||
- **Meziantou's MA0051 (60 lines, 40 statements) split** `FrameTimeSeries`'s two builders into one `Kept` accumulator,
|
||||
the summary's cards into three methods and Compare's rows into two; `dotnet format` wants one property per line in an
|
||||
object initializer, even in a test.
|
||||
- **The `fl_ring` anti-vacuity flake** (§Traps) fired on #264's CI and passed on the re-run, as written.
|
||||
- **`git describe` is 31 characters ten commits after a tag** (`v0.1.0-beta.13-10-g15ec7c1c5fd4`) — the most
|
||||
`FlShmHandshake.buildId` holds. `ShmHandshakeValidatorTests` appended `"x"` to the id for its mismatch case, the helper
|
||||
cut it back to 31, and the check read `Ok`: red from the tenth commit after every tag, locally and on CI (#273 uses
|
||||
another id of the same length).
|
||||
- **"The job was not acquired by Runner of type hosted even after multiple attempts"**: with seven CI runs in flight a
|
||||
queued Windows job was cancelled after ~15 minutes, twice, without a step having run. Nothing in the code; re-run the
|
||||
job when fewer runs are queued.
|
||||
- **The Privacy Policy 2.7 holds the merge of PR-5 and PR-7**: their wording (§4 the crash reports and the programs a
|
||||
game starts, §1 the card's sensor series) is the owner's to approve before they land, as the plan said.
|
||||
|
||||
**Owner-only, added to the list below:** item 11.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-06, the beta.15 train: the five chips beta.14 left *(struck the same day: the head is §beta.16 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.15]`; this is what no other file carries. The owner's request (2026-10-06): "Xong
|
||||
beta14, tổng hợp 5 chip thành 1 bản beta15" — the five findings the beta.14 train spawned as tasks instead of fixing in
|
||||
its own scope. Six stacked PRs — PR-1 the choice lists follow the language, PR-2 launch mode's election, PR-3 a restart
|
||||
during finalize, PR-4 the scan set's creation times (D51), PR-5 the App's viewer (D52), PR-6 the release.*
|
||||
|
||||
**Decisions (owner, 2026-10-06, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D51 — the scan set cuts a parent/child link only when it is proven wrong**: both creation times read and the child
|
||||
created before the process whose pid it names as its parent. An unread time keeps the link (rule 2, fail closed), equal
|
||||
times keep it, and each pid is walked once (`fl_guard_scanset.cpp`; `19_SAFETY` item 1 carries the rule and its one
|
||||
residual, a clock set backwards between a parent's start and its child's).
|
||||
- **D52 — the App's `--data-dir` is a viewer over a copy**: no Agent is started or contacted (its composition holds no
|
||||
pipe client, launcher, update check or Run-entry writer — `Services.MachineFacingServices`), every control that would
|
||||
ask the Agent or change the PC is disabled, and the profile's own folder is refused however it is spelled. D6 is
|
||||
unchanged; the full alternative (an Agent `--serve --data-dir`) would have changed D6, the pipe's per-user name and the
|
||||
hello.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **Launch mode's election had never run** (since #150): a refused launch returned its outcome without the launcher's
|
||||
pid, so the orchestrator stopped before its first `election:` line — and its tests hand-built an outcome that already
|
||||
carried a pid. A test of one half that hand-builds what the other half returns proves the half, not the pair
|
||||
(`CaptureSessionLaunchTests` now asserts what the session itself returns).
|
||||
- **The watcher reports a process once.** "One session per executable at a time" turned a restarted game away and nothing
|
||||
looked at it again; the orchestrator remembers the newest such process per executable and starts it when the running
|
||||
session ends, if it is then the executable's only process — a multi-process game's helper is not a restart.
|
||||
- **A pid in a snapshot names whoever holds it now.** Creation times are the evidence (`GetProcessTimes`, under the
|
||||
module scan's own read-only right), compared strictly: a parent and a child can share one tick of the clock.
|
||||
- **Static choice lists keep the language they were built in**; a list read once into a `static` field, the tray's
|
||||
menu built once and the pill's text written once all needed a way back (`ILanguageFollower`, called by the shell's
|
||||
rebuild).
|
||||
- **An Agent end-to-end test can lose to another project's harness**: `build.ps1` runs the test projects as parallel
|
||||
processes, and a `hook-harness.exe` another project was still starting made `TargetResolver` refuse with
|
||||
`TargetAmbiguous` (#269's first CI run; the re-run passed). The refusal is right and the test isolation is not — left
|
||||
as a task, not fixed in this train. *(Fixed in beta.16: the by-name suites consent to a run-unique copy of the
|
||||
harness — `14_TESTING` §hook-harness, test isolation.)*
|
||||
|
||||
**Owner-only, added to the list below:** item 12.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-06, 0.1.0-beta.16: beta.15 verified, and the chip it left *(struck 2026-10-07: the head is §beta.17 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.16]`; this is what no other file carries. The owner, after beta.15's release
|
||||
(2026-10-06): owner-only item 12 passed on real hardware ("đã chạy và ok"), do the chip beta.15 left, release, and close
|
||||
the session. One PR carries the test isolation and the release. Nothing in the app changed, so no owner-only item is
|
||||
added.*
|
||||
|
||||
- **The chip:** a suite whose host resolves its target BY NAME (`TargetResolver`) — the Agent's end-to-end and
|
||||
partial-recovery suites, the capture host's — consents to a run-unique copy of the harness, as the pipe suite already
|
||||
did, so another project's `hook-harness.exe` starting at the same moment can no longer make the target ambiguous
|
||||
(`14_TESTING` §hook-harness). `AnotherHookHarnessRunningBesideTheSuiteDoesNotMakeTheTargetAmbiguous` runs a second
|
||||
harness beside the capture and was red against the shared name (`TargetAmbiguous`), measured before the fix.
|
||||
- **The beta.15 train's merges, for the record:** #274–#276 and #279 carry the PRs' own titles; #277 (PR-4, the scan
|
||||
set, D51) and #278 (PR-5, the viewer, D52) were opened by the owner from the pushed branches, so their squash commits
|
||||
are titled "Beta15/pr4 guard" and "Beta15/pr5 viewer" and list every commit of the branch. Their content is the gated
|
||||
stack's: main's tree matched it after each merge.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A session restart restarts gpg-agent**, so the first signature after it asks for the passphrase again, whatever the
|
||||
cache said a minute before; pinentry-qt gives up in about half a minute with nobody at the desk (`git tag -s` failed
|
||||
with "signing failed: Timeout"). Ask the owner for `echo x | gpg --clearsign` right before a tag.
|
||||
- **main is strict and linear**: each PR of a stack must be rebased onto the squash of the one before and run CI again.
|
||||
`git rebase --update-refs --onto origin/main <merged branch> <tip>` moves every branch of the stack at once and drops
|
||||
a commit main already carries (it dropped PR-4 and PR-5 when the owner had merged them from the branches).
|
||||
- **The desktop app forbids polling CI** (no `gh` loop, Monitor or ScheduleWakeup): it wakes the session on a failure, a
|
||||
conflict or a review comment, never on green, so a green PR waits for the owner's word or the owner's auto-merge.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-07, 0.1.0-beta.17: text that follows a theme switch, scroll bars hidden everywhere, a wiki *(struck 2026-10-07: the head is §beta.18 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.17]`; this is what no other file carries. The owner's report (2026-10-07, three
|
||||
screenshots of beta.16): Settings' descriptions kept the old theme's colour after a switch; the Dashboard kept its
|
||||
scroll bar with Hide scroll bars on; "a complete wiki, concise and easy, End-user and Dev". Five stacked PRs — #281 the
|
||||
theme text, #282 the scroll bars, #283 the guide's four new pages, #284 the wiki and its publishing, then the
|
||||
release.*
|
||||
|
||||
**Decisions (owner, 2026-10-07, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D53 — the wiki's source is the repository.** `wiki/` (Home, the sidebar, the developer pages) and `guide/` with
|
||||
`LIMITATIONS.md` are assembled by `tools/wiki-build.ps1` and published to the Wiki tab by `.github/workflows/wiki.yml`
|
||||
after a successful Release run (and by hand); a page edited on the tab is overwritten at the next release. English.
|
||||
- **D54 — the wiki's End-user half is the user guide**, one source: it grows past D44's eight pages (the screens, every
|
||||
setting, troubleshooting, a glossary — twelve) and stays embedded in the App. Tests hold that every setting the
|
||||
Settings page shows and every page and menu item of the main window is named in it.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **`ui:TextBlock Appearance` pins a brush.** WPF UI 4.3.0 resolves it once (`TryFindResource`) and coerces Foreground
|
||||
to it, so a theme switch leaves the text in the old theme; 129 texts used it. Every contrast check before measured a
|
||||
theme as a surface was *made* under it — a switch needs the surface hosted in a `Window`, because only
|
||||
`Application.Windows` hear a dictionary change (`16_WPFUI_SYNTAX` §Gotchas, `14_TESTING`).
|
||||
- **A class handler on `Loaded` is not a load hook.** WPF raises Loaded only where a subtree listens for it with its own
|
||||
handler, style EventSetter or template trigger — WPF UI's toggle switches carry one, which is why Settings hid its
|
||||
bar and the Dashboard never did. A test that calls `RaiseEvent(Loaded)` proves the handler, never that WPF reaches it;
|
||||
`ScrollChanged` reaches every scroller from its first layout.
|
||||
- **The wiki's git branch is `master`, and the repository's default workflow token is read-only:** `wiki.yml` declares
|
||||
`contents: write`. A release made with `GITHUB_TOKEN` fires no `release` event for another workflow; `workflow_run`
|
||||
does, and runs `main`'s copy of the file — so it checks out the run's `head_sha` and links at its tag.
|
||||
- **A fresh worktree cannot run the full gate** (the native configure, `CONTRIBUTING`): the stack's tip was gated in the
|
||||
main checkout on a detached HEAD, and each PR's own CI ran on its branch.
|
||||
- **Found while writing the guide, not fixed** (a task each): two notices can print an internal name — *"The hook
|
||||
stopped (WriterSelfDisabled)…"*, and a refusal no anti-cheat names reads ~~*"The anti-cheat guard did not hook this
|
||||
game: reason RefusedKillSwitch."*~~ *"…: reason RefusedByGuard."* *(corrected 2026-10-07 by beta.18's tests, which
|
||||
build the Agent's own events: the kill switch's refusal carries the gate's label where a family goes, and read "kill
|
||||
switch was detected in this game (… (FR-2.4) …)"; a re-scan that could not look read "Access is denied. was detected")*; the kill switch's *Applied* strip says "at the next session start" (it applies
|
||||
within 30 s); *Turn off* failing says "Nothing was enabled."; in the viewer, the exception switch, the Recording numbers and the Channel stay enabled;
|
||||
`08_UI` lists a "PawnIO missing" banner that does not exist; and a release's Overlay build id reads `-dirty` (§0.1.0-beta.4,
|
||||
"Found and NOT fixed", still open). *(All but the build id fixed by beta.18 PR-2, 2026-10-07; the build id is PR-3's.)*
|
||||
|
||||
**Owner-only, added to the list below:** item 13.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-07, 0.1.0-beta.18: page titles readable in the dark theme, notices in words, a clean build id *(struck 2026-10-12: the head is §beta.19 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.18]`; this is what no other file carries. The owner's report (2026-10-07, five
|
||||
screenshots of beta.17 in the dark theme): every page's title and section headings near-black on the dark window — and
|
||||
the two chips beta.17 left (§beta.17, "Found while writing the guide"). Three stacked PRs — #286 the page text, #287
|
||||
the notices and the rest of that list, #288 the release build id — then the release.*
|
||||
|
||||
**No new decisions.** The train is the owner's request of 2026-10-07 ("beta18 with the two chip tasks, and the text that
|
||||
blends into the background in dark mode").
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A page in the `NavigationView` inherits nothing.** `NavigationViewContentPresenter` is a `Frame`, and a Frame sets
|
||||
`InheritanceBehavior.SkipToAppNow`; WPF UI 4.3.0 makes the TextBlock default black. A page on screen during a theme
|
||||
switch takes the window's new colour through the switch and a page navigated to afterwards does not, so it came and
|
||||
went. Every check before hosted pages straight in a window and measured a page the App never draws — host a page in the
|
||||
presenter (`PagesLoadTests.Hosted`, `16_WPFUI_SYNTAX` §Gotchas).
|
||||
- **The accent is not in the theme dictionary.** WPF UI writes it into `Application.Resources` at every
|
||||
`ApplicationThemeManager.Apply(…, updateAccent: true)`; a test that swaps only the dictionary measures the other theme's
|
||||
accent (`Visuals.UnderTheme` derives it as the App does; `systemAccentColor: true` reads the machine's own palette).
|
||||
- **The gate's own refusals look like findings on the wire.** `HookedCaptureGate` puts a label ("kill switch", "previously
|
||||
blocked") where a family goes; whatever reads a family as "an anti-cheat was found" asks the end reason first. A test
|
||||
of what the user reads builds the event as the Agent does (`NoticesFromTheAgentTests`), never by hand — the
|
||||
hand-written events were why every notice test was green.
|
||||
- **`Safety_Consent_*` strings are versioned with the consent disclosure** (`SafetyDisclosure`): a message that is wrong
|
||||
on one path gets a key of its own rather than a changed meaning.
|
||||
- **A release's natives were `-dirty` by the release's own hand:** its date substitution edits `legal/*.md` before CMake
|
||||
reads describe. The id is read first, handed in, and read back out of the binaries (`tools/buildid-check.ps1`).
|
||||
- **Met again:** `CaptureHostEndToEndTests.WhenTheTargetExitsTheHostStopsAndSaysWhy` (`TargetNotRunning` on a slow
|
||||
runner) failed #286's first CI run; the job was re-run. **And a new one** failed #288's:
|
||||
`…LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing`. A hosted runner has the Vulkan loader and no
|
||||
device, so the harness exits 77 with a `[SKIP]` line — but the runner is elevated, the launch goes through
|
||||
`CreateProcessWithTokenW` (`UnelevatedProcess`), the child inherits no stdout, and the line never reaches the host's
|
||||
output; when the guard's scan hits the exiting harness (`ModuleScanFailed`) the test fails instead of skipping. Re-run;
|
||||
~~the deterministic fix is a task of its own~~ fixed the same day by beta.18 PR-5 (the test asks the harness itself,
|
||||
before the host runs), which also gave the `TargetNotRunning` case a 15 s hold (`13_CI_CD` §ci.yml).
|
||||
|
||||
**Owner-only, added to the list below:** item 14.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-12, 0.1.0-beta.19: the import's helper, the folder Change executable opens in, three engines' versions, uninstalled games *(struck 2026-10-12: the head is §beta.20 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.19]`; this is what no other file carries. The owner's list (2026-10-12, four items):
|
||||
*Change executable…* opens in the game's root folder; the version of RPG Maker, Unity and Godot games; A Doll's Locket -
|
||||
Remake imported as `notification_helper.exe`; whether the Agent removes games whose executable is gone, and if not, to
|
||||
remove them when no session was recorded. Four stacked PRs — #292 the import, #293 the folder, #294 the versions,
|
||||
#295 the removal — and two from #295's review, #297 one notice per check and #298 the probe's unreadable-folder tests —
|
||||
then the release.*
|
||||
|
||||
**Decisions (owner, 2026-10-12, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D55 — a game you uninstalled leaves the library by itself when it has no session** (amends D41's "nothing is
|
||||
removed"): its executable gone at sweeps ten minutes apart (counted in the Agent's memory), its drive connected and the
|
||||
folder it was installed in still there, no session stored, recording or waiting to be recovered — behind Settings ▸
|
||||
Data ▸ *Remove uninstalled games*, on by default (`02_SPEC` FR-1.8). **Never an entry carrying an anti-cheat block, an
|
||||
exception's grant or a failed trial**: that part follows from rule 2 and D38 and was not asked (`19_SAFETY` §What a
|
||||
finding does to the game).
|
||||
- **D56 — an NW.js runtime is the import's game**: an executable beside `nw.dll` + `package.json` ranks as the engine's
|
||||
own layout, below Unity's and Unreal's and above a name match, so a launcher-fronted RPG Maker MV/MZ install is pointed
|
||||
at the process that draws. D28 did that by hand for HELLO, HELLO WORLD!; ~~the locator now picks the same file~~
|
||||
*(corrected 2026-10-13: the locator does, and an import never asks it there — itch's own pick names the program in
|
||||
front, which is not a helper, so the import takes it; and that program is malware, D57 — §beta.21)*.
|
||||
- **The owner's existing A Doll's Locket entry is not rewritten** (D25/D27): *Change executable…* re-points it, and the
|
||||
import no longer offers a twin of the same store title.
|
||||
- **The train (owner, 2026-10-12, after the PRs were up):** "commit, push và release luôn" — each PR squash-merged by the
|
||||
session as its CI went green, then the signed tag and the release, without asking again. Then, of the review's two
|
||||
follow-ups the session had offered as separate tasks: "2 pr riêng, rồi merge, push và release" — #297 and #298, in this
|
||||
release.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A store's own pick can be a helper.** itch's butler saves a *filtered* verdict — the shallowest candidates, minus
|
||||
those whose manifest asks for elevation — and ranks nothing, so A Doll's Locket's whole verdict was
|
||||
`notification_helper.exe`. Its database lives in the WAL (a 4 KB main file): a read with `immutable=1` sees no tables;
|
||||
open it `mode=ro` with the itch app closed, or copy the `-wal` beside it as `ItchLibrarySource` does.
|
||||
- **The locator's helper fragments are substrings** (`node` is inside *Nodebuster*): good enough for a guess, never to
|
||||
overrule a store — `ExecutableLocator.RuntimeHelperNames` holds whole names for that.
|
||||
- **Godot's version string sits 57–78 MB into an export**, past the rules' 8 MiB strings scan; the data pack's header
|
||||
has it in 20 bytes. **Unity's FileVersion string is not the editor version** (`2022.3.39.5118735`); the ProductVersion
|
||||
is (`2022.3.39f1 (hash)`), except on 2019.4 players, whose data file's header carries it.
|
||||
- **`File.Exists` and `Directory.Exists` answer false for a path they may not look at**: before removing anything, the
|
||||
parent's listing is asked whether the child is there (`ExecutablePresenceProbe`).
|
||||
- **The signing key was locked when the session began**, and ten pinentry prompts went unanswered; the code went on and
|
||||
the commits waited. Probe first: `echo x | gpg --batch --pinentry-mode error --local-user <key> --clearsign`.
|
||||
- **Mechanical, again:** the Write tool writes LF (convert after it); a Bash heredoc halves `\\` (patch scripts are
|
||||
files); a WPF project has no implicit `System.IO` using; MA0051 (60 lines) hit `ItchLibrarySource.ReadDatabaseAsync`,
|
||||
`DetectionSweep.SweepOnceAsync` and `AgentServices.AddDetection`; CA1716 rejects an interface member named `Of`.
|
||||
- **A review of the PR that deletes data, after its gates were green and before it merged, found three defects no gate
|
||||
could:** a cross-reference to a `19_SAFETY` section that does not exist; a presence probe that listed every drive for
|
||||
every entry and asked a dead share whether it was ready (`VolumeRoots.IsReady` reads the type first); and an entry
|
||||
the delete refused that was never asked again (`UninstalledEntryPrune.RetryAfter`, an hour). The `vi`/`ja` switch text
|
||||
also named the pill in English where those languages show their own word. Review such a PR before the merge. The two
|
||||
it left for later landed in the same release: one check's removals arrive as one event each, and WPF UI 4.3.0's
|
||||
`SnackbarService` keeps ONE snackbar and shows every message in it at once (`Show(true)`, read from the assembly), so
|
||||
only the last name stayed on screen (#297: the page waits `GamesViewModel.RemovalSettle` and says them once); and the
|
||||
probe's two *Unknown* branches had no test (#298: real folders the test user is denied, each test measured red with its
|
||||
branch broken).
|
||||
- **Loop a test class you touched before the merge.** `GamesViewModelTests` run 165 times failed once: two overlapping
|
||||
reads of the library, the older finishing last and shown — a removed game's card came back. #297 shows only the newest
|
||||
read. The first version of its test hung: which read reached the held check first was itself a race (wait for the
|
||||
first to be held before starting the second, and bound every wait).
|
||||
- **A test run reseeds `%LOCALAPPDATA%\FrameLedger\rules`** with rules `2026.10.2`, whose extractor types the installed
|
||||
beta.18 cannot parse: its detection sweep says "rules unusable" until it restarts or beta.19 is installed (beta.10's
|
||||
trap, met again; the guard is unaffected). For beta.20 PR-1 (rules `2026.10.3`, which the installed beta.19 cannot
|
||||
parse) the session copied the owner's `detection-rules.json` and `.seeded` aside before testing and back after,
|
||||
byte for byte, so the owner's running Agent kept its own.
|
||||
|
||||
**Owner-only, added to the list below:** item 15 — **passed 2026-10-12**.
|
||||
|
||||
**After the release (owner, 2026-10-12):** "tiếp tục với 1 pr kèm với detect version game dùng ren'py" — beta.20 PR-1 reads
|
||||
a Ren'Py game's engine version from `renpy/vc_version.py` (rules `2026.10.3`, Privacy Policy 2.9 — the Legal Gate shows it
|
||||
once at the next update; `05_DETECTION` §Engine version — Ren'Py) and strikes item 15. Merged for the next pre-release;
|
||||
no release was asked for.
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-12, 0.1.0-beta.20: the engine version of Ren'Py games *(struck 2026-10-13: the head is §beta.21 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.20]`; this is what no other file carries.* The owner, the same evening as beta.19 and
|
||||
after confirming it on real hardware: "tiếp tục với 1 pr kèm với detect version game dùng ren'py", then "tung bản beta20
|
||||
rồi đóng phiên hẳn". One PR — #299, a Ren'Py game's version from the engine's own `renpy/vc_version.py` (rules
|
||||
`2026.10.3`, Privacy Policy 2.9, item 15 struck) — then the release.
|
||||
|
||||
**Decisions:** none new. The Privacy Policy 2.9 wording — one item added to §4's list, "the version file of a Ren'Py
|
||||
game's engine" — was shown to the owner with #299 and released on their word.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **`keyboxd` can fail with "Input/output error" while the key is unlocked**: `gpgconf --kill keyboxd` alone brings it
|
||||
back on the next use; killing `gpg-agent` would drop the cached passphrase and wait on a pinentry.
|
||||
- **A test run still seeds the owner's live rules** (§beta.19's trap): rules `2026.10.3` cannot be parsed by an installed
|
||||
beta.19, so the owner's `detection-rules.json` and `.seeded` were copied aside before each local gate and back after.
|
||||
- **Loop a test class you touched before the merge** (§beta.19): `GamesViewModelTests` then ran 340 times green after #297.
|
||||
|
||||
**Owner-only, added to the list below:** item 16.
|
||||
|
||||
## **START HERE** — 2026-10-13, 0.1.0-beta.21: an anti-cheat beside the executable, four itch downloads that are malware, documents that scroll, Play
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.21]`; this is what no other file carries. The owner's list (2026-10-13, four items,
|
||||
with screenshots of two game pages): HELLO, HELLO WORLD!'s RPG Maker path is wrong; no anti-cheat is found for Wuthering
|
||||
Waves; the documents in the app scroll slowly; and, if possible, a Play button on a game's page or in the library that
|
||||
points to the platform. Then: once the plan is approved, commit → push → CI → auto-fix → merge → bump the version →
|
||||
release, in one go. Four stacked PRs — #301 check 4 also walks the executable's folder (rules `2026.10.4`), #302 the four
|
||||
itch "launchers" are malware and the Supports card, #303 the documents' wheel and one render per page, #304 Play and the
|
||||
Privacy Policy 2.10 — then the release.*
|
||||
|
||||
**Decisions (owner, 2026-10-13, asked with the plan — do not re-ask):**
|
||||
|
||||
- **D57 — the four itch "launchers" are malware: the documentation is corrected, the import is not changed.** The
|
||||
"wrong path" of HELLO, HELLO WORLD! is itch's own pick: the 213 MB .NET program in front of the RPG Maker runtime,
|
||||
which is not a helper, so the import takes it (D56). Read without running it, that program — the same in A Doll's
|
||||
Locket - Remake, City of Bones and Träumerei Chapter 2 — is malware (`spike-notes.md` §20). D28, D56, item 15(a), the
|
||||
beta.19 entry and `05_DETECTION` are corrected in place, and no document advises running one. The repository records
|
||||
what the files are, never the state of a PC that ran one.
|
||||
- **D58 — Wuthering Waves is on the title list** (Steam `3513350`, Anti-Cheat Expert), beside the fix that finds ACE's
|
||||
folder beside the game's executable.
|
||||
- **D59 — Play, in two modes switched in Settings:** "1: press Play → the platform opens → it runs; 3: it runs at once;
|
||||
let me switch between the two". `ui.play_mode` is `store` (the default) or `direct`; the store is the one whose own
|
||||
records name the game's folder, never the row's `platform`; an App running as administrator never starts a store's
|
||||
app (`08_UI` §Games).
|
||||
- **The train (owner, with the plan):** "Làm trọn mạch ngay" — each PR squash-merged as its CI went green, then the
|
||||
signed tag and the release, without asking again. The Privacy Policy 2.10 wording and the Wuthering Waves row of
|
||||
`LIST_GAME_TESTED.md` (D35) were approved with the plan.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **The pre-scan's depth limit is a reach, not a refusal.** A folder at the third level is named and never opened, and
|
||||
the walk reports a complete, clean tree; only the 4096-entry budget refuses. An anti-cheat deeper than three levels
|
||||
under both the install root and the executable's folder is still invisible to check 4 — the 30 s re-check meets it
|
||||
only once its driver is loaded, and a driver is a machine-wide finding that turns nothing off (`spike-notes.md` §19).
|
||||
- **A rules note over 300 characters fails `rules-validate` with a message about something else** ("Value is null …
|
||||
`/engines/4/version`"): `Test-Json` names a branch of the schema, not the long `notes` (`freeText`, maxLength 300).
|
||||
Bisect the edit, not the message.
|
||||
- **The owner's live rules, older than the repository's, make parallel test hosts race**: each reseeds
|
||||
`%LOCALAPPDATA%\FrameLedger\rules`, and `ReplaceFileW` fails one of them ("could not write the rules file"). Before
|
||||
the gate, seed the repository's rules and its `.seeded` marker (the uppercase SHA-256 hex) yourself; after it, put the
|
||||
owner's files back byte for byte.
|
||||
- **WPF's `ScrollViewer` moves 48 DIP per wheel message whatever its delta** (`16_WPFUI_SYNTAX`), so a touchpad's small
|
||||
deltas each jump the whole step; `MarkdownView` handles the wheel itself.
|
||||
- **A review of Play after its gates and its first CI run were green found four defects no gate could** (§beta.19's
|
||||
lesson, again). The pipe fails a request in flight with an `IOException` when the agent stops (`PipeClient` fails every
|
||||
pending request so), nothing on the Play path caught it, and a command's unhandled exception is the App's crash dialog —
|
||||
so pressing Play while the agent restarted for an update would have ended there. A store record whose id builds no
|
||||
link read "GOG GALAXY is not installed"; the agent's `UnknownGame` reached a notice as that token; two notices advised
|
||||
what their own path could not do. All four fixed in #304 before it merged. **Not fixed here:** `SessionDeletion` has the
|
||||
same gap (it catches no `IOException`), and every other caller of the pipe misses the `ObjectDisposedException` and
|
||||
`IpcFramingException` the same failure can raise — the owner asked for it as its own PR after this release, and
|
||||
its own pre-release (beta.22).
|
||||
- **Analyzers met:** MA0048 (one type per file), MA0099 (compare a flags enum with its `None`, not `0`), CS1573 (a
|
||||
`<param>` on some of a record's parameters needs one on all — `<remarks>` instead), IDE1006 (a `private const` takes
|
||||
the `_` prefix). **Mechanical, again:** a Bash heredoc halves `\\`; the Write tool writes LF and `sed -i` turns CRLF
|
||||
into LF.
|
||||
|
||||
**Owner-only, added to the list below:** item 17.
|
||||
|
||||
## Owner-only — no PR can close these
|
||||
|
||||
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
|
||||
@@ -1793,6 +2319,93 @@ release.*
|
||||
Gate shows Privacy 2.5 and Disclaimer 2.8 once. (e) The `ja` text of `Safety_AdminMode_*`, English until reviewed.
|
||||
(f) `docs/LIST_GAME_TESTED.md` — reviewed and approved by the owner before it was committed (D35, 2026-09-27);
|
||||
keep it current as games are run.
|
||||
8. **beta.11 on real hardware.** (a) GIRLS' FRONTLINE 2: the option on → *Eligible* → *Make exception…* (the disclosure
|
||||
`ac-exception-dialog/2`, with its *Trial* paragraph) → hooking on → two sessions: the card says *trial: 0 of 2*, then
|
||||
*1 of 2*, then *Exception in force since …* alone. (b) The library at your window's width, and the list; Refresh
|
||||
after installing a game, and with the USB drive unplugged (*Not installed*, the drive named). (c) Delete all sessions
|
||||
on a game's page and in Settings ▸ Data. (d) *Sessions at a glance* and the Trend with a second unit. (e) The Legal
|
||||
Gate shows the Disclaimer 2.9 and the EULA 1.4 once. (f) The `ja` text of `Safety_Exception_Trial` (English until
|
||||
reviewed) and the App strings marked `review`.
|
||||
9. **beta.12 on real hardware.** (a) **The game's memory:** one hooked game and one that is not (hooking off, or a
|
||||
blocked game), each beside Task Manager's Details tab at the same moment — the summary's *VRAM (this game)* against
|
||||
*Dedicated GPU memory*, *RAM (this game)* against *Memory (private working set)*; the Dashboard's live line; the
|
||||
Sessions columns, the Trend's memory metrics and the Sensors charts. (b) **The Legal Gate** shows the EULA 1.5, the
|
||||
Disclaimer 2.10 and the Privacy Policy 2.6 once, rendered, with the GPL as *your licence*, needing no acceptance.
|
||||
(c) **Help ▸ User guide**, **Help ▸ About** (its three tabs; *Open the licences folder* in the installed copy), and
|
||||
*View on GitHub* opening the `v0.1.0-beta.12` tag. (d) The `ja` strings marked `review` (the memory labels, the
|
||||
About window, the first-start summary). (e) `docs/LIST_GAME_TESTED.md` is as of beta.10: refresh it from a copy of
|
||||
the ledger, with the games' memory figures, and approve it before it is committed (D35).
|
||||
10. **beta.13 on real hardware.** (a) **The first delta:** update an installed `0.1.0-beta.12` through Help ▸ Check for
|
||||
updates — the download is a fraction of the full ~107 MB, and the App comes back as beta.13; if it downloaded the
|
||||
full package instead, say so (Velopack falls back silently). (b) **On this PC:** with an Easy Anti-Cheat service
|
||||
running for any game, start a hook-enabled game — the notice says the anti-cheat is running on this PC, not in
|
||||
the game. (c) **Two graphics cards**, if a machine with them is at hand: the Sensors chart's GPU figures are the
|
||||
game's card. (d) The `ja` review of the new safety strings, with the others still marked for it.
|
||||
11. **beta.14 on real hardware.** (a) **The update from beta.13:** choose *Beta* in Settings ▸ Updates, Help ▸ Check for
|
||||
updates, then *Restart to update* with no game running; Settings then reads *Automatic (Beta)*. The `velopack:` lines
|
||||
in `ui-*.log` say what was downloaded — a delta of about 2 MB; say so if it was the full package. (b) **Explorer ▸
|
||||
Properties ▸ Details** of `FrameLedger.exe` and `FrameLedger.Agent.exe` name FrameLedger and the copyright; Task Manager
|
||||
lists *FrameLedger Agent*. (c) **The wheel** on every page, the dialogs and the summary window; over a chart the wheel
|
||||
scrolls the page and Ctrl+wheel zooms; the Logs page follows the newest line. (d) **Hide scroll bars** on and off,
|
||||
without a restart. (e) **The import list in the dark theme**, and Compare's tick boxes. (f) **A crash**: an Unreal game
|
||||
that crashes reads *crashed (… CrashReportClient.exe)*; The Witcher 3 closed normally no longer reads *crashed*. (g)
|
||||
**The new measurements** on the RTX 5080: the VSync share against the game's own VSync setting, the render scale
|
||||
against the DLSS mode, the clocks, fan and limits. (h) The `ja` strings marked `review`. (i) **The Privacy Policy 2.7
|
||||
wording — before PR-5 and PR-7 merge.**
|
||||
|
||||
12. ~~**beta.15 on real hardware.**~~ **Passed 2026-10-06** — the owner ran it on real hardware and reported it OK ("đã
|
||||
chạy và ok"). *(The item as written:)* (a) **The update from beta.14:** Help ▸ Check for updates, then *Restart to update*
|
||||
with no game running — the first update in which beta.14's own step stops the Agent before Velopack applies; the
|
||||
`velopack:` lines in `ui-*.log` say what was downloaded. (b) **A quick restart:** close a hooked game and start it again
|
||||
within a few seconds; both sessions are recorded. (c) **A change of language:** English ↔ Tiếng Việt in Settings; the
|
||||
theme and channel lists, the Logs page's lists, the Games sort, the tray's menu and the Agent pill follow without a
|
||||
restart. (d) **A launcher:** `FrameLedger.Agent.exe --console launch --exe <a launcher that starts the game>`; the
|
||||
log has `election:` lines and the session is the game's. (e) **The viewer:** copy the data folder with SQLite's backup
|
||||
(`12_BUILD` §Debugging) and start `FrameLedger.exe --data-dir <copy>`; the banner names the folder, the pill reads
|
||||
*Viewer — no Agent*, the switches are off, and the installed App runs beside it untouched. (f) The `ja` strings
|
||||
marked `review`.
|
||||
13. **beta.17 on real hardware.** (a) **A theme switch:** on Settings, Dark → Light → Dark, and again with a session's
|
||||
summary window open — every description and caption follows at once. (b) **Hide scroll bars** on: the Dashboard,
|
||||
Games, a game's page, Logs, About, Help ▸ User guide and a drop-down list draw no bar, and the wheel still scrolls;
|
||||
off, the bars come back without a restart. (c) **Help ▸ User guide** lists twelve pages and Limitations; a link to a
|
||||
section opens that section. (d) **The wiki**, once the release is out: the Wiki tab shows Home, the sidebar's two
|
||||
halves and a footer naming `v0.1.0-beta.17` — then tick *Restrict editing to collaborators only* (Settings ▸ General
|
||||
▸ Features ▸ Wikis), or anyone can change a page until the next release overwrites it. (e) The `ja` strings marked
|
||||
`review`.
|
||||
14. ~~**beta.18 on real hardware.**~~ **Passed 2026-10-08** — the owner ran it on real hardware and reported it OK ("Đã
|
||||
test và ok"). *(The item as written:)* (a) **The dark theme:** every page's title and section headings — Dashboard, Games, a
|
||||
game's page, Compare, Settings, Logs — read light on the dark window, after starting in Dark, after Light → Dark, and
|
||||
after moving between pages. (b) **The overlay build** on the Dashboard's *Capture agent* card reads `v0.1.0-beta.18`,
|
||||
without `-dirty`. (c) **Disable all hooking:** turning it on says a game being measured stops within 30 seconds; with
|
||||
it on, a hooked game's notice reads "All hooking is switched off in Settings, so nothing was measured." (d) The `ja`
|
||||
strings marked `review`, `Safety_Unhooked_Unnamed_Format` among them.
|
||||
15. ~~**beta.19 on real hardware.**~~ **Passed 2026-10-12** — the owner ran it and reported (a), (c), (d)'s unplugged
|
||||
drive, (e) and (f) OK ("Các mục đã test: 1, 2. 5, 6, 4, ok"); (b) and (d)'s removal were read from the logs: Refresh
|
||||
named the existing entry instead of offering a twin, and one check at 18:04:00 removed Deadly Heart Gambit, Vibe Train
|
||||
Demo and 衔蝶 (the App's restart at 17:47 had started the ten minutes again), the library then reading *Games · 46*.
|
||||
*(The item as written:)* (a) **A Doll's Locket - Remake:** its page ▸ *Change executable…* opens in `Dolls
|
||||
Locket\`; pick `css\Game.exe`. Its launcher asks for administrator, so the runtime is measured only with *Run the agent
|
||||
as administrator* on — otherwise the session says why nothing was measured. *(Withdrawn 2026-10-13, D57: that
|
||||
launcher is malware — do not run it; `spike-notes.md` §20.)* (b) **Refresh** offers no second A Doll's
|
||||
Locket. (c) **Engine versions:** a Unity game's page (*Unity 2022.3.62f2* on Umamusume, *Unity 2019.4.40* on GIRLS'
|
||||
FRONTLINE 2), Godot's (*Godot 4.4.1* on 衔蝶), RPG Maker's (*RPG Maker MZ 1.10.0*, *RPG Maker MV 1.6.2* on Flower in
|
||||
Us, *RPG Maker VX Ace (RGSS 3.0.1)*), each with its *Engine version* line. (d) **Uninstall a game that has no session**
|
||||
(or delete a copy you added): about ten minutes later its entry is gone and the Games page says so — two removed
|
||||
together are said in one notice that names both; with the USB drive unplugged nothing is removed; *Remove uninstalled
|
||||
games* off keeps it. (e) The Legal Gate shows the Privacy Policy 2.8
|
||||
once. (f) The `ja` strings marked `review`.
|
||||
16. **beta.20 on real hardware.** (a) **Bound Between Desks:** its page reads *Ren'Py 8.5.0*, and its *Engine version*
|
||||
line says it was read from the engine's version file (`renpy/vc_version.py`); the first sweep after the update reads
|
||||
every game once more (rules `2026.10.3`). (b) The Legal Gate shows the Privacy Policy 2.9 once. (c) The `ja` string
|
||||
marked `review` (`GameDetail_EngineVersion_RenPyVcVersion`).
|
||||
17. **beta.21 on real hardware.** (a) **Wuthering Waves:** after the update, before any session, its page says hooking
|
||||
is off — Anti-Cheat Expert beside its executable, and its Steam id on the title list; Neverness To Everness stays
|
||||
blocked, and GIRLS' FRONTLINE 2's exception stays in force. (b) **Play**, in both modes of Settings ▸ Games ▸ *Play
|
||||
button*, with a Steam game, Alan Wake 2 from the Epic Games Launcher (its link has not been tried on a real game), a
|
||||
GOG game and an itch game — and in Task Manager's Details tab the game's *Elevated* column reads *No*. (c) **The
|
||||
wheel and a touchpad** in Help ▸ User guide, the licence in Help ▸ About and the Legal Gate: about three lines a
|
||||
notch, gliding; at the end of the update notes the window scrolls instead. (d) The Legal Gate shows the Privacy
|
||||
Policy 2.10 once. (e) The `ja` strings marked `review` (Play, Settings ▸ Games, `GameDetail_Supports_None`).
|
||||
|
||||
**Answered 2026-08-05, do not re-ask:** remove `gameguard` and keep `guard` (approved
|
||||
over a red `Rules` gate, with the reasoning recorded in the merge commit); vendor NVAPI
|
||||
@@ -1813,7 +2426,7 @@ deferred with a written rationale.
|
||||
way. Corrected in place.
|
||||
- **`README:14`'s RayQuery claim is not a rule-7 contradiction**, which an audit
|
||||
asserted. `03_METRICS:128` says AS-build hooking is what makes inline RayQuery
|
||||
detectable *at all*. The real contradiction is between CLAUDE.md rule 7 and
|
||||
detectable *at all* (line numbers as of 2026-08; both passages have since moved — noted 2026-10-04). The real contradiction is between CLAUDE.md rule 7 and
|
||||
`03_METRICS` — recorded as §S29(f).
|
||||
|
||||
---
|
||||
@@ -1827,7 +2440,9 @@ diagnosis*.
|
||||
sessions` against `%LOCALAPPDATA%\FrameLedger\ledger.db` applied two migration scripts, because every verb opened
|
||||
through the one migrating path. The print verbs open read-only now (`Program.PrintsOnly`; a schema older than the
|
||||
build is refused, exit 7) — but the rule that outlives the fix is: **nothing from a session is run against the
|
||||
owner's data directory unless the owner asks for exactly that**; `--data-dir` exists for everything else. The same
|
||||
owner's data directory unless the owner asks for exactly that**; `--data-dir` exists for everything else — and since
|
||||
beta.15 for the App too (`FrameLedger.exe --data-dir <copy>`, a viewer, D52), so a UI change can be looked at over a
|
||||
copy of the owner's ledger made with SQLite's backup (`12_BUILD` §Debugging). The same
|
||||
day's ledger held a whole day of rows only in a WAL a fresh connection discarded (`06_DATA_MODEL` §Migrations
|
||||
carries the shape); if `ledger: wal at open` in `agent-*.log` or `ui-*.log` reports frames that a passive checkpoint
|
||||
did not move while no other FrameLedger process is running, stop and read that note before touching the file.
|
||||
@@ -1845,8 +2460,9 @@ diagnosis*.
|
||||
flag** — and that fix did not fire, because **NW.js has no GPU process**: the GPU runs
|
||||
in-process in the browser, the one process Chromium leaves untyped. Second rule: one
|
||||
untyped candidate among typed siblings is the browser and the target. **Read the tree before
|
||||
guessing the rule** — the refusal line prints it now. Whether the Overlay can load inside
|
||||
that browser process is the next thing the title measures.
|
||||
guessing the rule** — the refusal line prints it now. ~~Whether the Overlay can load inside
|
||||
that browser process is the next thing the title measures.~~ *(Measured 2026-09-04, `spike-notes` §9 run 3: it
|
||||
loads and captures — marked 2026-10-04.)*
|
||||
- **A TITLE ASKS STREAMLINE FOR A FRAME TOKEN SEVERAL TIMES PER FRAME AND GETS A DIFFERENT
|
||||
OBJECT EACH TIME.** Cyberpunk 2077: 3 to 4.6 requests per application frame, distinct pointers,
|
||||
same index. A count keyed on the pointer reads the request rate and the `off` leg comes out
|
||||
|
||||
@@ -4,6 +4,9 @@
|
||||
measurement notes, and reviewed by the project's owner before it was published. It lists what happened on one machine;
|
||||
it promises nothing about any other.*
|
||||
|
||||
*(Not re-read for 0.1.0-beta.11 or 0.1.0-beta.12 — noted 2026-10-04. Refreshing it needs a new copy of the database and
|
||||
the owner's review; sessions since 2026-09-27, and the game-memory figures beta.12 adds, are not here.)*
|
||||
|
||||
**The machine.** Every row below was run on one PC: an NVIDIA GeForce RTX 5080 (the only graphics card), an Intel Core
|
||||
i7-14700KF, 32 GB of DDR5, Windows 11 (Insider builds 26300 → 29648) and a 2560×1440, 240 Hz monitor. **No AMD or Intel
|
||||
graphics card and no second machine has been tested**, and **no real Vulkan or OpenGL game has been measured** — every
|
||||
@@ -45,7 +48,7 @@ with the 2026-09-16 recovery and with library entries removed since.
|
||||
|
||||
| Game | Why nothing was measured | When | Evidence |
|
||||
|---|---|---|---|
|
||||
| HELLO, HELLO WORLD! | A 32-bit game (RPG Maker MV): refused by the guard once, and two sessions with hooking switched off — each recorded with its duration and sensors | 2026-09-23 | database |
|
||||
| HELLO, HELLO WORLD! | A 32-bit game (RPG Maker MV): refused by the guard once, and two sessions with hooking switched off — each recorded with its duration and sensors. *Its itch.io download puts malware in front of the game — do not run it (noted 2026-10-13, [spike-notes §20](spike-notes.md))* | 2026-09-23 | database |
|
||||
| Umamusume: Pretty Derby | Three sessions played with hooking switched off for the game | 2026-09-27 | database |
|
||||
| Sekiro: Shadows Die Twice | One session played with hooking switched off | 2026-09-25 | database |
|
||||
| GIRLS' FRONTLINE 2: EXILIUM | One session whose process Windows would not let FrameLedger open, and two recovered after the agent itself stopped mid-session (*interrupted*) | 2026-09-22 → 09-23 | database |
|
||||
@@ -59,6 +62,7 @@ with the 2026-09-16 recovery and with library entries removed since.
|
||||
| Aniimo | NetEase Yidun with a kernel driver (`NEPKernel.sys`) in the game's folder — never eligible for an exception | 2026-09-25 | [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
| Goose Goose Duck | Easy Anti-Cheat's service running, and its folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
|
||||
| Neverness To Everness | Anti-Cheat Expert's kernel driver in the game's folder | 2026-08-04 | [spike-notes §13](spike-notes.md) |
|
||||
| Wuthering Waves | Anti-Cheat Expert, kept beside the game's executable four folder levels in, where the check did not look before beta.21: a session with hooking on was injected and unhooked 37 seconds later, when the 30-second re-check met ACE's driver (`ACE-BASE.sys`); nothing was measured. Since beta.21 its folder and its Steam id refuse it before any injection *(row added 2026-10-13 from the agent's log)* | 2026-10-12 | [spike-notes §19](spike-notes.md) |
|
||||
| Counter-Strike 2 | Valve Anti-Cheat — refused by FrameLedger's title list since beta.8. On 2026-08-04 the checks alone allowed it (VAC is invisible to them); nothing was injected | 2026-08-04, beta.8 | [spike-notes §13](spike-notes.md), [19_SAFETY](19_SAFETY_AND_ANTICHEAT.md) |
|
||||
|
||||
Also refused before any injection: **Deadly Heart Gambit** — a 32-bit game (2026-08-03).
|
||||
|
||||
@@ -0,0 +1,87 @@
|
||||
# FrameLedger developer documentation
|
||||
|
||||
This folder is for people who build, change or review FrameLedger. **If you only want to use it, read the
|
||||
[user guide](../guide/README.md) instead** — it is also in the app, under Help ▸ User guide.
|
||||
|
||||
## Where to start
|
||||
|
||||
| You want to… | Read |
|
||||
|---|---|
|
||||
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (~~D1…D46~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
|
||||
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
|
||||
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
|
||||
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
|
||||
|
||||
**Status lives in four places, and nowhere else** — check a status claim against the code before you plan on it:
|
||||
|
||||
| Question | File |
|
||||
|---|---|
|
||||
| What is unresolved, and what does it block? | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) |
|
||||
| What was measured, on what machine? | [`spike-notes.md`](spike-notes.md) |
|
||||
| Which phase is where? | [`15_ROADMAP.md`](15_ROADMAP.md) |
|
||||
| What landed, in which release? | [`../CHANGELOG.md`](../CHANGELOG.md) |
|
||||
|
||||
What the software promises users is the accuracy block in [`../legal/ACCURACY.md`](../legal/ACCURACY.md), copied
|
||||
verbatim into the README and the Disclaimer and bound to its source by `tools/accuracy-check.ps1`.
|
||||
|
||||
## Reading order
|
||||
|
||||
1. [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) — the guard, the refusal list, what will not be built. It
|
||||
constrains everything else.
|
||||
2. [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) — processes, the injection flow, lifecycles, the ADRs.
|
||||
3. [`02_SPEC.md`](02_SPEC.md) — the FR / NFR ids used everywhere.
|
||||
4. [`03_METRICS.md`](03_METRICS.md) — the metric math; the source of truth for every number shown.
|
||||
5. [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) — the C++ hook layer inside the game.
|
||||
6. [`04_CAPTURE.md`](04_CAPTURE.md) — capture orchestration on the Agent's side.
|
||||
7. [`05_DETECTION.md`](05_DETECTION.md) — engine, upscaler, frame-generation and ray-tracing facts.
|
||||
8. [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) — layered telemetry, the game process's memory, vendor-SDK licence rules.
|
||||
9. [`06_DATA_MODEL.md`](06_DATA_MODEL.md) · [`07_IPC.md`](07_IPC.md) · [`08_UI.md`](08_UI.md) ·
|
||||
[`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md)
|
||||
10. The rest: [`09_I18N.md`](09_I18N.md), [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md),
|
||||
[`11_UPDATER.md`](11_UPDATER.md), [`12_BUILD.md`](12_BUILD.md), [`13_CI_CD.md`](13_CI_CD.md),
|
||||
[`14_TESTING.md`](14_TESTING.md), [`15_ROADMAP.md`](15_ROADMAP.md).
|
||||
|
||||
**Before you write native or capture code, read [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md):** its S-series items
|
||||
are safety items, and something listed there as unresolved should not be built the way an older document describes it.
|
||||
|
||||
## Every document, in one line
|
||||
|
||||
| Document | What it is for |
|
||||
|---|---|
|
||||
| [`01_ARCHITECTURE.md`](01_ARCHITECTURE.md) | The processes (App, Agent, Overlay, Vulkan layer), how injection flows, the architecture decisions |
|
||||
| [`02_SPEC.md`](02_SPEC.md) | Functional and non-functional requirements, by id |
|
||||
| [`03_METRICS.md`](03_METRICS.md) | How every number is computed: frame times, lows, stutter, frame generation, display mode, the game's memory, sensor statistics, the export schema |
|
||||
| [`04_CAPTURE.md`](04_CAPTURE.md) | The Agent's capture loop, the tiers, finalizing and recovery, the threading model |
|
||||
| [`05_DETECTION.md`](05_DETECTION.md) | Detecting engines, platforms and capabilities; the detection rules |
|
||||
| [`06_DATA_MODEL.md`](06_DATA_MODEL.md) | The SQLite schema, every migration, who writes what, retention |
|
||||
| [`07_IPC.md`](07_IPC.md) | The shared-memory ring between the game and the Agent, and the named pipe between the Agent and the App |
|
||||
| [`08_UI.md`](08_UI.md) | Every screen of the App, as specified and as built |
|
||||
| [`09_I18N.md`](09_I18N.md) | English / Vietnamese / Japanese strings, the glossary, the safety-string review rule |
|
||||
| [`10_LOGGING_AND_BUG_REPORTS.md`](10_LOGGING_AND_BUG_REPORTS.md) | Logs in every process, the bug-report bundle, redaction |
|
||||
| [`11_UPDATER.md`](11_UPDATER.md) | Velopack updates from GitHub Releases, and when an update may apply |
|
||||
| [`12_BUILD.md`](12_BUILD.md) | The toolchain, the build, the quality gate step by step, publishing and packaging |
|
||||
| [`13_CI_CD.md`](13_CI_CD.md) | The CI and release workflows |
|
||||
| [`14_TESTING.md`](14_TESTING.md) | The test strategy, hook overhead, the hardware matrix |
|
||||
| [`15_ROADMAP.md`](15_ROADMAP.md) | The phases and where each stands |
|
||||
| [`16_WPFUI_SYNTAX.md`](16_WPFUI_SYNTAX.md) | WPF UI (lepoco) rules, theming, rendered documents, gotchas |
|
||||
| [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) | The hooks inside the game: inventory, fault policy, the ring writer, Vulkan |
|
||||
| [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) | Telemetry layers (DXGI/PDH, LibreHardwareMonitor, NVAPI), the game process's memory, licences |
|
||||
| [`19_SAFETY_AND_ANTICHEAT.md`](19_SAFETY_AND_ANTICHEAT.md) | The anti-cheat guard, what a finding does, the user-mode exception, what will never be built |
|
||||
| [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) | Every unresolved question, defect and measurement, with its status marker |
|
||||
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the owner's decisions, traps |
|
||||
| [`spike-notes.md`](spike-notes.md) | What was measured, how, on which machine, and what each result decided |
|
||||
| [`LIST_GAME_TESTED.md`](LIST_GAME_TESTED.md) | The real games FrameLedger has been run with, and what each session measured (changes need the owner's review) |
|
||||
| [`legal-drift-history.md`](legal-drift-history.md) | How the legal documents once drifted from the software, and the maintainers' notes moved out of them |
|
||||
| [`vendor-exports.json`](vendor-exports.json) | The vendor DLL exports the hooks are allowed to bind, checked by `tools/vendor-exports` |
|
||||
|
||||
## Beside this folder
|
||||
|
||||
- [`../guide/`](../guide/README.md) — the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.
|
||||
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
|
||||
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
|
||||
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
|
||||
texts, the trademark note.
|
||||
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
|
||||
- [`../rules/detection-rules.json`](../rules/detection-rules.json) — engine, platform and capability signatures and the
|
||||
anti-cheat blocklist, validated by `tools/rules-validate.ps1`.
|
||||
@@ -34,3 +34,69 @@ statement is `legal/ACCURACY.md`, dated.
|
||||
> **This block is maintained by hand and nothing verifies it.** Every other document here is bound to the code by something — `rules-validate` cross-checks the blocklist, `static_assert`s bind `fl_shm.h` to `07_IPC`, `versioninfo-check` and `chokepoint-check` bind claims to binaries. `legal/` is bound by nothing, and it has now gone stale **three times**: first within hours of being written, when the 65-second sentence was added directly beneath a header that said "Three"; then again when five PRs (#40–#44) changed the Overlay from a stub into a hooking, shared-memory-mapping, control-block-reading component and touched **no documentation at all**, leaving the second bullet above asserting four things about that binary that were each false. and a third time when #46–#52 landed — seven PRs, including one (#48) that changed what the Overlay does *inside a game* — with no edit here at all. None of the three drifts was visible from inside the PR that caused it. **Whoever edits any promise in this file must re-count — and whoever changes what `FrameLedger.Overlay` does must re-read this block, because nothing will remind them.**
|
||||
>
|
||||
> **That sentence has now failed twice, so it is being replaced by something that is not a sentence.** `ci.yml` fails a pull request that touches `src/` without touching `CHANGELOG.md`. That is a weaker gate than the ones binding every other document — it forces a *ledger* entry, not a re-read of *this* file — and it is written down as weaker rather than described as a fix. A gate over the claims in `legal/` would have to assert things about behaviour rather than about files, and nobody has designed one (`docs/20_OPEN_QUESTIONS.md` §S23-6).
|
||||
|
||||
---
|
||||
|
||||
## Moved out of the accepted documents on 2026-10-03 (beta.12: Disclaimer 2.10, Privacy Policy 2.6)
|
||||
|
||||
The three blocks below were notes for the documents' maintainers inside texts a user accepts. They moved here unchanged
|
||||
when the user guide (`guide/`) and a rendered Legal Gate made those documents read as what they are — terms — and they
|
||||
are kept because they record what each version changed and why (owner decision D45).
|
||||
|
||||
### The Disclaimer's preface (versions 2.3–2.9)
|
||||
|
||||
> **How this document is kept true.** The statement of what FrameLedger measures (§4) is `legal/ACCURACY.md`,
|
||||
> embedded here and in `README.md` and bound to its source by `tools/accuracy-check.ps1`, which fails the build when a
|
||||
> copy differs. Earlier versions of this document carried a hand-maintained audit of how its own promises drifted from
|
||||
> the software — six re-counts between 2026-08-04 and 2026-09-15; that history is `docs/legal-drift-history.md`,
|
||||
> moved out of the text you accept on 2026-09-16 and kept in full.
|
||||
|
||||
### The Privacy Policy's §2 history note (versions 2.2–2.5)
|
||||
|
||||
> **History.** Versions 2.0 and 2.1 of this document listed three further rows — a weekly safety-list update, a weekly detection-rules update, and an opt-in Steam store lookup — describing requests the software did not make; from 2026-08-04 they carried an audit note saying so. Version 2.2 (2026-09-16) removes them. A privacy policy that lists a transmission which never happens is as wrong as one that omits a transmission which does.
|
||||
|
||||
### The Privacy Policy's §4 history note (versions 2.3–2.5)
|
||||
|
||||
> **History.** Version 2.3 (2026-09-23) adds the per-entry recording switch. Before it, every program in your library was recorded whenever it ran, which recorded a utility that starts with Windows at every boot.
|
||||
>
|
||||
> Version 2.4 (2026-09-25, 0.1.0-beta.8) names what the software reads to check every game in your library for anti-cheat — until then it checked only a game you asked to hook — and to name the versions of its files, and the NVIDIA driver's settings for your games. The files of a library game's folder were already read to detect its engine and features; this version is the first to say so.
|
||||
>
|
||||
> 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.10 of the Privacy Policy changed (0.1.0-beta.21)
|
||||
|
||||
§4 names the lists of installed games the Steam, GOG GALAXY, Epic Games and itch apps keep on the disk, and where GOG
|
||||
GALAXY is installed, read when the library is imported and when Play is pressed (beta.21 PR-4, owner decision D59; the
|
||||
wording approved with the plan). The import has read the Epic Games Launcher's manifests and itch's records since
|
||||
0.1.0-beta.1 without a word here — §4 named only "the store files that name it (Steam's and GOG's, on your disk)", read for
|
||||
detection; this version is the first to say so. §2 says that Play hands a game to its store's app, which may connect to
|
||||
its store, and that FrameLedger itself connects to nothing. Nothing here leaves your device, as before.
|
||||
|
||||
### What version 2.9 of the Privacy Policy changed (0.1.0-beta.20)
|
||||
|
||||
§4's list of the version marks an engine keeps in its own files gains one: the version file of a Ren'Py game's engine
|
||||
(`renpy/vc_version.py`), read to show a Ren'Py game's engine version (beta.20 PR-1, owner request 2026-10-12) — its first
|
||||
4 KiB, for the `version` line only. Nothing here leaves your device, as before.
|
||||
|
||||
### What version 2.8 of the Privacy Policy changed (0.1.0-beta.19)
|
||||
|
||||
§4 names the version marks an engine keeps in its own files, read to show a Unity, Godot or RPG Maker game's engine
|
||||
version (beta.19 PR-3, owner request 2026-10-12): Unity's player library (its version information) and the header of its
|
||||
data file, the header of a Godot data pack, an RPG Maker game's core script and `Game.ini` and the library `Game.ini`
|
||||
names. Two of them were read before and never stated: the version information of `UnityPlayer.dll` (the Unity rule's
|
||||
extractor since the detection rules began) and an RPG Maker MV/MZ game's title in `data/System.json`, which the App reads
|
||||
to name a game added by hand (since 2026-09-23). Nothing here leaves your device, as before.
|
||||
|
||||
### What version 2.7 of the Privacy Policy changed (0.1.0-beta.14)
|
||||
|
||||
§4 says two things the software reads to tell a crash from an ordinary exit: the crash reports Windows keeps in its
|
||||
Application log about a tracked game — read since P2 and never stated until 2.7 — and the names of the programs a tracked
|
||||
game starts, so that an engine's own crash reporter is recognised (beta.14 PR-5). §1 lists the graphics card's clock
|
||||
speeds, fan speed, memory temperature and power or thermal limit among the stored sensor series (beta.14 PR-7, D49): they
|
||||
were read before and are stored since.
|
||||
|
||||
### What version 2.6 of the Privacy Policy changed
|
||||
|
||||
It names the game's own memory use (since beta.12, read from outside the game in every session) where version 2.5
|
||||
named "video-memory usage reported by the graphics runtime" — an in-game figure the software never read — and adds
|
||||
§3A: what an export or a bug report can carry about you before you share it.
|
||||
@@ -2531,6 +2531,9 @@ then elects the newest tracked descendant and attaches.
|
||||
spawns — so the run is: `consent grant` the launcher, `launch` it, read the `election:` line, then
|
||||
`consent grant` the game the election named and `launch` again.
|
||||
|
||||
*(2026-10-06, beta.15: before beta.15 the `election:` line could not appear — the launch's refused outcome carried no
|
||||
launcher pid and the election returned before it logged anything. Run this table on beta.15 or later.)*
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Title / launcher | |
|
||||
@@ -2584,3 +2587,188 @@ shipped `UnrealBuildReader` once it was. Nothing was copied or written; the numb
|
||||
that scanned only a PE's `.rdata` read Black Myth as `5.0.0` from the file version alone; the 1 MiB `.rdata` floor
|
||||
(`UnrealBuildReader.MinRdataBytes`) is what moved it to the stronger rung.
|
||||
- No UE3 title is installed; the rule does not detect UE3 at all.
|
||||
|
||||
## 16 · A game process's own memory, read from outside it *(2026-10-03, beta.12, owner decision D43)*
|
||||
|
||||
**Why this was measured.** Per-process VRAM had storage since 0001 and no producer: `17_HOOK_ENGINE` §Memory planned
|
||||
`IDXGIAdapter3::QueryVideoMemoryInfo` inside the game, `20_OPEN_QUESTIONS` §M7 (2026-09-09) recorded that its
|
||||
`CurrentUsage` is the calling process's own (0 bytes from the Agent) and concluded the figure could only be read in the
|
||||
game, and §H10 left open where in the game. The owner chose the other road (D43): the documented performance counters
|
||||
`\GPU Process Memory(pid_<pid>_luid_…_phys_<n>)\Dedicated Usage` / `Shared Usage` — the numbers Task Manager's Details tab
|
||||
shows — need no handle to the game at all, and `GetProcessMemoryInfo` needs only `PROCESS_QUERY_LIMITED_INFORMATION`.
|
||||
§M7's conclusion holds for `QueryVideoMemoryInfo` and not in general.
|
||||
|
||||
**Already seen before this section was written**, stated so the table below is not read as having preceded them:
|
||||
(1) the counter set exists on the dev box, 37 instances at an idle desktop (`Get-Counter`, 2026-10-03); (2) `Dedicated
|
||||
Usage` is not `Local Usage` — dwm.exe 858 MB against 310 MB — so "dedicated" is defined as Task Manager's column and never
|
||||
compared with a DXGI budget; (3) `ctest fl_process_stats` on the RTX 5080 while the reader was being written: a 256 MiB
|
||||
DEFAULT buffer moved this process's dedicated figure 12.9 → 269.0 MiB (+256.1), and `PROCESS_MEMORY_COUNTERS_EX2` answered
|
||||
(private working set 5.2 MiB) on Windows 11 29648.
|
||||
|
||||
**The decision table, written before the runs below** (instrument: `fl-probe-processstats`, `--hold-vram` in one
|
||||
process and `--read` against it in another):
|
||||
|
||||
| # | Measurement | Outcome → what it means |
|
||||
|---|---|---|
|
||||
| M1 | Cost of one collect + read, 60 samples at 1 s | median ≤ 5 ms → 1 Hz with the sensors; 5–20 ms → still 1 Hz, noted in `18_GPU_VENDOR_APIS`; > 20 ms → every 5 s, and said so |
|
||||
| M2 | Δ dedicated of a second process holding 512 MiB | within ±2 % → "Dedicated GPU memory, as Task Manager shows it" may be written; off by > 10 % → stop, the video half does not ship |
|
||||
| M3 | dedicated against that process's own `QueryVideoMemoryInfo(LOCAL).CurrentUsage` | recorded in `03_METRICS`, whichever way it falls — the source does not change |
|
||||
| M4 | `PrivateWorkingSetSize` (EX2) against `\Process V2(<name>:<pid>)\Working Set - Private` | equal → "the same as Task Manager's Memory column"; EX2 refused → the EX fallback, and Windows 10 stays unmeasured |
|
||||
| M5 | How soon a new process's counter instance appears | recorded; the first seconds of a session reading N/A is then expected, not a fault |
|
||||
| M6 | The probe's own private bytes after 600 collections | Δ < 1 MiB → keep one query per session; more → open and close per collection, then measure again |
|
||||
|
||||
**Results (2026-10-03, the same evening; RTX 5080, driver 617.14, Windows 11 29648.1000, `fl-probe-processstats`
|
||||
from this PR's build):**
|
||||
|
||||
| # | Measured | Row taken |
|
||||
|---|---|---|
|
||||
| M1 | 60 samples at 1 s: collect + read **median 0.098 ms, max 0.217 ms**; 600 back to back: median 0.028 ms, max 0.190 ms | ≤ 5 ms → 1 Hz with the sensors |
|
||||
| M2 | holder at 8 MiB: dedicated **21.0 MiB**; holder at 512 MiB: **525.0 MiB** → Δ **512.0 MiB** for 512 MiB allocated (0.0 %); the in-process ctest earlier: +256.1 MiB for 256 | within ±2 % → "Dedicated GPU memory, as Task Manager shows it" |
|
||||
| M3 | the holder's own `CurrentUsage(LOCAL)`: 16.5 MiB (8 MiB holder) and 520.5 MiB (512 MiB holder) against dedicated 21.0 and 525.0 — **dedicated reads 4.5 MiB more, the same 4.5 MiB at both sizes** | recorded in `03_METRICS`: the counter includes a constant per-device amount the DXGI budget group does not; the difference does not grow with what the game allocates |
|
||||
| M4 | private working set (EX2) **9.1 MiB** = `\Process V2(fl-probe-processstats:<pid>)\Working Set - Private` **9.1 MiB**, in all 60 samples | equal → "the same as Task Manager's Memory column" |
|
||||
| M5 | the holder's instance was present at the reader's first poll, ~50 ms after the holder started (its device and buffer had already been created) | an instance exists from the process's first GPU allocation; a game that has made none reads N/A, as specified |
|
||||
| M6 | 600 collections: the probe's private bytes moved by **0 bytes** (−44 KB over the 60 slow ones) | < 1 MiB → one query per session |
|
||||
|
||||
**What stays unmeasured:** Windows 10 22H2 (no machine; the reader falls back to `PROCESS_MEMORY_COUNTERS_EX` where EX2 is
|
||||
refused, and the private working set then reads N/A), AMD and Intel GPUs, a laptop with two adapters (the reader sums
|
||||
every adapter's instances for the pid), and a real game — the owner's beta.12 check (HANDOFF owner-only item 9) compares
|
||||
a session's figures with Task Manager's Details tab at the same moment.
|
||||
|
||||
## 17 · Unity, Godot and RPG Maker versions in installed games *(2026-10-12, beta.19)*
|
||||
|
||||
Measured read-only on the owner's machine (i7-14700KF, RTX 5080, Windows 11 29648) before the readers were written:
|
||||
every `UnityPlayer.dll`, `*.pck`, `rmmz_core.js`, `rpg_core.js` and `RGSS*.dll` up to five levels under `D:\another`
|
||||
(GOG, itch and loose installs), `D:\SteamLibrary\steamapps\common`, Steam's own `common` and `G:\` — 23 installs, read in
|
||||
9.6 s. Then again through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`, rules `2026.10.2`), which read
|
||||
every install as tabled. Nothing was copied or written; the decision rules are in `05_DETECTION` §Engine version — Unity,
|
||||
Godot, RPG Maker.
|
||||
|
||||
| Engine | Installs | What the files say | Read as (shipped) | Detect time |
|
||||
|---|---|---|---|---|
|
||||
| Unity 2020+ | DONT GO, Dialoop, Broken Shell Demo, Deadly Heart Gambit, DreadFields, Kemono Teatime, March Out!, Umamusume, Walto, Yasha, Yu-Gi-Oh! Master Duel, 帰路, Legends of Runeterra | `UnityPlayer.dll` ProductVersion `2022.3.39f1 (4e1b0f82c39a)` … `6000.3.17f1 (cf0352b38e81)`; FileVersion `2022.3.39.5118735` (the build number where the release letter belongs) | the ProductVersion's editor version (`unity_player`) | 26 ms – 4.1 s |
|
||||
| Unity 2019.4 | A Space for the Unbound - Prologue (GOG) | ProductVersion = FileVersion `2019.4.1.15122501`; `*_Data/globalgamemanagers` byte 20: `2019.4.1f1` | `2019.4.1f1` (`unity_data`) | 102 ms |
|
||||
| Unity 2019.4 | GIRLS' FRONTLINE 2: EXILIUM | ProductVersion `2019.4.40.16762411`; the data file's header is not readable (encrypted) | `2019.4.40` (`unity_player_file`) | 2.2 s |
|
||||
| Godot 4 | Plethora of Bullets 2 (itch), 衔蝶 (Steam) | `<exe>.pck` header `GDPC`, format 2, `4.2.2` / `4.4.1`; the exe's `Godot Engine v4.4.1.stable.official` sits 57–78 MB in; 衔蝶's version resource is the studio's (`0.1.0.3`) | `4.2.2`, `4.4.1` (`godot_pck`) | 24–41 ms |
|
||||
| RPG Maker MZ | A Doll's Locket - Remake (itch) | `js/rmmz_core.js` line 2 `// rmmz_core.js v1.10.0` (also under the runtime's `css\js\`) | MZ `1.10.0` | 41–53 ms |
|
||||
| RPG Maker MV | Flower in Us (Steam), 996IR, HELLO, HELLO WORLD! (itch) | `www/js/rpg_core.js` `v1.6.2`, `v1.6.2`, `v1.6.1` (HHW's one folder above its runtime) | MV `1.6.x` | 70–275 ms |
|
||||
| RPG Maker VX Ace | City of Bones, Träumerei Chapter 2 (itch) | `Game.ini`: `Library=System\RGSS301.dll`; the DLL's version `3, 0, 1, 1` | VX Ace, RGSS `3.0.1` | 427–442 ms |
|
||||
|
||||
- **Detect time** is the whole detection of one entry — the install's walk, the rules and the second read — on the USB
|
||||
drive; the second read itself is a version resource and at most a few kilobytes. It runs once per executable and rules
|
||||
version, like Unreal's.
|
||||
- ~~**Four of the itch installs front their runtime with a 213 MB .NET launcher**~~ **Four of the itch installs put a
|
||||
213 MB .NET program in front of their runtime, and it is malware** *(corrected 2026-10-13, owner decision D57 — §20;
|
||||
do not run it)* (HELLO, HELLO WORLD!, A Doll's Locket - Remake — whose launcher asks for administrator —, City of
|
||||
Bones and Träumerei) — read as a launcher, the reason the import's choice of executable changed in the same train
|
||||
(`05_DETECTION` §Library import, D56).
|
||||
- **Not measured:** RPG Maker 2000/2003 (`RPG_RT.exe`; none installed, and no rule detects it), XP and VX (no install —
|
||||
their RGSS1/RGSS2 libraries are read by the same rule as VX Ace's, unmeasured), a Unity build older than 2019 (its
|
||||
player is the executable, with no `UnityPlayer.dll`), a Godot 3 export, and a Godot pack appended to the executable
|
||||
(both installs ship the pack beside it; the trailer the reader follows is Godot's documented layout, tested on
|
||||
synthetic files only).
|
||||
|
||||
## 18 · The Ren'Py version in an installed game *(2026-10-12, beta.20)*
|
||||
|
||||
The owner's one Ren'Py install, read-only: Bound Between Desks (Steam) — `BoundBetweenDesks.exe` (386,048 bytes, no version
|
||||
resource), `BoundBetweenDesks.py`, `game\`, `lib\py3-windows-x86_64\` (Python 3.12: `libpython3.12.dll`,
|
||||
`librenpython.dll`, `pythonw.exe`) and `renpy\` with the engine's `.py` sources beside `__pycache__\*.cpython-312.pyc`.
|
||||
|
||||
- `renpy\vc_version.py` (109 bytes, LF line ends): `branch = 'master'`, `nightly = False`, `official = True`,
|
||||
`version = '8.5.0.25111603'`, `version_name = 'In Good Health'`.
|
||||
- `renpy\__init__.py` imports those names from `vc_version` (else from `renpy.versions.get_version()`) and builds
|
||||
`version_tuple` from `version.split(".")`; `renpy.version` is `"Ren'Py " + version_only`.
|
||||
- The game's own `log.txt` (written at its last start, 2026-09-16) begins `Ren'Py 8.5.0.25111603`: the same number.
|
||||
|
||||
Then through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`, rules `2026.10.3`): `renpy 8.5.0
|
||||
renpy_vc_version` in 79 ms; Dialoop (`unity 6000.3.3f1`), Plethora of Bullets 2 (`godot 4.2.2`), A Doll's Locket - Remake
|
||||
(`rpgmaker_mv 1.10.0`) and City of Bones (`rpgmaker_rgss 3.0.1`) read as in §17.
|
||||
|
||||
- **Not measured:** an older Ren'Py (no other install), whose `vc_version.py` may name no `version` — it then reads as
|
||||
not found; a build that ships the engine compiled only (none seen).
|
||||
|
||||
## 19 · Anti-cheat beside the executable — Wuthering Waves *(2026-10-13, beta.21, owner decision D58)*
|
||||
|
||||
The owner's report: FrameLedger found no anti-cheat in `D:\SteamLibrary\steamapps\common\Wuthering Waves` (Steam
|
||||
`3513350`, Unreal Engine 4.26.2). Read-only, on the owner's disk and in the Agent's own log.
|
||||
|
||||
**The layout.** The install root holds the launcher `Wuthering Waves.exe` (483,768 bytes), `Client\`, `Engine\` and
|
||||
`ClearThirdParty.exe`; the library entry is the shipping binary `Client\Binaries\Win64\Client-Win64-Shipping.exe`
|
||||
(169,213,960 bytes). Beside it, `Client\Binaries\Win64\AntiCheatExpert\` holds Tencent's ACE: `ACE-BASE.sys`
|
||||
(4,125,432), `ACE-CORE.sys` (3,923,120) with `ACE-CORE.sys2`, `.sysa` and `.sysa2`, `ACE-Base64.dll` (69,736,848),
|
||||
`ACE-Service64.exe`, `ACE-Setup64.exe`, `ACE-Base.dat` and `pld.dat`. The folder is **four levels** under the root;
|
||||
entries per level under the root: 6, 10, 31, 276, 109, 136 (levels 1–6). Neverness To Everness keeps a second
|
||||
`AntiCheatExpert\` beside its `HTGame.exe`, at `Client\WindowsNoEditor\HT\Binaries\Win64\` — **six** levels down.
|
||||
|
||||
**Why it read clean.** Check 4 walked the install root only (since 2026-09-25), three levels deep, and a folder at the
|
||||
last level is named and never opened, silently: the walk listed `Win64` and reported a complete, clean tree. The rules
|
||||
already named the folder (`directories`: `AntiCheatExpert`); the walk never handed the name to the matcher.
|
||||
|
||||
**What it cost, from the Agent's log.** Added by import 2026-10-11 19:50:19 → `prescan: scanned 2 — anti-cheat 1, clean 1`
|
||||
(the anti-cheat was NTE's `PGameProtectDriver_X64.sys`, three levels down); re-scanned after the game's update at
|
||||
21:22:14, clean; re-added 2026-10-13 18:30:44, clean. With hooking turned on, the session of 2026-10-12 started at
|
||||
21:10:20 found nothing — ACE's driver not yet loaded, its services stopped — and was injected; at 21:10:57 the 30 s
|
||||
re-scan met `ACE-BASE.sys` (written to `System32\drivers` at 21:10 by the game's ACE setup) and unhooked:
|
||||
`SafetyUnhook; Saved (tier 1, exit=UnhookedSafety, frames=0); guard=BlockedDriver/Anti-Cheat Expert`. A driver is a
|
||||
machine-wide finding, which refuses the session and turns nothing off, so the game's hooking stayed on. Registered on
|
||||
the machine afterwards: the kernel service `ACE-BASE` (demand start) and the user-mode `AntiCheatExpert Protection`.
|
||||
|
||||
**The options, measured across the owner's 83 Steam installs** (read-only listings):
|
||||
|
||||
| Option | Cost | Newly finds | Verdict |
|
||||
|---|---|---|---|
|
||||
| Walk the executable's own folder too | ≤ 103 entries (NTE), 95 for Wuthering Waves | exactly the two `AntiCheatExpert\` folders above | **taken** |
|
||||
| Depth 3 → 4 | one constant; peak 1,627 entries (Half-Life 2) | Wuthering Waves' folder name only — NTE's is six levels down, and the folder's files stay out of reach | rejected |
|
||||
| Depth 5 or more | over 4096 entries for Yu-Gi-Oh! Master Duel (41,251), Yasha (12,215), GIRLS' FRONTLINE 2 (9,969) | — | rejected: those games would read *could not verify* and be refused at session start, GF2 under its D33 exception included |
|
||||
| Make the depth cap refuse | — | — | rejected: it would refuse nearly every game |
|
||||
|
||||
**Taken (rules `2026.10.4`):** check 4 walks the install root, then the executable's folder when it lives below the
|
||||
root (`ScanGameFolders`, `fl_prescan.cpp`), each with its own 4096-entry budget; the five `ACE-*` names join the
|
||||
`files` group, `ACE-CORE.sys` the `drivers` group, `ACE-BASE` the `services` group and `ACE-Base64.dll` a `modules`
|
||||
row of its own (so an injected Overlay stops itself if it loads); and Wuthering Waves' Steam id is on the title list.
|
||||
The version bump is what makes every game's pre-scan run again: the sweep re-scans only when the rules version or the
|
||||
executable changes.
|
||||
|
||||
- **Not measured:** that the game loads `ACE-Base64.dll` (no session has run since), and whether ACE's other titles
|
||||
keep the same layout.
|
||||
|
||||
## 20 · The launcher in front of four itch installs is malware *(2026-10-13, beta.21, owner decision D57)*
|
||||
|
||||
§17 read the 213 MB program four itch.io downloads put in front of their RPG Maker game as a *launcher*, and the
|
||||
documentation built on that reading (D28, D56's rationale, HANDOFF item 15(a), which told the owner to run A Doll's
|
||||
Locket's with the agent as administrator). Read on 2026-10-13 without running anything — file listings, the itch
|
||||
receipt, version resources, the .NET metadata strings and the files beside it — it is not a launcher. **It is malware.
|
||||
Do not run it.**
|
||||
|
||||
| Download (itch) | The program | SHA-256 | Beside it |
|
||||
|---|---|---|---|
|
||||
| HELLO, HELLO WORLD! (5015466) | `HELLOHELLOWORLD.exe`, 213,572,096 bytes | `053553514C3E34865393654477631DEFB50B36509F44B8ADC5B1E555E1F64FD1` | `locales\ml.reg`, `locales\ko.xml` |
|
||||
| A Doll's Locket - Remake (5085165) | `DollsLocket.exe`, 213,745,664 bytes | `51D3271AD0FFAF3652DAB9F66C1279CB2CA16F46A6AB2E5173D032600C1E5E53` | `data\Items.reg`, `data\Armors.xml` |
|
||||
| City of Bones | `CityofBones.exe`, 213,557,760 bytes | `CA81BE260941E7BE2D87FE6852E7DAD0D432A84F071C2C578A7BD06BE7E61248` | `System\Windowskin.reg`, `System\RGSS301.xml` |
|
||||
| Träumerei Chapter 2 | `TräumereiChapter2.exe`, 213,559,808 bytes | `65D4CCB7065227A0ED08D8977CA2F00F1E2A6DDC5F375C2C32E115D90DE29E4D` | `System\Game.reg`, `System\RGSS301.xml` |
|
||||
|
||||
- **The four programs are one .NET program**, unsigned, its version resource Visual Studio's template named after each
|
||||
game (`HELLOHELLOWORLD`, version 1.0.0.7, "Copyright © 2026"), and nearly all of its size embedded resources.
|
||||
- **Beside each, two files named like the game's own.** A 3,060-byte Windows registry file — byte-identical in all four —
|
||||
that sets `AmsiEnable = 0` under `HKCU` and `HKLM\SOFTWARE\Microsoft\Windows Script\Settings` (it switches off
|
||||
Windows' script scanning), and under `HKLM\SOFTWARE\Policies\Microsoft\Windows Defender` adds exclusions for the `.exe`
|
||||
and `.msi` extensions and for `powershell.exe`, `rundll32.exe`, `msiexec.exe` and `regasm.exe`, and sets
|
||||
`SpynetReporting = 0` and `SubmitSamplesConsent = 2` (no cloud protection, no samples sent). And a 3,216-byte `.xml`
|
||||
that is no XML: high-entropy bytes, a different blob in each download.
|
||||
- **What the program's own metadata names** (type and member names, read as strings): checks for virtual machines
|
||||
(VMware, VirtualBox, QEMU, Hyper-V, Xen, KVM, Bochs, Parallels — through WMI, the registry and the firmware) and for
|
||||
debuggers (`IsDebuggerPresent`, `CheckRemoteDebuggerPresent`, `NtQueryInformationProcess` on the debug port, object and
|
||||
flags, hardware breakpoints, debugger windows); AES decryption of Base64 text; PowerShell run inside the process
|
||||
(`CreateRunspace`, `AddScript`); registry writes; steps named `RunPayload` and `PayloadStep`; and the game it starts
|
||||
afterwards — the RPG Maker runtime beside it (`swiftshader\Game.exe`, `css\Game.exe`, `Game.exe` with
|
||||
`RGSS301.dll`), which is what makes it look like the game.
|
||||
- **Where it sits in each download:** the itch receipt of HELLO, HELLO WORLD! lists the program, the runtime in
|
||||
`swiftshader\` and both disguised files as what the download installed; nothing was added afterwards.
|
||||
|
||||
**What changes in FrameLedger (D57): the documentation, not the import.** The import still takes a store's own pick when
|
||||
it is not a helper (beta.19) — FrameLedger reads a game's files to find its engine and anti-cheat, never to judge
|
||||
whether it is safe, and a store's verdict stays the store's. What is corrected in place: §17's bullet, `05_DETECTION`
|
||||
§Library import (D56's rationale and its admin-mode sentence), HANDOFF D28, D56 and item 15(a), the beta.19 CHANGELOG
|
||||
entry, and the HELLO, HELLO WORLD! row of `LIST_GAME_TESTED.md`; `LIMITATIONS.md` says FrameLedger does not tell a safe
|
||||
game from an unsafe one.
|
||||
|
||||
- **Not measured, and not to be:** what the payload does. Nothing here was run, decrypted or uploaded anywhere.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Install and first start
|
||||
|
||||
## What you need
|
||||
|
||||
- **Windows 10 (22H2) or Windows 11, 64-bit.**
|
||||
- Games FrameLedger can measure: **64-bit DirectX 11, DirectX 12 and OpenGL games.** Other games — 32-bit games,
|
||||
DirectX 9 games, and Vulkan games you start yourself — are still recorded (how long you played, your PC's sensors,
|
||||
the game's memory use), but not measured. [Limitations](../LIMITATIONS.md) has the full list.
|
||||
|
||||
## Download and install
|
||||
|
||||
1. Download `FrameLedger.App-win-Setup.exe` from the project's
|
||||
[Releases page](https://github.com/poli0981/frameledger/releases) on GitHub.
|
||||
2. **Check the file.** Each release publishes SHA-256 checksums in `SHA256SUMS.txt`. In PowerShell:
|
||||
`Get-FileHash .\FrameLedger.App-win-Setup.exe` — the result must match the line for that file.
|
||||
3. Run it. FrameLedger is free software and is **not code-signed**, so Windows SmartScreen may warn about an unknown
|
||||
publisher. Once the checksum matches, choose **More info ▸ Run anyway**.
|
||||
|
||||
FrameLedger installs into `%LOCALAPPDATA%\FrameLedger.App` and needs no administrator rights. Your recordings are kept
|
||||
separately, in `%LOCALAPPDATA%\FrameLedger`.
|
||||
|
||||
## The first start
|
||||
|
||||
The first window walks you through four short steps:
|
||||
|
||||
1. **Before you start** — the documents. You accept three: the End User License Agreement, the Disclaimer and the
|
||||
Privacy Policy. The GNU GPL v3 is shown too: it is your licence to FrameLedger and needs no acceptance. A short
|
||||
summary sits above them, and [The terms, in plain words](terms-in-plain-words.md) explains them, but the documents
|
||||
are the terms. Declining closes FrameLedger.
|
||||
2. **The capture agent** — the background program that notices when one of your games starts and records it. It runs
|
||||
as you, without administrator rights.
|
||||
3. **What hooking means** — the difference between a game that is recorded and a game that is measured. Read
|
||||
[Anti-cheat and safety](04-anti-cheat-and-safety.md) before you switch hooking on for any game.
|
||||
4. **Your game library** — where to import it from. Nothing is measured until you choose to.
|
||||
|
||||
## Updates
|
||||
|
||||
A few seconds after it starts, FrameLedger asks GitHub whether a newer version exists. A new version downloads in the
|
||||
background and is installed only when you restart FrameLedger — never while a game is being measured, and not while a
|
||||
game it measured earlier is still running. You can switch the check off in **Settings ▸ Updates ▸ Check for updates at
|
||||
startup**, and check by hand with Help ▸ Check for updates.
|
||||
|
||||
**Settings ▸ Updates ▸ Channel** is *Automatic* unless you choose: a test version (a pre-release, like every version so
|
||||
far) looks for test versions, a release looks for releases. Choose *Stable* or *Beta* to decide yourself. Before
|
||||
0.1.0-beta.14 the channel was *Stable* by default and found no version at all — on an older copy, choose *Beta* to update.
|
||||
|
||||
## Uninstall
|
||||
|
||||
Uninstall FrameLedger from Windows Settings ▸ Apps. It asks before it deletes your recordings folder.
|
||||
@@ -0,0 +1,47 @@
|
||||
# Record a game
|
||||
|
||||
## 1. Add the game
|
||||
|
||||
- **File ▸ Add game…** — pick the game's `.exe` file.
|
||||
- **File ▸ Import library…** — FrameLedger lists the games installed through Steam, GOG, Epic and itch.io, and you
|
||||
tick the ones to add.
|
||||
|
||||
Every game is added with **hooking off**.
|
||||
|
||||
## 2. Play
|
||||
|
||||
When a game in your library starts, the capture agent records a session by itself. While it runs, the **Dashboard**
|
||||
shows it live. When the game closes, the session is saved and you get a notice. A session shorter than 30 seconds is
|
||||
not kept.
|
||||
|
||||
## Recorded, or measured
|
||||
|
||||
A game in your library is always **recorded**: how long you played, your PC's sensors (GPU temperature, load and power;
|
||||
CPU load; memory in use) and how much memory the game itself used — its video memory and its RAM, read from Windows
|
||||
from outside the game.
|
||||
|
||||
To **measure** a game — frame rate and frame times, the real render resolution, the upscaler, frame generation, ray
|
||||
tracing — FrameLedger has to load a small component into it. That is called **hooking**, and it is a choice you make
|
||||
**one game at a time**: open the game's page (Games ▸ the game) and switch **Hooking** on. A warning explains the risk
|
||||
first. **Read [Anti-cheat and safety](04-anti-cheat-and-safety.md) before you do.**
|
||||
|
||||
In the session list, **T1** marks a measured session and **T2** one that was only recorded; a recorded session says
|
||||
why it was not measured.
|
||||
|
||||
## When FrameLedger will not measure a game
|
||||
|
||||
- **It found anti-cheat.** FrameLedger then turns hooking off for that game and says why on the game's page.
|
||||
- **The game is 32-bit or uses DirectX 9.**
|
||||
- **It is a Vulkan game** you started yourself.
|
||||
- **The game runs as administrator.** Settings ▸ Capture agent ▸ *Run the agent as administrator* can help (off by
|
||||
default; Windows asks every time the agent starts). Read its risk in [Limitations](../LIMITATIONS.md) first.
|
||||
- **The game was already running when FrameLedger was updated** — restart the game once.
|
||||
|
||||
## Programs that are not games
|
||||
|
||||
Open the entry's page and switch **Recording** off: it is then ignored and nothing is recorded.
|
||||
|
||||
## Turning all hooking off
|
||||
|
||||
**Settings ▸ Capture ▸ Disable all hooking** stops every game from being hooked, whatever each game's own switch says. A
|
||||
session that is running stops measuring within 30 seconds.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Read your results
|
||||
|
||||
Open **Games ▸ a game ▸ Sessions**: one row per session. Double-click a row (or press **Open**) for the session's
|
||||
summary. The Dashboard lists your most recent sessions too.
|
||||
|
||||
## N/A means "not measured"
|
||||
|
||||
A value FrameLedger could not measure reads **N/A** — never 0, and never an estimate. A session that was only recorded
|
||||
(**T2**) has N/A for everything that needs hooking, and says why.
|
||||
|
||||
## Frame rate
|
||||
|
||||
- **When frame generation was measured**, the game's own frames and the frames you saw are shown together:
|
||||
`62 → 118 FPS (×1.9 FG)`. If frame generation changed during the session (menus, loading screens, a settings change),
|
||||
the figures are for the state that lasted longest, with the share of the session it covers: `(×1.9 FG · 75%)`.
|
||||
- **When it could not be measured**, you see **Presented FPS** with a sentence saying whether generated frames could be
|
||||
included in it. FrameLedger never shows a single number that may count generated frames as the game's own.
|
||||
- **1% low** and **0.1% low** are the frame rate of the slowest 1% and 0.1% of frames: the further they fall below the
|
||||
average, the less smooth the game felt. **Stutter** counts frames that took much longer than the frames around them,
|
||||
and the share of time they took.
|
||||
- **Time below 60 FPS** (with *below 30* and *display under* your monitor's refresh rate beneath it) is how much of the
|
||||
session ran slower than that. A game held at its limit is not counted as dropping below it for the tiny wobble every
|
||||
frame limit has. **Frame to frame** is how much one frame's time differs from the next: lower is smoother.
|
||||
- **VSync** is how many frames asked to wait for the display, and *tearing allowed* how many did not mind tearing — what
|
||||
the game asked; your graphics driver can still override it.
|
||||
- **GPU clocks**, the fan and the video memory's temperature are the card's own readings. **GPU held back** says how much
|
||||
of the time its power limit or its temperature slowed it down (NVIDIA cards only). **Frames per watt** is the game's
|
||||
own frames per second for each watt the graphics card drew — generated frames never count.
|
||||
|
||||
## Memory
|
||||
|
||||
- **VRAM (this game)** is the game's own video memory — what Task Manager's Details tab calls *Dedicated GPU memory* for
|
||||
the game's process. **RAM (this game)** is its *Memory (private working set)*. Both are read from Windows once a
|
||||
second, from outside the game, whether or not the game was hooked.
|
||||
- The **median** is the typical level during the session; the **peak** is the highest it reached.
|
||||
- *VRAM, whole graphics card* and *RAM in use, whole PC* count everything else running too, so they are usually much higher.
|
||||
- **Statistics per series**, at the bottom of the summary, lists the mean, median, minimum and peak of every sensor.
|
||||
|
||||
## Ray tracing
|
||||
|
||||
**Ray tracing**, **path tracing** and **ray reconstruction** read *Yes*, *No* or *N/A*. Ray tracing is measured on
|
||||
DirectX 12 games; path tracing is never stated as a fact, because nothing in a game's calls says so. Click a chip to
|
||||
correct it by hand — your correction is labelled as yours.
|
||||
|
||||
## Charts
|
||||
|
||||
- **Frametime** — how long each frame took. Spikes are stutters.
|
||||
- **Distribution** — how often each frame rate occurred.
|
||||
- **Render scale** — the share of the screen's resolution the game rendered at before upscaling (100% means no
|
||||
upscaling), and when it changed.
|
||||
- **Sensors** — temperatures, load and power; video memory; memory; and the card's clocks and fan, with the moments it
|
||||
was held back shaded. The game's own line and the whole card's or the whole PC's are drawn separately.
|
||||
- **Trend** (on the game's page) — one point per session over time, for example before and after a driver update.
|
||||
Changes to your hardware or driver are marked on it.
|
||||
- **Compare** (in the navigation on the left) — pick sessions, even of different games, and see them side by side.
|
||||
|
||||
To look closer, hold **Ctrl** and turn the mouse wheel over a chart to zoom, drag to pan, and double-click to reset. The
|
||||
wheel alone scrolls the page.
|
||||
|
||||
## Export
|
||||
|
||||
The summary's **Export CSV**, **Export JSON** and **Export PNG** buttons — or File ▸ Export — save a session to a file.
|
||||
Read [Your data](05-your-data.md) before you share one.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Anti-cheat and safety
|
||||
|
||||
## The risk
|
||||
|
||||
To measure a game, FrameLedger loads a small component into it ("hooking"). **Anti-cheat systems can detect that and
|
||||
may warn you, block you, or permanently ban your account** — and a ban can arrive days after the session. The developer
|
||||
cannot reverse a ban, recover progress, or speak to a game's publisher for you.
|
||||
|
||||
**Use hooking for offline and single-player games.** Switching it on for a game with online or competitive play is
|
||||
your decision and your risk.
|
||||
|
||||
## What FrameLedger does to keep the risk small
|
||||
|
||||
- **Hooking is off for every game** until you switch it on for that game, after a warning.
|
||||
- **It looks for anti-cheat** before it hooks a game and every 30 seconds while it is hooked. If it finds any, it
|
||||
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.
|
||||
|
||||
## What it cannot promise
|
||||
|
||||
- Its list of anti-cheat systems is its own and **can be incomplete**, and a game can add anti-cheat in an update.
|
||||
- Anti-cheat that starts in the middle of a session can be there for **up to 30 seconds** — in the worst case 65 —
|
||||
before FrameLedger stops.
|
||||
- Some anti-tamper software (Denuvo, for example) can make a game **crash** when it is hooked, even offline.
|
||||
|
||||
## The one exception you can make
|
||||
|
||||
**Settings ▸ Capture ▸ User-mode exceptions** (off by default). For a game whose only finding is one anti-cheat that runs
|
||||
entirely inside the game — no driver, nothing else found — you may allow hooking for that game after a separate warning.
|
||||
Its first two hooked sessions are a trial: one that does not go well ends the exception for good. FrameLedger still runs
|
||||
every check under it, and **a ban is still possible.** Kernel anti-cheat is never allowed.
|
||||
|
||||
## Turning everything off
|
||||
|
||||
**Settings ▸ Capture ▸ Disable all hooking** stops all hooking at once, whatever each game's own switch says.
|
||||
|
||||
## If FrameLedger missed a game's anti-cheat
|
||||
|
||||
Please open an issue with the **Safety gap** form on the project's GitHub page. That is treated as a safety bug, with
|
||||
the same priority as a security report. A fix reaches you with the next version you install.
|
||||
|
||||
The full statement of the risk is the [Disclaimer](../legal/DISCLAIMER.md), §2 and §2A.
|
||||
@@ -0,0 +1,50 @@
|
||||
# Your data
|
||||
|
||||
## Where it is
|
||||
|
||||
Everything FrameLedger records stays on your PC, in `%LOCALAPPDATA%\FrameLedger` (Tools ▸ Open data folder): the
|
||||
database with your library and sessions, the logs, and crash reports of FrameLedger itself. There is no account and
|
||||
nothing is uploaded. The only network requests are the update check and the update download, both to GitHub
|
||||
([Install and first start](01-install.md#updates)).
|
||||
|
||||
## What is in it
|
||||
|
||||
Your game library; your sessions — frame times when a game was measured, the statistics, your PC's sensors, the game's
|
||||
own memory use, how the game's window was shown; a short description of your hardware for each session; your tags and
|
||||
notes; your settings. The [Privacy Policy](../legal/PRIVACY_POLICY.md) lists all of it.
|
||||
|
||||
## How much is kept
|
||||
|
||||
The per-frame data of the newest **20 sessions of each game** is kept; older sessions keep their statistics. Change it
|
||||
in **Settings ▸ Recording ▸ Raw series kept per game** (0 keeps everything).
|
||||
|
||||
## Back it up
|
||||
|
||||
**Tools ▸ Database maintenance… ▸ Back up…** writes a consistent copy of the database to a file you choose, even while
|
||||
a game is being recorded. Backing up is up to you — FrameLedger does not do it by itself.
|
||||
|
||||
## Delete it
|
||||
|
||||
- **A game's sessions:** Games ▸ the game ▸ Sessions ▸ **Delete all sessions…**
|
||||
- **A game:** its page ▸ **Remove…** A game you uninstalled goes by itself when it has no sessions (Settings ▸ Data ▸
|
||||
**Remove uninstalled games**, on unless you turn it off); one with sessions stays, with them, until you remove it.
|
||||
- **Every session of every game:** Settings ▸ Data ▸ **Delete all sessions…**
|
||||
- **Everything:** uninstall FrameLedger and let it delete the data folder, or delete the folder yourself.
|
||||
|
||||
## Share it — carefully
|
||||
|
||||
An exported **CSV** or **JSON** file, 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
|
||||
in your user folder;
|
||||
- your PC's processor, graphics card, driver and Windows version;
|
||||
- your tags and notes.
|
||||
|
||||
Look at a file before you share it. **Help ▸ Report a bug…** builds the report on your PC, shows you every file in it,
|
||||
and removes your user folder's path from the logs; you decide whether to attach it to an issue on GitHub. An export is
|
||||
written as it is. Once you share a file, whoever receives it — and the site you post it to — can read it.
|
||||
|
||||
## Updating and going back
|
||||
|
||||
A new version upgrades the database in place. **An older version cannot open it afterwards** — there is no downgrade,
|
||||
so keep a backup if you might want to go back.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Questions and answers
|
||||
|
||||
## Why does my session say N/A everywhere?
|
||||
|
||||
The game was recorded, not measured (**T2**): hooking is off for it, FrameLedger found anti-cheat, or the game is one
|
||||
FrameLedger cannot measure. The session's summary says which. See [Record a game](02-record-a-game.md).
|
||||
|
||||
## I switched hooking on, and the game is still not measured.
|
||||
|
||||
FrameLedger refuses a game where it finds anti-cheat, and cannot measure 32-bit games, DirectX 9 games, Vulkan games you
|
||||
start yourself, or a game that runs as administrator (unless the agent does too). A game that was already running when
|
||||
FrameLedger updated needs one restart. The game's page and the session's summary say what happened.
|
||||
|
||||
## Why "Presented FPS" and not the game's own frame rate?
|
||||
|
||||
Because frame generation could not be measured in that session. Presented FPS counts every frame the game handed to
|
||||
Windows, and the sentence beside it says whether generated frames could be among them. FrameLedger never labels a
|
||||
number that may include generated frames as the game's own.
|
||||
|
||||
## Why is the video memory different from my in-game overlay?
|
||||
|
||||
FrameLedger shows what Task Manager shows for the game's process: its *Dedicated GPU memory*. Overlays often show the
|
||||
whole graphics card's use, which includes every other program, or the amount the game is allowed to use. FrameLedger
|
||||
shows the whole card's figure too, separately.
|
||||
|
||||
## Why is the CPU temperature N/A?
|
||||
|
||||
Reading it needs *Run the agent as administrator* (Settings ▸ Capture agent) and the separately installed PawnIO
|
||||
driver — and that reading has not been checked on real hardware yet. CPU load needs neither.
|
||||
|
||||
## Windows warned me when I installed FrameLedger.
|
||||
|
||||
FrameLedger is not code-signed, so SmartScreen does not know its publisher. Check the download against the published
|
||||
SHA-256 checksum before you run it ([Install and first start](01-install.md)).
|
||||
|
||||
## Can I use FrameLedger with online games?
|
||||
|
||||
Recording works with any game. **Hooking** an online or competitive game risks your account — see
|
||||
[Anti-cheat and safety](04-anti-cheat-and-safety.md).
|
||||
|
||||
## Something is wrong. How do I report it?
|
||||
|
||||
**Help ▸ Report a bug…** builds a report on your PC and opens the issue form on GitHub; you decide what to attach. If
|
||||
FrameLedger missed a game's anti-cheat, use the **Safety gap** form instead.
|
||||
|
||||
## Where are the full documents?
|
||||
|
||||
**Help ▸ About ▸ Legal documents**, or Settings ▸ Legal ▸ Reopen the legal documents. What FrameLedger cannot do is in
|
||||
[Limitations](../LIMITATIONS.md).
|
||||
@@ -0,0 +1,126 @@
|
||||
# The screens
|
||||
|
||||
What each part of FrameLedger shows and what each button does. What the numbers mean is in
|
||||
[Read your results](03-read-your-results.md); every setting is in [Every setting](08-settings.md).
|
||||
|
||||
## The main window
|
||||
|
||||
**The badge at the top right** says how the capture agent is doing:
|
||||
|
||||
| Badge | Meaning |
|
||||
|---|---|
|
||||
| Agent connected | Everything works. |
|
||||
| Connecting to agent… · Starting agent… | FrameLedger is reaching the agent, or starting it. Give it a few seconds. |
|
||||
| Waiting for administrator permission… | *Run the agent as administrator* is on, and Windows is asking you. |
|
||||
| Agent offline | The agent is installed but does not answer. FrameLedger keeps trying; **Retry** on the banner tries now. |
|
||||
| Agent not installed | `FrameLedger.Agent.exe` is missing: install FrameLedger again. |
|
||||
| Viewer — no Agent | You opened a copy of a data folder to look at ([When something goes wrong](09-troubleshooting.md#looking-at-a-copy-of-your-data)). |
|
||||
|
||||
**Banners** under the menus stay until you act on them: *Capture agent offline* with **Retry**; *Update* with **Restart to
|
||||
update** (it waits while a game is being recorded); and the safety notices — a game's hooking refused, measurement
|
||||
stopped, hooking turned off — each with one button that only says you have read it.
|
||||
|
||||
**The pages** are on the left: **Dashboard**, **Games**, **Compare**, **Logs**, and **Settings** at the bottom.
|
||||
|
||||
## The menus
|
||||
|
||||
| Menu | Item | What it does |
|
||||
|---|---|---|
|
||||
| **File** | **Add game…** | Pick a game's `.exe` file. It is added with hooking off, and its page opens. |
|
||||
| | **Import library…** | A checklist of the games installed through Steam, GOG Galaxy, Epic and itch.io. |
|
||||
| | **Export** ▸ **Session CSV** · **Session JSON** · **Chart PNG** | Saves the session you last selected or opened. Read [Your data](05-your-data.md) before you share a file. |
|
||||
| | **Exit** | Quits FrameLedger, even when *Minimize to tray on close* is on. |
|
||||
| **Tools** | **Agent status…** | Opens the Dashboard, where the agent's card is. |
|
||||
| | **Update detection rules** | The agent reads its detection rules again and checks your games again. |
|
||||
| | **Vulkan layer registration…** | Opens Settings, where the Vulkan layer is. |
|
||||
| | **Open data folder** | Opens `%LOCALAPPDATA%\FrameLedger` in Explorer. |
|
||||
| | **Database maintenance…** | **Check**, **Back up…**, **Sweep…** and **Compact** your database ([When something goes wrong](09-troubleshooting.md#the-database)). |
|
||||
| **Help** | **User guide** | This guide. |
|
||||
| | **Check for updates** | Asks GitHub now. |
|
||||
| | **Report a bug…** | Builds a report on your PC ([When something goes wrong](09-troubleshooting.md#report-a-problem)). |
|
||||
| | **Online documentation** | The project's page on GitHub. |
|
||||
| | **Limitations** | What FrameLedger cannot do. |
|
||||
| | **About FrameLedger** | The version, the licences and the notices. |
|
||||
|
||||
## Dashboard
|
||||
|
||||
- **Live capture** — the game being recorded right now: its name, **T1** (measured) or **T2** (recorded only), and the
|
||||
time so far. While it is measured: the frame rate, the resolution, the upscaler, frame generation, ray tracing, the GPU
|
||||
and CPU temperatures and the game's memory. *Attached — waiting for the first frames…* means hooking worked and the
|
||||
first frames are on their way.
|
||||
- **Games tracked**, **Total playtime**, **Sessions this week**.
|
||||
- **Capture agent** — *State*, *Agent version*, *Telemetry source* (which sensor readers work on this PC: `l1` is
|
||||
Windows itself, `lhm` is LibreHardwareMonitor, `nvapi` is NVIDIA's own and only on NVIDIA cards), *Overlay build* (the
|
||||
version of the component loaded into games), *Elevated* (whether the agent runs as administrator) and *Running
|
||||
sessions*. Everything reads N/A until the agent answers.
|
||||
- **Recent sessions** — the ten newest. Click one to open its summary.
|
||||
|
||||
## Games
|
||||
|
||||
- **Search games**; sort by **Name**, **Last played** or **Playtime**; **Show as a list** or **Show as a grid**.
|
||||
- **Refresh** reads your library again: it offers games newly installed through a store, and marks a game whose `.exe`
|
||||
is gone as *Not installed*. The agent removes such a game by itself after ten minutes when it has no sessions and its
|
||||
drive is connected — never one where anti-cheat was found (**Settings ▸ Data ▸ Remove uninstalled games** turns this
|
||||
off).
|
||||
- **Add game…** — or drop `.exe` files onto the page.
|
||||
- Each game shows its name, its store and engine, and one state: **Hooking on**, **Hooking off**, **Anti-cheat** (found,
|
||||
so it is not hooked), **Exception** (a user-mode exception is in force) or **Not recorded**; then its sessions,
|
||||
playtime and last play. Click it to open its page (in the list: double-click, or Enter). Its **Play** button (on the
|
||||
card's corner; the list's first column) starts it as the game's page does.
|
||||
|
||||
## A game's page
|
||||
|
||||
- **At the top:** the name, publisher, version, store and engine, the `.exe` path, the last session, the last measured
|
||||
session's frame rate and its ray-tracing chips. **Play** starts the game: through the store that installed it, or
|
||||
directly — **Settings ▸ Games ▸ Play button** chooses. **Edit…** changes the name, publisher, version and notes. **Change
|
||||
executable…** points the entry at another `.exe` and turns hooking back off; its file dialog opens in the game's own
|
||||
folder. **Remove…** asks whether to keep the game's sessions.
|
||||
- **Recording** — off, FrameLedger ignores the program completely: for a launcher or a tool that is not a game.
|
||||
- **Hooking** — on, the game is measured. A warning comes first, and you type `I ACCEPT THE INJECTION RISK` to go on.
|
||||
Read [Anti-cheat and safety](04-anti-cheat-and-safety.md) before you do.
|
||||
- **Anti-cheat** — shown in its place when anti-cheat was found: what was found, and where. **User-mode exception**
|
||||
appears when the game qualifies for the one exception.
|
||||
- **Supports** and **Details** — what the game's own files contain, as far as FrameLedger can tell.
|
||||
- **Tabs:** **Sessions** (every session: double-click a row or press **Open**; **Delete all sessions…** at the top),
|
||||
**Frametime**, **Distribution**, **Trend** (one point per session for a figure you choose, with changes to your
|
||||
hardware or driver marked), **Sensors**, and **Latency** when the game reported it.
|
||||
|
||||
## A session's summary
|
||||
|
||||
It opens from a session row, from the Dashboard, and from the notice when a session is saved.
|
||||
|
||||
- A warning at the top when the game crashed or measuring stopped early.
|
||||
- The **Ray Tracing**, **Path Tracing** and **Ray Reconstruction** chips: click one to correct it by hand, for this
|
||||
session or as the game's default. Your correction is labelled as yours.
|
||||
- The figures, the charts and **Statistics per series** — [Read your results](03-read-your-results.md) explains each.
|
||||
- **Tags and notes** with **Save**, and **Export CSV**, **Export JSON**, **Export PNG**.
|
||||
|
||||
## Compare
|
||||
|
||||
Tick **2 to 5 sessions**, from any of your games, and press **Compare**: one frame-rate curve per measured session, and
|
||||
a table with the best value of each row in bold. Comparing a measured session with an unmeasured one asks first,
|
||||
because they measured different things.
|
||||
|
||||
## Logs
|
||||
|
||||
What FrameLedger and its agent wrote down. Choose **App** or **Agent**, a level, and search; **Pause** stops the view from
|
||||
following new lines. **Open logs folder**, and **Export bug bundle**, which does the same as Help ▸ Report a bug….
|
||||
|
||||
## Settings
|
||||
|
||||
Every switch and box is described in [Every setting](08-settings.md).
|
||||
|
||||
## The tray icon
|
||||
|
||||
The icon by the clock has **Open FrameLedger**, **Pause capture** / **Resume capture**, **Agent status** and **Exit**; a
|
||||
click on it opens the window. **Pause capture** stops measuring the running sessions until you resume, and the paused
|
||||
stretch is left out of their figures. While the window is hidden, a notice pops up when a session is saved or an update
|
||||
is ready.
|
||||
|
||||
## Keyboard and mouse
|
||||
|
||||
- **Ctrl+1** … **Ctrl+5** open Dashboard, Games, Compare, Logs and Settings.
|
||||
- **Alt** or **F10** moves to the menus.
|
||||
- **Esc** closes a dialog the way its Close or Cancel button does.
|
||||
- Over a chart, **Ctrl** and the mouse wheel zoom, dragging pans, and a double-click resets. The wheel alone scrolls the
|
||||
page.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Every setting
|
||||
|
||||
Settings is the last item on the left. Its sections follow, in the order it shows them. Settings marked *agent* are read
|
||||
by the capture agent; unless the row says otherwise, a change applies from the next session.
|
||||
|
||||
## Capture
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Disable all hooking** | Nothing is loaded into any game, whatever each game's own switch says. A game being measured stops being measured at the next safety check, within 30 seconds. Sessions are still recorded. *Agent.* | Off |
|
||||
| **Games with hooking on** | Shown while any game has hooking on: one **Turn off** per game. | — |
|
||||
| **Hide hooking on anti-cheat games** | On, the page of a game where anti-cheat was found shows only what was found; off, it also shows the Hooking switch, greyed out. Such a game is never hooked either way. | On |
|
||||
| **Allow hooking in games whose only anti-cheat runs in user mode** | Turns on the one narrow exception ([Anti-cheat and safety](04-anti-cheat-and-safety.md#the-one-exception-you-can-make)). The games that qualify are listed under it, each with **Make exception…** (after a warning) or **Withdraw**. *Agent.* | Off |
|
||||
| **Vulkan layer** | The component that measures Vulkan games — but only a game FrameLedger starts itself: **Play** set to *Start directly* (Games, below) does; a Vulkan game started any other way is recorded, not measured. The agent registers and removes it by itself; **Register** and **Unregister** repair that, for your Windows user only. | — |
|
||||
|
||||
The link under them, *Read what the hook does and does not do*, opens the safety document on GitHub.
|
||||
|
||||
## Recording
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **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. *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 |
|
||||
|
||||
## Data
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Remove uninstalled games** | A game whose `.exe` has been gone for ten minutes is removed from your library — only when it has no sessions, its drive is connected and the folder it was installed in is still there (an unplugged drive never counts), and never a game where anti-cheat was found. Off, it stays and reads *Not installed*. *Agent*, within 15 seconds. | On |
|
||||
| **Delete all sessions** | Deletes every session of every game, with its data and notes, after asking. Your library, your settings and each game's hooking choice stay. It cannot be undone, and it is refused while a game is being recorded. | — |
|
||||
|
||||
## Capture agent
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Run the agent as administrator** | Lets FrameLedger measure games that run as administrator, and read CPU temperature with PawnIO installed. Windows asks every time the agent starts, at logon too. A warning explains the risk first; read [Limitations](../LIMITATIONS.md#running-the-agent-as-administrator). The agent restarts to apply it, or at its next start if a game is being recorded. | Off |
|
||||
| **Start the agent at logon** | **Register**, **Repair** or **Remove** a task that starts the agent when you log on, for your user only and without administrator rights. Without it, FrameLedger starts the agent when you open it. | Not installed |
|
||||
|
||||
## Appearance
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Theme** | Follow system, Light or Dark. Applies at once. | Follow system |
|
||||
| **Language** | English, Tiếng Việt or 日本語. The window is rebuilt in the new language at once. | English |
|
||||
|
||||
## Games
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Play button** | What **Play** does, on a game's page and on each game in the library. *Through the store*: Steam or the Epic Games Launcher starts the game, GOG GALAXY runs it, and the itch app asks which copy to launch — each store's app does what it does when you start a game from it. A game no store installed, and a GOG game without GOG GALAXY, is started by FrameLedger instead; so is every game while FrameLedger itself runs as administrator, so that the game does not. *Start directly*: FrameLedger's agent starts the game, recorded from its first frame, with your standard rights; it does not start a game whose recording is off, or one that asks to run as administrator. | Through the store |
|
||||
|
||||
## Window
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Start FrameLedger with Windows** | Opens FrameLedger when you log on, for your user only. | Off |
|
||||
| **Minimize to tray on close** | Closing the window keeps FrameLedger running by the clock; quit with **Exit** in the tray's menu or the File menu. | Off |
|
||||
| **Show FPS with two decimals** | Every frame rate with two decimals (62.40) instead of a whole number (62). Pages show it when they next open. | Off |
|
||||
| **Hide scroll bars** | No scroll bars are drawn anywhere; the wheel, the keyboard and touch still scroll. Applies at once. | Off |
|
||||
|
||||
## Updates
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Channel** | *Automatic* follows your copy: a test version (a pre-release) looks for test versions, a release for releases. Or choose *Stable*, or *Beta* (releases and pre-releases). | Automatic |
|
||||
| **Check for updates at startup** | One question to GitHub a few seconds after FrameLedger starts. A new version downloads in the background and installs only when you restart. | On |
|
||||
|
||||
## Logging
|
||||
|
||||
| Setting | What it does | Default |
|
||||
|---|---|---|
|
||||
| **Debug logging** | FrameLedger writes far more detail into its log, for a bug report. The agent keeps its own level. | Off |
|
||||
|
||||
## System
|
||||
|
||||
This PC as FrameLedger records it with every session: processor, graphics card and driver, memory, Windows build and
|
||||
the main display. Nothing is sent anywhere. **Copy** puts the lines on the clipboard, for a bug report.
|
||||
|
||||
## Legal
|
||||
|
||||
**Reopen the legal documents** shows the documents you accepted, and the GPL, again. Nothing is accepted again.
|
||||
@@ -0,0 +1,98 @@
|
||||
# When something goes wrong
|
||||
|
||||
Find what you see, then what it means and what to do. Questions that are not problems are in
|
||||
[Questions and answers](06-faq.md).
|
||||
|
||||
## The capture agent is not working
|
||||
|
||||
| You see | It means | Do this |
|
||||
|---|---|---|
|
||||
| **Connecting to agent…** or **Starting agent…** | FrameLedger is reaching its agent, or starting it. | Wait a few seconds. |
|
||||
| **Agent offline**, and a banner: *The capture agent is not answering* | The agent is installed but does not answer. Your library, sessions and charts still work; only what is live does not. FrameLedger keeps trying. | **Retry** on the banner, or close FrameLedger and open it again. |
|
||||
| **Agent not installed** | `FrameLedger.Agent.exe` is missing from FrameLedger's folder. | Install FrameLedger again from the [Releases page](https://github.com/poli0981/frameledger/releases). |
|
||||
| **Waiting for administrator permission…** | *Run the agent as administrator* is on, and Windows is asking. The prompt may be waiting on the taskbar. | Answer it — or switch the option off in Settings ▸ Capture agent. |
|
||||
| Settings says *the administrator prompt was declined* | The agent runs with your normal rights. | Nothing, unless you need it ([Every setting](08-settings.md#capture-agent)). |
|
||||
|
||||
## A game was recorded but not measured
|
||||
|
||||
The session is **T2**, its frame figures read N/A, and its summary says why on the **Why:** line — go by that line.
|
||||
While the game runs, a notice may say *hooking refused*.
|
||||
|
||||
| Why | Do this |
|
||||
|---|---|
|
||||
| Hooking was off for the game. | Switch **Hooking** on in the game's page, after reading [Anti-cheat and safety](04-anti-cheat-and-safety.md). |
|
||||
| The game's file changed since hooking was switched on — an update, usually. | Switch hooking on again for it. |
|
||||
| The game you added is its launcher. | Add the game's own `.exe` too: hooking a launcher does not reach the game it starts. |
|
||||
| Anti-cheat was found in the game. | Nothing: FrameLedger will not hook it, and hooking stays off. The only exception is narrow ([Anti-cheat and safety](04-anti-cheat-and-safety.md#the-one-exception-you-can-make)). |
|
||||
| An anti-cheat driver or service was running on the PC. It may belong to another game. | Close the program it belongs to: the next session is measured again. |
|
||||
| Anti-cheat appeared while the game was running. | Nothing: measuring stopped, and the summary says *Measurement stopped early*. |
|
||||
| FrameLedger could not check the game's files. | It checks again by itself; Tools ▸ Update detection rules checks now. |
|
||||
| The game runs as administrator. | Settings ▸ Capture agent ▸ *Run the agent as administrator* — read its risk in [Limitations](../LIMITATIONS.md#running-the-agent-as-administrator) first. A game protected by an anti-cheat driver cannot be measured either way. |
|
||||
| The game is 32-bit, uses DirectX 9, or uses Vulkan. | Nothing: these are recorded, not measured ([Limitations](../LIMITATIONS.md#games-it-will-not-measure)). |
|
||||
| **Disable all hooking** is on. | Switch it off in Settings ▸ Capture. |
|
||||
| The game was already running when FrameLedger was updated. | Close the game and start it again. |
|
||||
| Hooking was switched off after the game crashed twice soon after it started. | Switch it on again in the game's page if the cause may be gone — after a driver update, for example. |
|
||||
| The game's file is gone. | If only its drive letter changed, FrameLedger follows it within about 15 seconds; otherwise **Change executable…** on the game's page. |
|
||||
| The component could not be loaded into the game. | [Report a problem](#report-a-problem). |
|
||||
|
||||
## Some numbers read N/A
|
||||
|
||||
- **Everything** reads N/A: the session was not measured — see above.
|
||||
- **1% low** needs 1,000 of the game's own frames, and **0.1% low** 10,000: a shorter session reads N/A for them.
|
||||
- **VSync** reads N/A for OpenGL games.
|
||||
- **VRAM (this game)** reads N/A for the game's first second.
|
||||
- **GPU sensors** on AMD and Intel cards have not been tested, and **GPU held back** is read on NVIDIA cards only.
|
||||
- **A session's charts are gone**: its per-frame data was removed under *Raw series kept per game*
|
||||
([Every setting](08-settings.md#recording)); its statistics stay.
|
||||
- **Presented FPS** instead of the game's own frame rate, **video memory** that differs from an in-game overlay, and
|
||||
**CPU temperature**: see [Questions and answers](06-faq.md).
|
||||
|
||||
## A session says the game crashed
|
||||
|
||||
*How it ended*, on the session's summary:
|
||||
|
||||
| It says | It means |
|
||||
|---|---|
|
||||
| ended normally | The game closed by itself. |
|
||||
| ended with exit code 1 | What *End task* or `taskkill` leaves behind: not a crash. |
|
||||
| crashed (0xC0000005 …) | The game ended with an error code. *0xC0000006* often points at a failing drive. |
|
||||
| crashed (Windows logged an application error) | Windows recorded the game's crash. |
|
||||
| crashed (the game started its crash reporter, …) | The game's own crash reporter started while it was ending. |
|
||||
| interrupted | The agent itself stopped during the session; the session was rebuilt when the agent next started. |
|
||||
|
||||
More in [Limitations](../LIMITATIONS.md#when-a-game-crashed). If FrameLedger itself stops, it says *FrameLedger stopped
|
||||
unexpectedly* and offers to report it.
|
||||
|
||||
## An update does not install
|
||||
|
||||
- *A session is running, so it is applied only after the session ends* — restart FrameLedger once the game has closed.
|
||||
- *… is still loaded in a game FrameLedger measured* — close that game, then **Restart to update**.
|
||||
- *Try again in about an hour* — GitHub limits how often it is asked. *Offline* — no connection.
|
||||
- A download that fails its check twice: [report a problem](#report-a-problem).
|
||||
- Windows warns about the installer: see [Install and first start](01-install.md#download-and-install).
|
||||
|
||||
## The database
|
||||
|
||||
Everything is in one file, the ledger. **Tools ▸ Database maintenance…**:
|
||||
|
||||
- **Check** reads the whole file. If it finds a problem, **Back up…** first, then [report a problem](#report-a-problem).
|
||||
- **Back up…** writes a consistent copy wherever you choose, even while a game is recorded.
|
||||
- **Sweep…** removes old per-frame data, as *Raw series kept per game* does; it needs the agent running.
|
||||
- **Compact** gives freed space back to the disk; it waits until no game is being recorded.
|
||||
- *The ledger was busy* — try again in a moment.
|
||||
|
||||
## Looking at a copy of your data
|
||||
|
||||
`FrameLedger.exe --data-dir <folder>` opens a **copy** of a data folder to look at — one sent with a bug report, for
|
||||
example. The badge reads **Viewer — no Agent**: nothing is recorded and nothing on this PC is changed. It refuses your own
|
||||
data folder.
|
||||
|
||||
## Report a problem
|
||||
|
||||
- **Help ▸ Report a bug…** (or Logs ▸ Export bug bundle) saves a zip on your PC with FrameLedger's logs, a description of
|
||||
your PC and your settings — and, if you tick them, FrameLedger's last crash dump and the last session without its
|
||||
frames, notes or tags. Your Windows user name is removed from the paths in the logs; the crash dump is not cleaned.
|
||||
You see every file, then the issue form opens on GitHub, and you add the zip yourself: FrameLedger sends nothing.
|
||||
- The logs are in `%LOCALAPPDATA%\FrameLedger\logs` (Logs ▸ Open logs folder).
|
||||
- If FrameLedger missed a game's anti-cheat, use the **Safety gap** form instead
|
||||
([Anti-cheat and safety](04-anti-cheat-and-safety.md#if-frameledger-missed-a-games-anti-cheat)).
|
||||
@@ -0,0 +1,60 @@
|
||||
# Words FrameLedger uses
|
||||
|
||||
What the words on FrameLedger's screens mean, in alphabetical order. How each figure is computed is in the developers'
|
||||
[metrics document](../docs/03_METRICS.md).
|
||||
|
||||
- **0.1% low, 1% low** — the frame rate of the game's slowest 0.1% and 1% of frames. The further they fall below the
|
||||
average, the less smooth the game felt. They need 10,000 and 1,000 of the game's own frames.
|
||||
- **Agent** (the capture agent) — the program FrameLedger runs in the background, with your normal rights, that notices
|
||||
a game starting and records it.
|
||||
- **Anti-cheat finding** — what FrameLedger's anti-cheat check found for a game: a component loaded into it, a file or
|
||||
folder of it, or the game itself on a list. A game with a finding is not hooked ([Anti-cheat and
|
||||
safety](04-anti-cheat-and-safety.md)).
|
||||
- **Bug bundle** — the zip **Help ▸ Report a bug…** writes on your PC. Nothing is sent by FrameLedger.
|
||||
- **Compare** — two to five sessions side by side, from any of your games.
|
||||
- **Disable all hooking** — the switch that stops every game from being hooked at once, whatever each game's own switch
|
||||
says. Sessions are still recorded.
|
||||
- **Displayed FPS** — the frames you saw, generated frames included.
|
||||
- **FG factor** — Displayed FPS divided by Native FPS, shown as `×1.9 FG`.
|
||||
- **FPS** — frames per second over the time measured.
|
||||
- **Frame generation** — the technology (DLSS Frame Generation, FSR Frame Generation) that inserts frames the game did
|
||||
not render itself.
|
||||
- **Frame time** — how long one frame took, in milliseconds.
|
||||
- **Frame to frame** — how much one frame's time differs from the next. Lower is smoother.
|
||||
- **Frames per watt** — the game's own frames per second for each watt the graphics card drew.
|
||||
- **GPU held back** — how much of the time the card's power limit or its temperature slowed it down. NVIDIA cards only.
|
||||
- **Hooking** — loading FrameLedger's small component into a game to measure it. Off for every game until you switch
|
||||
it on for that game.
|
||||
- **Ledger** — the one database file that holds your library and sessions, `%LOCALAPPDATA%\FrameLedger\ledger.db`.
|
||||
- **N/A** — not measured. Never 0, and never an estimate.
|
||||
- **Native FPS** — the frames the game rendered itself.
|
||||
- **Overlay build** — the version of the component that hooking loads into a game. It draws nothing on your screen.
|
||||
- **Override** — your own Yes, No or N/A for a ray-tracing chip. The measured value is kept, and yours is marked as
|
||||
yours.
|
||||
- **Presented FPS** — every frame the game handed to Windows, shown when frame generation could not be measured, with a
|
||||
note saying whether generated frames could be among them.
|
||||
- **RAM (this game)** — the game's own memory, what Task Manager's Details tab shows as its private working set.
|
||||
- **Ray tracing, Path tracing, Ray reconstruction** — read *Yes*, *No* or *N/A*. Ray tracing is measured on DirectX 12
|
||||
games; path tracing is never stated as a fact.
|
||||
- **Render scale** — the share of the screen's resolution the game drew at before upscaling. 100% means no upscaling.
|
||||
- **Session** — one run of a game, from its start to its end. A session shorter than 30 seconds is not kept.
|
||||
- **Steady state** — when frame generation changed during a session (menus, loading screens, a settings change), the
|
||||
figures are for the state that lasted longest, with the share of the session it covers: `×1.9 FG · 75%`.
|
||||
- **Stutter** — frames that took more than twice as long as the frames around them, counted, with the share of time
|
||||
they took.
|
||||
- **T1** — a measured session. **T2** — a session that was only recorded: how long you played, your PC's sensors and
|
||||
the game's memory, with every frame figure N/A.
|
||||
- **Tags and notes** — what you write on a session's summary.
|
||||
- **Telemetry source** — which sensor readers work on this PC: `l1` is Windows itself, `lhm` is LibreHardwareMonitor,
|
||||
`nvapi` is NVIDIA's own.
|
||||
- **Time below 60 FPS** — how much of the session ran slower than 60 frames per second (and *below 30*, and *below your
|
||||
display's refresh rate*), not counting the tiny wobble of a game held at its frame limit.
|
||||
- **Trend** — one point per measured session over time, on a game's page.
|
||||
- **Upscaler** — the technology that draws the game at a lower resolution and scales it up (DLSS, FSR).
|
||||
- **User-mode exception** — the one way to hook a game where anti-cheat was found: only an anti-cheat that runs entirely
|
||||
inside the game, one game at a time, after a warning. Its first two sessions are a trial.
|
||||
- **Viewer** — FrameLedger opened over a copy of a data folder: no agent, nothing recorded, nothing changed.
|
||||
- **VRAM (this game)** — the game's own video memory, what Task Manager shows as its *Dedicated GPU memory*.
|
||||
- **VSync** — how many frames asked to wait for the display; *tearing allowed*, how many did not mind tearing. It is
|
||||
what the game asked: your graphics driver can override it.
|
||||
- **Vulkan layer** — the component that measures Vulkan games, used only when FrameLedger starts a game itself.
|
||||
@@ -0,0 +1,28 @@
|
||||
# FrameLedger user guide
|
||||
|
||||
FrameLedger records how your games run on this PC — frame rate, frame times, the settings a game is really rendering
|
||||
with, temperatures, and how much memory the game uses — and keeps every session so you can compare them later.
|
||||
Everything stays on your PC.
|
||||
|
||||
Each page below takes a minute or two to read. The first six are the guide; the next four are there to look things up.
|
||||
|
||||
1. [Install and first start](01-install.md)
|
||||
2. [Record a game](02-record-a-game.md)
|
||||
3. [Read your results](03-read-your-results.md)
|
||||
4. [Anti-cheat and safety](04-anti-cheat-and-safety.md) — read this before you switch hooking on for any game
|
||||
5. [Your data](05-your-data.md)
|
||||
6. [Questions and answers](06-faq.md)
|
||||
7. [The screens](07-screens.md) — what each page, menu and button does
|
||||
8. [Every setting](08-settings.md)
|
||||
9. [When something goes wrong](09-troubleshooting.md)
|
||||
10. [Words FrameLedger uses](10-glossary.md)
|
||||
11. [The terms, in plain words](terms-in-plain-words.md)
|
||||
|
||||
What FrameLedger cannot do is listed on its own page: [Limitations](../LIMITATIONS.md) (in the app: Help ▸
|
||||
Limitations).
|
||||
|
||||
**FrameLedger is beta software.** It certainly still has bugs. If something goes wrong, Help ▸ Report a bug… builds a
|
||||
report on your PC that you can look at before you decide to share it.
|
||||
|
||||
This guide is part of FrameLedger and describes the version it came with. It is also in the project's repository on
|
||||
GitHub, in the `guide` folder, and on the project's wiki, which shows the newest release.
|
||||
@@ -0,0 +1,43 @@
|
||||
# The terms, in plain words
|
||||
|
||||
This page sums up the documents FrameLedger shows you. **It is a summary, not the terms:** the documents themselves
|
||||
are the terms, and where this page and a document differ, the document is right. They are all under **Help ▸ About ▸
|
||||
Legal documents**.
|
||||
|
||||
## End User License Agreement — you accept it
|
||||
|
||||
- FrameLedger is **free software** under the GNU GPL v3 (below), and nothing in the agreement takes any of that away.
|
||||
- It records performance data **on your PC**.
|
||||
- It hooks a game **only if you switch that on for that game**, after a warning. If anti-cheat bans your account for
|
||||
it, **that risk is yours**, and the developer cannot undo a ban.
|
||||
- It is **beta** software, provided **without warranty**, and the developer is not liable for damage it causes — as
|
||||
far as the law allows. Rights the law gives you as a consumer, which no agreement can take away, stay yours.
|
||||
- Read it: [EULA](../legal/EULA.md).
|
||||
|
||||
## Disclaimer — you accept it
|
||||
|
||||
How FrameLedger measures, why that can be detected by anti-cheat, what its safety checks can and cannot catch, how
|
||||
accurate its measurements are, that your PC must meet each game's own requirements, and what *Run the agent as
|
||||
administrator* changes. Read it: [Disclaimer](../legal/DISCLAIMER.md).
|
||||
|
||||
## Privacy Policy — you accept it
|
||||
|
||||
Everything stays on your PC: no account, no telemetry, no analytics. The only network requests are the update check
|
||||
and the update download, to GitHub, and the check can be switched off. It lists what FrameLedger can observe, and says
|
||||
that sharing an export or a bug report is your decision. Read it: [Privacy Policy](../legal/PRIVACY_POLICY.md).
|
||||
|
||||
## GNU General Public License v3 — your licence, shown for information
|
||||
|
||||
It gives you the right to **use, study, share and change** FrameLedger. You do not have to accept it to use the
|
||||
program. If you **give copies to others** — changed or not — you must pass on the same freedoms and offer the source
|
||||
code. Read it: [GPL v3](../LICENSE).
|
||||
|
||||
## NOTICE — the copyright line and three extra terms
|
||||
|
||||
The copyright line, and three terms of the kinds the GPL's section 7 allows: keep the copyright line and the
|
||||
attribution; a changed version must say it is changed and must not be called just "FrameLedger"; and the terms give no
|
||||
rights to the FrameLedger name or logo. Read it: [NOTICE](../NOTICE).
|
||||
|
||||
## When the documents change
|
||||
|
||||
A new version of a document you accepted is shown to you again before FrameLedger continues.
|
||||
+25
-7
@@ -11,8 +11,8 @@
|
||||
that changes what FrameLedger.Overlay or the capture host does; date the change.
|
||||
HTML comments are not part of the block.
|
||||
-->
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-10-13.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.21`** (2026-10-13), an unsigned installer built from that tag with its
|
||||
> checksums published beside it. The source holds the desktop app
|
||||
> (library, store import, charts, settings) and the background Agent, which records a session when a
|
||||
> game in the library runs (unless you switched its recording off), injects only into games you enabled
|
||||
@@ -21,8 +21,9 @@
|
||||
>
|
||||
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
|
||||
> OpenGL titles FrameLedger injects into. Vulkan titles are measured only when FrameLedger itself
|
||||
> starts the game with its Vulkan layer enabled, which today only the Agent's command-line launch
|
||||
> does. A Vulkan title started any other way is not observed by the layer; FrameLedger injects its
|
||||
> starts the game with its Vulkan layer enabled, which the Play button set to *Start directly* (since
|
||||
> beta.21) and the Agent's command-line launch do. A Vulkan title started any other way is not
|
||||
> observed by the layer; FrameLedger injects its
|
||||
> Direct3D component into it instead, and what that records on a Vulkan title has not been
|
||||
> verified. Direct3D 9 and every 32-bit title are not measured.
|
||||
> - **Which upscaler is running:** measured from the API a Direct3D title calls — DLSS or NIS through
|
||||
@@ -63,12 +64,29 @@
|
||||
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
|
||||
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
|
||||
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
|
||||
> files state.
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
|
||||
> player library or its data file — without the release letter where only the library's number is readable),
|
||||
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
|
||||
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
|
||||
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
|
||||
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
|
||||
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
|
||||
> once a second from Windows' own counters, from outside the game, in every session: a game
|
||||
> FrameLedger injects into through the handle it already holds, any other by opening it briefly with
|
||||
> the least access Windows offers (and adding up every process running its executable). Shown with
|
||||
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
|
||||
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
|
||||
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
|
||||
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
|
||||
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
|
||||
> measured from frame times.
|
||||
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
|
||||
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
|
||||
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
|
||||
> differs from the next; for Direct3D titles, how many frames asked to wait for the display and how many allowed
|
||||
> tearing — what the game asked, not what the driver did; the graphics card's clock speeds, fan speed and memory
|
||||
> 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.
|
||||
> - **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
|
||||
|
||||
+31
-17
@@ -1,12 +1,6 @@
|
||||
# FrameLedger — Disclaimer
|
||||
|
||||
**Version:** 2.9 · **Effective:** {{RELEASE_DATE}}
|
||||
|
||||
> **How this document is kept true.** The statement of what FrameLedger measures (§4) is `legal/ACCURACY.md`,
|
||||
> embedded here and in `README.md` and bound to its source by `tools/accuracy-check.ps1`, which fails the build when a
|
||||
> copy differs. Earlier versions of this document carried a hand-maintained audit of how its own promises drifted from
|
||||
> the software — six re-counts between 2026-08-04 and 2026-09-15; that history is `docs/legal-drift-history.md`,
|
||||
> moved out of the text you accept on 2026-09-16 and kept in full.
|
||||
**Version:** 2.10 · **Effective:** {{RELEASE_DATE}}
|
||||
|
||||
## 0. This is pre-release (beta) software
|
||||
|
||||
@@ -42,7 +36,9 @@ Be precise about what that does and does not promise, because the shorter versio
|
||||
|
||||
Install it somewhere only you can write to, and verify the published SHA-256 checksums.
|
||||
|
||||
**What it observes:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation) and video-memory usage reported by the graphics runtime.
|
||||
**What it observes inside the game:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation).
|
||||
|
||||
**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 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 nothing else — holds for all of it.
|
||||
|
||||
@@ -69,8 +65,8 @@ FrameLedger is designed to reduce that risk substantially:
|
||||
the game exits.
|
||||
- FrameLedger contains **no evasion techniques of any kind** — it does not hide, rename, obfuscate, or disguise itself. It is intended to be plainly identifiable to any security software that looks.
|
||||
|
||||
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread** that sleeps for a second at a time and checks whether it has been told to stop. It reads only FrameLedger's own shared memory. It does not scan the game, enumerate what the system has loaded, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
|
||||
- FrameLedger injects into a game only after you enable that game individually. For every other game — and for any game where the safety checks refuse — it records the session's start, end and duration together with whatever hardware sensor readings your machine provides, and reports every other measurement as not available. **There is no measurement mode that works without injecting**; an earlier version of this document described one, and it was never built. FrameLedger never estimates a value it could not measure, and it always shows which of the two modes produced a session. Neither mode requires administrator rights.
|
||||
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread**. It wakes once a second, or when the game loads a library, and then: checks FrameLedger's own shared memory for a request to stop and for the heartbeat of the safety scan described above; asks Windows, by name, whether the graphics, upscaling and frame-generation libraries it knows about are loaded, and puts its interception into the ones that are (for ray tracing it creates one command list on the game's own Direct3D 12 device, to find the functions to intercept); writes its counters to FrameLedger's shared memory; and writes FrameLedger's own log file. It does not scan the game's memory, list the modules or processes on the system, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
|
||||
- FrameLedger injects into a game only after you enable that game individually. For every other game — and for any game where the safety checks refuse — it records the session's start, end and duration together with whatever hardware sensor readings your machine provides and the game's own memory use as Windows reports it (§1), and reports every other measurement as not available. **There is no measurement mode that works without injecting**; an earlier version of this document described one, and it was never built. FrameLedger never estimates a value it could not measure, and it always shows which of the two modes produced a session. Neither mode requires administrator rights.
|
||||
|
||||
**However, these protections cannot be complete:**
|
||||
|
||||
@@ -117,8 +113,8 @@ Software running inside another process can, in principle, destabilize it. Frame
|
||||
Frame timing is derived from high-resolution timestamps taken at the moment the game presents each frame; upscaling, frame-generation and ray-tracing state are read from the parameters the game passes to those APIs. This is substantially more accurate than inferring settings from files on disk, but **no measurement is guaranteed to be exact**:
|
||||
|
||||
<!-- accuracy-block:begin -->
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-09-28.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.10`** (2026-09-28), an unsigned installer built from that tag with its
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-10-13.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.21`** (2026-10-13), an unsigned installer built from that tag with its
|
||||
> checksums published beside it. The source holds the desktop app
|
||||
> (library, store import, charts, settings) and the background Agent, which records a session when a
|
||||
> game in the library runs (unless you switched its recording off), injects only into games you enabled
|
||||
@@ -127,8 +123,9 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
|
||||
>
|
||||
> - **Frame times and output resolution:** measured from the present call for Direct3D 11/12 and
|
||||
> OpenGL titles FrameLedger injects into. Vulkan titles are measured only when FrameLedger itself
|
||||
> starts the game with its Vulkan layer enabled, which today only the Agent's command-line launch
|
||||
> does. A Vulkan title started any other way is not observed by the layer; FrameLedger injects its
|
||||
> starts the game with its Vulkan layer enabled, which the Play button set to *Start directly* (since
|
||||
> beta.21) and the Agent's command-line launch do. A Vulkan title started any other way is not
|
||||
> observed by the layer; FrameLedger injects its
|
||||
> Direct3D component into it instead, and what that records on a Vulkan title has not been
|
||||
> verified. Direct3D 9 and every 32-bit title are not measured.
|
||||
> - **Which upscaler is running:** measured from the API a Direct3D title calls — DLSS or NIS through
|
||||
@@ -169,12 +166,29 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
|
||||
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
|
||||
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
|
||||
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
|
||||
> files state.
|
||||
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
|
||||
> player library or its data file — without the release letter where only the library's number is readable),
|
||||
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
|
||||
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
|
||||
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
|
||||
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
|
||||
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
|
||||
> once a second from Windows' own counters, from outside the game, in every session: a game
|
||||
> FrameLedger injects into through the handle it already holds, any other by opening it briefly with
|
||||
> the least access Windows offers (and adding up every process running its executable). Shown with
|
||||
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
|
||||
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
|
||||
> and charted. **Not measured at all:** each game's own video-memory use and budget, which frame
|
||||
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
|
||||
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
|
||||
> measured from frame times.
|
||||
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
|
||||
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
|
||||
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
|
||||
> differs from the next; for Direct3D titles, how many frames asked to wait for the display and how many allowed
|
||||
> tearing — what the game asked, not what the driver did; the graphics card's clock speeds, fan speed and memory
|
||||
> 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.
|
||||
> - **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
|
||||
|
||||
+9
-5
@@ -1,6 +1,6 @@
|
||||
# FrameLedger — End User License Agreement (EULA)
|
||||
|
||||
**Version:** 1.4 · **Effective:** {{RELEASE_DATE}}
|
||||
**Version:** 1.5 · **Effective:** {{RELEASE_DATE}}
|
||||
|
||||
This End User License Agreement ("Agreement") applies to **FrameLedger** ("the Software"), developed and published by **poli0981** ("the Developer"), contactable at <contact@poli0981.dev> — see <https://poli0981.dev/> for other contact channels.
|
||||
|
||||
@@ -10,7 +10,7 @@ The Software is free and open-source software licensed to you under the **GNU Ge
|
||||
|
||||
## 2. What the Software does
|
||||
|
||||
The Software records game performance data, hardware telemetry (temperatures, load, memory usage), and game metadata, and stores this data **locally on your device**. Details are described in the Privacy Policy and Disclaimer accompanying the Software.
|
||||
The Software records game performance data, hardware telemetry (temperatures, load, memory usage), each game's own memory use as Windows reports it, and game metadata, and stores this data **locally on your device**. Details are described in the Privacy Policy and Disclaimer accompanying the Software.
|
||||
|
||||
## 2A. Code injection — your responsibility
|
||||
|
||||
@@ -28,7 +28,7 @@ By enabling this feature for a game, you confirm that:
|
||||
|
||||
(e) the Developer has no ability to reverse a ban, recover lost progress, or intervene with any game publisher on your behalf, and accepts no liability for such outcomes.
|
||||
|
||||
The Software records without injecting unless you enable injection for a specific game. In that mode it records only the session's duration and whatever hardware sensor data is available, indicates that mode on the session, and reports unavailable measurements as such rather than estimating them. Neither mode requires the Software's agent to run with administrator rights.
|
||||
The Software records without injecting unless you enable injection for a specific game. In that mode it records only the session's duration, whatever hardware sensor data is available, and the game's own memory use as Windows reports it — read from outside the game, never from the game's memory — indicates that mode on the session, and reports unavailable measurements as such rather than estimating them. Neither mode requires the Software's agent to run with administrator rights.
|
||||
|
||||
## 2B. Pre-release software, and your PC
|
||||
|
||||
@@ -43,11 +43,11 @@ unstable, overheating, overclocked or faulty hardware, are your responsibility a
|
||||
|
||||
## 3. Acceptance
|
||||
|
||||
By clicking "Accept" in the first-run dialog or by using the Software, you confirm that you have read this Agreement, the Disclaimer, and the Privacy Policy.
|
||||
By clicking "Accept" in the first-run dialog or by using the Software, you confirm that you have read this Agreement, the Disclaimer, and the Privacy Policy. The GPL-3.0 is shown in the same dialog for your information: it is your licence to the Software, and you need not accept it to run the Software (GPL-3.0 §9).
|
||||
|
||||
## 4. Third-party components
|
||||
|
||||
The Software includes and interoperates with third-party components listed in `legal/THIRD_PARTY_NOTICES.md`, each under its own license. The optional **PawnIO** kernel driver is a separate third-party product installed by you at your discretion and governed by its own license and terms.
|
||||
The Software includes and interoperates with third-party components listed in `legal/THIRD_PARTY_NOTICES.md` — in an installed copy, `licenses\THIRD_PARTY_NOTICES.md` beside the Software, and Help ▸ About — each under its own license. The optional **PawnIO** kernel driver is a separate third-party product installed by you at your discretion and governed by its own license and terms.
|
||||
|
||||
## 5. No warranty
|
||||
|
||||
@@ -69,6 +69,10 @@ The Software can check for updates via GitHub. Installing updates is always your
|
||||
|
||||
Your rights under the GPL-3.0 continue as described in that license. You may stop using the Software at any time by uninstalling it; local data removal options are offered during uninstall.
|
||||
|
||||
## 10. Your rights as a consumer, and the rest of this Agreement
|
||||
|
||||
Nothing in this Agreement limits any right you have under consumer protection law that cannot be limited or waived by agreement; where such a law applies, the warranty and liability terms above apply only as far as that law allows. If a court finds any provision of this Agreement unenforceable, that provision is enforced to the extent permitted, and the rest of the Agreement remains in effect.
|
||||
|
||||
---
|
||||
|
||||
Contact: <contact@poli0981.dev> · Developer: <https://poli0981.dev/> · Project: <https://github.com/poli0981/frameledger>
|
||||
+9
-11
@@ -1,6 +1,6 @@
|
||||
# FrameLedger — Privacy Policy
|
||||
|
||||
**Version:** 2.5 · **Effective:** {{RELEASE_DATE}}
|
||||
**Version:** 2.10 · **Effective:** {{RELEASE_DATE}}
|
||||
|
||||
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
|
||||
|
||||
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
|
||||
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, memory usage), 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.
|
||||
- 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.
|
||||
- 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.
|
||||
@@ -27,26 +27,24 @@ FrameLedger makes **no network connections except the following two**, both from
|
||||
|
||||
There is no other request. In particular, the anti-cheat safety list and the detection rules ship **with the build** and are installed locally on first run; the software fetches no rules from anywhere, and it looks nothing up on any store. When a rules feed exists it will be a new version of this document, which the app shows you again before continuing (§6).
|
||||
|
||||
> **History.** Versions 2.0 and 2.1 of this document listed three further rows — a weekly safety-list update, a weekly detection-rules update, and an opt-in Steam store lookup — describing requests the software did not make; from 2026-08-04 they carried an audit note saying so. Version 2.2 (2026-09-16) removes them. A privacy policy that lists a transmission which never happens is as wrong as one that omits a transmission which does.
|
||||
|
||||
GitHub's own privacy practices apply to requests it receives: <https://docs.github.com/privacy>.
|
||||
|
||||
Pressing Play hands the game to its store's app on your PC, which may connect to its store as it does whenever you start a game from it; FrameLedger itself connects to nothing.
|
||||
|
||||
## 3. Bug reports — always manual
|
||||
|
||||
The "Report a bug" feature builds a zip file **on your device**, shows you exactly which files it contains, and lets you inspect them. Nothing is transmitted by the app; **you** decide whether to attach the file to a GitHub issue in your browser. Logs are redacted (user directory paths removed) before bundling. Optional items (crash dumps, last-session metadata) are included only when you tick their checkboxes.
|
||||
|
||||
## 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. 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; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); video-memory usage reported by the graphics runtime; loaded module names of a game being captured (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 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), and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; 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 how busy the processor is and how much memory is in use, from Windows' own counters.
|
||||
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; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); 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 (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 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) — 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 — 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; 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; how busy the processor is and how much memory is in use, from Windows' own counters; the crash reports Windows keeps in its Application log about a tracked game's executable while it ran (to tell a crash from an ordinary exit — the reports are read, never sent anywhere); and the names of the programs a tracked game starts, so that a game's own crash reporter is recognised.
|
||||
|
||||
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.
|
||||
|
||||
> **History.** Version 2.3 (2026-09-23) adds the per-entry recording switch. Before it, every program in your library was recorded whenever it ran, which recorded a utility that starts with Windows at every boot.
|
||||
>
|
||||
> Version 2.4 (2026-09-25, 0.1.0-beta.8) names what the software reads to check every game in your library for anti-cheat — until then it checked only a game you asked to hook — and to name the versions of its files, and the NVIDIA driver's settings for your games. The files of a library game's folder were already read to detect its engine and features; this version is the first to say so.
|
||||
>
|
||||
> 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.
|
||||
|
||||
All of this stays on your device. None of it is transmitted anywhere.
|
||||
|
||||
## 5. Children
|
||||
|
||||
@@ -29,7 +29,6 @@ FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the th
|
||||
| Component | Use | License | Notes |
|
||||
|---|---|---|---|
|
||||
| **MinHook** | Inline function hooking in `FrameLedger.Overlay` | BSD-2-Clause | Vendored and built from source, pinned by commit. Copyright notice must ship in `legal/licenses/` |
|
||||
*(The **Intel PresentMon** row was removed on 2026-08-27. It is not bundled, not fetched, not redistributed and no longer used at all — §S31 retired it as a measurement oracle and the owner then dropped it outright — so a notice for it would be over-disclosure, which this document treats as a defect in the same way an omission is. `tools/license-check.ps1`'s matching claim was removed in the same commit, because a bidirectional check whose subject no longer exists cannot go green honestly: it would be asserting agreement about nothing.)*
|
||||
| Vulkan headers / loader interfaces | `FrameLedger.VkLayer` implicit layer | Apache-2.0 | Khronos headers; layer implemented against the documented loader–layer interface |
|
||||
| LibreHardwareMonitorLib | GPU sensors (all vendors) + CPU/motherboard sensors (optional, elevated) | MPL-2.0 | See §GPU telemetry below. Consumed unmodified |
|
||||
| WPF UI (`Wpf.Ui`, lepoco) | Fluent UI theme/controls/navigation | MIT | © lepo.co, Leszek Pomianowski and contributors. License copy must ship with the app (MIT requirement) — `legal/licenses/nuget/WPF-UI.txt`, the package's own LICENSE.md |
|
||||
@@ -43,6 +42,7 @@ FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the th
|
||||
| CsWin32 (build-time) | Win32 interop source generator | MIT | Build-time only |
|
||||
| NVIDIA NVAPI SDK | NVIDIA GPU telemetry + Reflex latency | MIT | **Vendored 2026-08-05** — nine headers + `amd64/nvapi64.lib`, at `src/native/third_party/nvapi/`. See §GPU telemetry below |
|
||||
| H.NotifyIcon.Wpf | Tray icon | MIT | |
|
||||
| Markdig | Markdown rendering in the App (since beta.12): the Legal Gate, Help, About, the update notes | BSD-2-Clause | © Alexandre Mutel. The package ships no licence file; its text is the project's own `license.txt` at the packaged commit, a reviewed override (`tools/license-overrides/Markdig.txt`) → `legal/licenses/nuget/Markdig.txt`. Consumed unmodified; HTML in a document is shown as text, never interpreted, and no image is fetched |
|
||||
| **Transitive, under LibreHardwareMonitorLib** — BlackSharp.Core, DiskInfoToolkit, RAMSPDToolkit-NDD | Hardware access helpers LHM 0.9.6 depends on | MPL-2.0 | Not named by this table until 2026-09-15. **Exhibit B clear:** authenticated code search of each upstream repository (Blacktempel/BlackSharp, /DiskInfoToolkit, /RAMSPDToolkit) finds the sentence once, in `LICENSE` — the template — and no source file carries an MPL notice at all, so the repository licence governs and §3.3 Secondary Licenses applies. Default branch as searched; the nuspecs pin commits `c70b735c`, `25319eae`, `3b47b960`. Source Code Form links are in each package's text |
|
||||
| **Transitive, under LibreHardwareMonitorLib** — HidSharp; Mono.Posix.NETStandard; System.IO.Ports, System.Management, System.CodeDom, System.IO.FileSystem.AccessControl | USB HID, POSIX helpers, serial ports, WMI | Apache-2.0 (HidSharp's LICENSE.txt); MIT (Mono's LICENSE, reviewed override); MIT (Microsoft) | Mono.Posix.NETStandard declares only a URL; its text is the Mono LICENSE file that URL resolves to, fetched 2026-09-15 and committed as `tools/license-overrides/Mono.Posix.NETStandard.txt` |
|
||||
| **Transitive, under ScottPlot.WPF** — SkiaSharp, HarfBuzzSharp and their Win32 native assets; OpenTK 4.x; OpenTK.GLWpfControl; OpenTK.redist.glfw | 2-D rendering, text shaping, OpenGL host | MIT; GLFW is zlib (its COPYING.md) | The native Skia and HarfBuzz builds carry their own third-party notices, shipped once each in `legal/licenses/nuget/notices-*.txt`. OpenTK.GLWpfControl declares only a URL (reviewed override, like Mono.Posix) |
|
||||
@@ -50,6 +50,8 @@ FrameLedger is licensed under **GPL-3.0-only**. It includes or depends on the th
|
||||
| Roslynator, Meziantou.Analyzer, VS Threading Analyzers (build-time) | Static analysis | Apache-2.0 / MIT | Build-time only |
|
||||
| **Test-time only, never shipped** — xUnit.net v3 4.x (`xunit.v3.mtp-off`, `xunit.runner.visualstudio`), Microsoft.NET.Test.Sdk, coverlet.collector, FluentAssertions 7.x, NSubstitute; Catch2 (native) | Unit and integration tests, coverage | Apache-2.0 (xUnit.net, <https://github.com/xunit/xunit>; FluentAssertions **7.x only**) · MIT (Test.Sdk, coverlet) · BSD-3-Clause (NSubstitute) · BSL-1.0 (Catch2) | Not named by this table until 2026-09-21. None of them is in a published package: `12_BUILD` publishes App and Agent only, `tools/package-closure-check.ps1` keeps the test projects out of that closure, and `legal/licenses/nuget/` therefore lists none of them. xUnit.net moved 3.2.2 → 4.0.1 on 2026-09-21, same licence. **FluentAssertions is pinned to `[7.2.2]` on purpose**: 8.x is Xceed's Community Licence, not an OSI licence (`Directory.Packages.props`, `20_OPEN_QUESTIONS` §G). Catch2's text is `legal/licenses/catch2-BSL-1.0.txt` |
|
||||
|
||||
*(The **Intel PresentMon** row was removed on 2026-08-27. It is not bundled, not fetched, not redistributed and no longer used at all — §S31 retired it as a measurement oracle and the owner then dropped it outright — so a notice for it would be over-disclosure, which this document treats as a defect in the same way an omission is. `tools/license-check.ps1`'s matching claim was removed in the same commit, because a bidirectional check whose subject no longer exists cannot go green honestly: it would be asserting agreement about nothing.)* *(Moved out of the table on 2026-10-03: a line without cells inside a table ended it for Markdig, so the App drew the whole table as text; GitHub draws it either way.)*
|
||||
|
||||
## GPU telemetry — what is bundled and what is not
|
||||
|
||||
Telemetry is layered so no proprietary vendor licence is ever required (`docs/18_GPU_VENDOR_APIS.md`).
|
||||
@@ -99,7 +101,7 @@ All product names, logos, and brands are property of their respective owners and
|
||||
## Attribution requirements checklist (release gate)
|
||||
|
||||
- [x] `legal/licenses/` contains full texts: MIT (per-project copies, **including `nvapi-MIT.txt`**), BSD-2-Clause (MinHook), MPL-2.0, Apache-2.0 — **2026-09-15 (P4 PR-6):** the vendored natives' copies as before, plus one generated text per shipped NuGet package in `legal/licenses/nuget/` (77), gated by `license-check` §3; the .NET runtime's licence and notices are added to the package by `release.yml`. The copies ship: the App's publish carries `legal/licenses/` as `licenses/`
|
||||
- [ ] About → Third-party tab lists this table with versions filled from `Directory.Packages.props` — **not built as of 2026-09-16 and not a gate for the first pre-release**: the texts ship as files (`licenses/` beside the App, `licenses/nuget/INDEX.md` lists every package with its version), and Help ▸ Documentation opens this file; the tab is an open UI item
|
||||
- [x] About → Third-party tab lists this table with versions ~~filled from `Directory.Packages.props`~~ — **built beta.12 (2026-10-03)**: Help ▸ About ▸ *Third-party licences* renders this file and `licenses/nuget/INDEX.md` — every shipped package with its version and licence, generated from what the build restores rather than from `Directory.Packages.props` — with a button that opens the published `licenses\` folder. ~~not built as of 2026-09-16 and not a gate for the first pre-release: the texts ship as files (`licenses/` beside the App, `licenses/nuget/INDEX.md` lists every package with its version), and Help ▸ Documentation opens this file; the tab is an open UI item~~
|
||||
- ~~PresentMon license + copyright shipped beside the bundled binary~~ — **removed 2026-08-27 with the dependency.** Nothing Intel-authored is distributed by this project
|
||||
- [x] MPL-2.0 source-availability note points to upstream LibreHardwareMonitor repository — every MPL-2.0 package text in `legal/licenses/nuget/` names its Source Code Form (MPL-2.0 §3.2), LHM's `https://github.com/LibreHardwareMonitor/LibreHardwareMonitor` included (2026-09-15)
|
||||
- [x] LHM checked for MPL-2.0 Exhibit B on any depended-upon file — clear as of 0.9.6 / commit `3d331e33`, 2026-08-02
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# Names and trademarks
|
||||
|
||||
FrameLedger measures games on hardware, drivers and platforms made by other companies, so its software and its
|
||||
documents name their products constantly. This page says how those names are used, and how the name *FrameLedger*
|
||||
itself may be used. It is information for readers of the repository and of the documentation; it is not one of the
|
||||
documents the app asks you to accept.
|
||||
|
||||
## Other companies' names
|
||||
|
||||
Microsoft, Windows, DirectX, Direct3D and DXGI are trademarks of 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
|
||||
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.
|
||||
|
||||
They are used **only to say what FrameLedger works with or measures** — for example, which upscaler a game used, or
|
||||
which anti-cheat product made FrameLedger refuse to load into a game. Such a mention is a statement of fact about
|
||||
compatibility or detection; it is not a claim about the quality of anyone's product.
|
||||
|
||||
**FrameLedger is an independent project.** It is not affiliated with, endorsed by or sponsored by any of these
|
||||
companies, by any game's developer or publisher, or by any anti-cheat vendor, and none of them supports it.
|
||||
|
||||
- The anti-cheat products named in `rules/detection-rules.json` are listed so that FrameLedger can **refuse** to load
|
||||
into a game protected by them; the list says nothing else about them.
|
||||
- The games named in `docs/LIST_GAME_TESTED.md` are games the developer ran FrameLedger with, on one machine; the list is
|
||||
not a benchmark claim and not a recommendation.
|
||||
|
||||
## The name FrameLedger
|
||||
|
||||
*FrameLedger* is the name of this project. The licence (`LICENSE`, `NOTICE`) gives you broad rights in the software
|
||||
but, by its additional term (e), **no rights in the name**, the project's logo or its icon, beyond describing truthfully
|
||||
where a work comes from:
|
||||
|
||||
- **fine:** "based on FrameLedger", "a fork of FrameLedger", "compatible with FrameLedger's export format", a link to
|
||||
the project, an article or video about FrameLedger;
|
||||
- **not fine:** naming a modified version "FrameLedger", using the icon or name for a build the project did not make,
|
||||
or suggesting the developer made or endorses something they did not (NOTICE (c)).
|
||||
|
||||
`FORKING.md` says what a fork that ships builds should rename.
|
||||
|
||||
## Questions
|
||||
|
||||
If you represent one of the companies above and believe a mention here is wrong, or you want to ask about using the
|
||||
FrameLedger name, write to contact@poli0981.dev.
|
||||
@@ -18,6 +18,7 @@ from the runtime packs the publish used.
|
||||
| HarfBuzzSharp.NativeAssets.Win32 | 8.3.1.1 | MIT | App | [HarfBuzzSharp.NativeAssets.Win32.txt](HarfBuzzSharp.NativeAssets.Win32.txt) |
|
||||
| HidSharp | 2.6.4 | the file LICENSE.txt in the package | Agent, App | [HidSharp.txt](HidSharp.txt) |
|
||||
| LibreHardwareMonitorLib | 0.9.6 | MPL-2.0 | Agent, App | [LibreHardwareMonitorLib.txt](LibreHardwareMonitorLib.txt) |
|
||||
| Markdig | 1.4.0 | BSD-2-Clause | App | [Markdig.txt](Markdig.txt) |
|
||||
| Microsoft.Data.Sqlite.Core | 10.0.12 | MIT | Agent, App | [Microsoft.Data.Sqlite.Core.txt](Microsoft.Data.Sqlite.Core.txt) |
|
||||
| Microsoft.Extensions.Configuration | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.txt](Microsoft.Extensions.Configuration.txt) |
|
||||
| Microsoft.Extensions.Configuration.Abstractions | 10.0.12 | MIT | Agent, App | [Microsoft.Extensions.Configuration.Abstractions.txt](Microsoft.Extensions.Configuration.Abstractions.txt) |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
Markdig 1.4.0
|
||||
|
||||
Licence declared: BSD-2-Clause
|
||||
Text below: tools/license-overrides/Markdig.txt, a reviewed copy of the project's own licence file; the package ships none
|
||||
Copyright: Alexandre Mutel
|
||||
Authors: Alexandre Mutel
|
||||
Project: https://xoofx.github.io/markdig
|
||||
Ships in: App
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
Reviewed override for Markdig 1.4.0 (tools/license-gather.ps1).
|
||||
|
||||
The package declares <license type="expression">BSD-2-Clause</license> and ships no licence file. The text
|
||||
below is the project's own license.txt at the commit the package names (<repository commit=
|
||||
"56e9c238584a44a169f174c881855c049768634c">), fetched on 2026-10-03 from
|
||||
https://raw.githubusercontent.com/xoofx/markdig/56e9c238584a44a169f174c881855c049768634c/license.txt,
|
||||
verbatim. The package's <copyright> field is "Alexandre Mutel"; the file names the same holder.
|
||||
|
||||
Used by the App since beta.12 to render the documents it shows (the Legal Gate, Help, About, the user guide);
|
||||
consumed unmodified.
|
||||
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
Copyright (c) 2016-2026, Alexandre Mutel
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification
|
||||
, are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice, this
|
||||
list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
+28
-19
@@ -1,13 +1,14 @@
|
||||
{
|
||||
"$comment": [
|
||||
"Rules are DATA, not code (docs/05_DETECTION.md). This file ships with the",
|
||||
"app and is updatable from the repository independently of releases.",
|
||||
"app. It is NOT fetched: there is no rules feed (docs/20_OPEN_QUESTIONS.md",
|
||||
"§S20 feed half), so a change here reaches users with a release, seeded by",
|
||||
"the Agent from the copy beside it. (This comment said otherwise until",
|
||||
"2026-10-04.)",
|
||||
"",
|
||||
"The `anticheat` block is what feeds the hard gate in",
|
||||
"docs/19_SAFETY_AND_ANTICHEAT.md. Updates to it are treated as security",
|
||||
"updates: applied on the next check regardless of the user's auto-update",
|
||||
"preference for other rules. Removing an entry is a safety change and needs",
|
||||
"the same review as a security fix (docs/13_CI_CD.md §rules-publish).",
|
||||
"docs/19_SAFETY_AND_ANTICHEAT.md. Removing an entry is a safety change and",
|
||||
"needs the same review as a security fix (docs/13_CI_CD.md §rules-publish).",
|
||||
"",
|
||||
"Shape is fixed by rules/detection-rules.schema.json (JSON Schema 2020-12),",
|
||||
"which closes docs/20_OPEN_QUESTIONS.md §S5. Constraints a schema cannot",
|
||||
@@ -15,10 +16,11 @@
|
||||
"compilability, case-insensitive duplicate values — stay imperative in",
|
||||
"tools/rules-validate.ps1.",
|
||||
"",
|
||||
"STILL INCOMPLETE AS DATA: docs/19_SAFETY §Blocklist seed names one family",
|
||||
"with no representation here at all — Valve VAC (needs blockedStoreIds",
|
||||
"entries). Activision Ricochet was the other until 2026-09-25, when its",
|
||||
"driver and services arrived from Activision's own support pages.",
|
||||
"Every family docs/19_SAFETY §Blocklist seed names is represented since",
|
||||
"2026-09-25: Valve VAC through blockedStoreIds and blockedExecutables (VAC",
|
||||
"runs inside Steam, so no file of the game's own names it), and Activision",
|
||||
"Ricochet through its driver and services from Activision's own support",
|
||||
"pages.",
|
||||
"",
|
||||
"PRE-INJECTION CHECK 3 MATCHED NOTHING until 2026-09-25, because",
|
||||
"`blockedExecutables` and `blockedStoreIds` were both empty. The owner seeded",
|
||||
@@ -40,7 +42,7 @@
|
||||
"level, which made it a check that could not fire."
|
||||
],
|
||||
"schemaVersion": 2,
|
||||
"rulesVersion": "2026.10.1",
|
||||
"rulesVersion": "2026.10.4",
|
||||
|
||||
"engines": [
|
||||
{
|
||||
@@ -50,7 +52,7 @@
|
||||
{ "type": "sibling_glob", "value": "UnityPlayer.dll" },
|
||||
{ "type": "dir_exists", "value": "${ExeName}_Data" }
|
||||
] },
|
||||
"version": { "type": "pe_file_version", "from": "UnityPlayer.dll" }
|
||||
"version": { "type": "unity_build" }
|
||||
},
|
||||
{
|
||||
"id": "unreal",
|
||||
@@ -68,7 +70,7 @@
|
||||
{ "type": "sibling_glob", "value": "nw.dll" },
|
||||
{ "type": "sibling_glob", "value": "package.json" }
|
||||
] },
|
||||
"version": null
|
||||
"version": { "type": "rpgmaker_build" }
|
||||
},
|
||||
{
|
||||
"id": "rpgmaker_rgss",
|
||||
@@ -81,7 +83,7 @@
|
||||
{ "type": "sibling_glob", "value": "*.rgss2a" },
|
||||
{ "type": "sibling_glob", "value": "*.rgss3a" }
|
||||
] },
|
||||
"version": null
|
||||
"version": { "type": "rpgmaker_build" }
|
||||
},
|
||||
{
|
||||
"id": "re_engine",
|
||||
@@ -107,7 +109,7 @@
|
||||
{ "type": "sibling_glob", "value": "*.pck" },
|
||||
{ "type": "strings_contains", "value": "Godot Engine v" }
|
||||
] },
|
||||
"version": { "type": "strings_regex", "value": "Godot Engine v(\\d+\\.\\d+[\\.\\d]*)" }
|
||||
"version": { "type": "godot_build" }
|
||||
},
|
||||
{
|
||||
"id": "gamemaker",
|
||||
@@ -122,7 +124,7 @@
|
||||
{ "type": "dir_exists", "value": "renpy" },
|
||||
{ "type": "sibling_glob", "value": "*.rpa" }
|
||||
] },
|
||||
"version": null
|
||||
"version": { "type": "renpy_build" }
|
||||
},
|
||||
{
|
||||
"id": "cryengine",
|
||||
@@ -221,7 +223,9 @@
|
||||
{ "family": "EQU8", "match": "prefix", "values": [ "equ8" ],
|
||||
"note": "Splitgate. Documented (SteamDB EQU8); module names unmeasured." },
|
||||
{ "family": "Xigncode3", "match": "exact", "values": [ "x3.xem" ],
|
||||
"note": "x3.xem is XIGNCODE3's loader, LoadLibrary'd as an ordinary module (documented). The files row names the same token in the install tree." }
|
||||
"note": "x3.xem is XIGNCODE3's loader, LoadLibrary'd as an ordinary module (documented). The files row names the same token in the install tree." },
|
||||
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "ACE-Base64.dll" ],
|
||||
"note": "ACE's user-mode module, MEASURED on disk 2026-10-13 in Wuthering Waves' AntiCheatExpert/ folder; that the game loads it is unmeasured. Exact, not prefix: 'ACE-' is four characters over a namespace we do not own. Appended, as every row since 2026-09-25." }
|
||||
],
|
||||
"drivers": [
|
||||
{ "family": "Riot Vanguard", "match": "exact", "values": [ "vgk.sys" ], "scope": "machine" },
|
||||
@@ -231,6 +235,8 @@
|
||||
"note": "MEASURED 2026-08-04: EasyAntiCheat_EOSSys was Running as a kernel driver while a real EAC title played, and matched NOTHING in this group — the refusal came from the service check instead. A family caught through only one of five groups is one rename away from being missed." },
|
||||
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "ACE-BASE.sys", "ACE-ADVT.sys", "ACE-GAME.sys" ], "scope": "machine",
|
||||
"note": "ACE-BASE.sys and ACE-ADVT.sys MEASURED under System32\\drivers on the dev machine 2026-08-04. ACE-GAME.sys is a documented sibling and is UNMEASURED: a blocklist may over-cover, never under-cover. Exact not prefix — 'ACE-' is four characters over a namespace we do not own." },
|
||||
{ "family": "Anti-Cheat Expert", "match": "exact", "values": [ "ACE-CORE.sys" ], "scope": "machine",
|
||||
"note": "On disk beside ACE-BASE.sys in Wuthering Waves' AntiCheatExpert/ folder (MEASURED 2026-10-13); that it loads is unmeasured. Exact, as the row above." },
|
||||
{ "family": "BattlEye", "match": "exact", "values": [ "BEDaisy.sys" ], "scope": "machine",
|
||||
"note": "BattlEye's kernel driver, loaded by BEService while a protected game runs and unloaded after (documented, BattlEye FAQ). Unmeasured." },
|
||||
{ "family": "FACEIT", "match": "exact", "values": [ "FACEIT.sys" ], "scope": "machine",
|
||||
@@ -260,7 +266,7 @@
|
||||
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS" ] },
|
||||
{ "family": "BattlEye", "values": [ "BattlEye" ] },
|
||||
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert", "AceAntibotClient" ],
|
||||
"note": "Documented (SteamDB FileDetectionRuleSets, AntiCheatExpert). Unmeasured." },
|
||||
"note": "Documented (SteamDB FileDetectionRuleSets). AntiCheatExpert MEASURED 2026-10-13 beside the executables of Wuthering Waves and Neverness To Everness, reached from the executable's own folder and never from the root. AceAntibotClient is unmeasured." },
|
||||
{ "family": "nProtect GameGuard", "values": [ "GameGuard" ] },
|
||||
{ "family": "Xigncode3", "values": [ "XIGNCODE", "XIGNCODE3" ] },
|
||||
{ "family": "AhnLab HackShield", "values": [ "HShield" ],
|
||||
@@ -276,8 +282,8 @@
|
||||
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat", "EasyAntiCheat_EOS", "EasyAntiCheat_EOSSys" ] },
|
||||
{ "family": "Riot Vanguard", "values": [ "vgc", "vgk" ],
|
||||
"note": "vgk is the kernel driver's service, started at boot like vgk.sys itself." },
|
||||
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert Protection", "AntiCheatExpert Service" ],
|
||||
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness. The sibling name is unmeasured." },
|
||||
{ "family": "Anti-Cheat Expert", "values": [ "AntiCheatExpert Protection", "AntiCheatExpert Service", "ACE-BASE" ],
|
||||
"note": "'AntiCheatExpert Protection' MEASURED registered on the dev machine 2026-08-04 by Neverness To Everness; 'ACE-BASE', the kernel service of ACE-BASE.sys, MEASURED registered there 2026-10-13. 'AntiCheatExpert Service' is unmeasured." },
|
||||
{ "family": "BattlEye", "values": [ "BEService", "BEDaisy" ],
|
||||
"note": "BEService is started by a protected game and stops after it; BEDaisy is the driver's service. A stopped service is absent (19_SAFETY). Unmeasured." },
|
||||
{ "family": "FACEIT", "values": [ "FACEIT", "FACEITService" ],
|
||||
@@ -296,6 +302,8 @@
|
||||
"note": "Shipped beside the game. This note said 'not a loadable module' until 2026-09-25: XIGNCODE3 LoadLibrary's x3.xem as its loader (documented), which is why the modules group names it too." },
|
||||
{ "family": "Anti-Cheat Expert", "values": [ "PGameProtectDriver_X64.sys", "SGuard64.exe", "SGuardSvc64.exe" ],
|
||||
"note": "A KERNEL DRIVER shipped inside the game install. MEASURED at 'Neverness To Everness/NTEGlobal/driver/' 2026-08-04, where check 4 returned Allow: no group named it, and the fuzzy tier is modules-only — so a name containing 'protect' sat in the game's tree and the static scan walked past." },
|
||||
{ "family": "Anti-Cheat Expert", "values": [ "ACE-BASE.sys", "ACE-CORE.sys", "ACE-Base64.dll", "ACE-Service64.exe", "ACE-Setup64.exe" ],
|
||||
"note": "MEASURED 2026-10-13 in Wuthering Waves' Client/Binaries/Win64/AntiCheatExpert/, beside its executable and four levels under its install root, which the walk from the root never opened: check 4 also walks the executable's own folder since then." },
|
||||
{ "family": "Easy Anti-Cheat", "values": [ "EasyAntiCheat_EOS_Setup.exe", "EasyAntiCheat_Setup.exe", "EasyAntiCheat_x64.dll", "EasyAntiCheat_x86.dll", "EasyAntiCheat_EOS.sys", "start_protected_game.exe", "eac_server64.dll" ],
|
||||
"note": "For a layout where the EasyAntiCheat folder sits deeper than the scan reaches. start_protected_game.exe is the EAC launcher FromSoftware titles ship (ELDEN RING's appeared in the owner's Windows Application log on 2026-09-21)." },
|
||||
{ "family": "BattlEye", "values": [ "BEService.exe", "BEService_x64.exe", "BEClient.dll", "BEClient_x64.dll", "BEDaisy.sys" ],
|
||||
@@ -416,6 +424,7 @@
|
||||
{ "store": "steam", "id": "2139460", "family": "NetEase Anti-Cheat", "reason": "Protected by NetEase's kernel anti-cheat (NEAC)." },
|
||||
{ "store": "steam", "id": "2507950", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
|
||||
{ "store": "steam", "id": "2073620", "family": "Anti-Cheat Expert", "reason": "Protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
|
||||
{ "store": "steam", "id": "3513350", "family": "Anti-Cheat Expert", "reason": "Wuthering Waves, protected by Tencent Anti-Cheat Expert (ACE), a kernel anti-cheat." },
|
||||
{ "store": "steam", "id": "1517290", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
|
||||
{ "store": "steam", "id": "2807960", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
|
||||
{ "store": "steam", "id": "2669320", "family": "EA AntiCheat", "reason": "Protected by EA AntiCheat (Javelin), a kernel anti-cheat." },
|
||||
|
||||
@@ -198,12 +198,12 @@
|
||||
}
|
||||
},
|
||||
{
|
||||
"$comment": "beta.10: Unreal Engine's build facts (the shipping executable's numeric file version and the engine's branch name inside it), decided in code (Domain.Detection.UnrealVersion) rather than by a pattern - which is why it takes no parameter.",
|
||||
"$comment": "beta.10: Unreal Engine's build facts (the shipping executable's numeric file version and the engine's branch name inside it), decided in code (Domain.Detection.UnrealVersion) rather than by a pattern - which is why it takes no parameter. beta.19 adds Unity's (the player library's version resource, the data file's header), Godot's (a data pack's header, the executable's version resource) and RPG Maker's (MV/MZ's core-script header, the RGSS library Game.ini names), decided by UnityVersion, GodotVersion and RpgMakerVersion. beta.20 adds Ren'Py's (the version line of the engine's renpy/vc_version.py), decided by RenPyVersion.",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["type"],
|
||||
"properties": {
|
||||
"type": { "const": "unreal_build" }
|
||||
"type": { "enum": ["unreal_build", "unity_build", "godot_build", "rpgmaker_build", "renpy_build"] }
|
||||
}
|
||||
}
|
||||
]
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.Agent;
|
||||
|
||||
/// <summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Infrastructure.Persistence;
|
||||
|
||||
namespace FrameLedger.Agent;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Globalization;
|
||||
using System.Security.Principal;
|
||||
using FrameLedger.Infrastructure.Startup;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.Agent.Cli;
|
||||
|
||||
/// <summary>What the Agent can be asked to do (P2 PR-F). The surface is pinned by <c>AgentCommandLineSurfaceTests</c>.</summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Agent.Composition;
|
||||
using FrameLedger.Application.Capture;
|
||||
using FrameLedger.Application.Consent;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.Vulkan;
|
||||
using FrameLedger.Infrastructure.Persistence;
|
||||
using FrameLedger.Infrastructure.Startup;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.Agent.Composition;
|
||||
|
||||
/// <summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Reflection;
|
||||
using FrameLedger.Application.Ipc;
|
||||
using FrameLedger.Infrastructure.AntiCheat;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.Capture;
|
||||
using FrameLedger.Application.Recording;
|
||||
using FrameLedger.Application.Watch;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.AntiCheat;
|
||||
using FrameLedger.Application.Capture;
|
||||
using FrameLedger.Application.Consent;
|
||||
@@ -40,6 +43,7 @@ internal sealed class AgentRecording
|
||||
private readonly IOverlayToleranceChannel _tolerance;
|
||||
private readonly WindowGeometryProbe _display = new();
|
||||
private readonly UserModeExceptionLapsePolicy _exceptionLapse;
|
||||
private readonly ICrashReporterSightings _reporters;
|
||||
|
||||
public AgentRecording(
|
||||
IGameConsentStore store,
|
||||
@@ -63,8 +67,10 @@ internal sealed class AgentRecording
|
||||
IDriverProfileSource profiles,
|
||||
IUserModeExceptionSwitch exceptions,
|
||||
IOverlayToleranceChannel tolerance,
|
||||
UserModeExceptionLapsePolicy exceptionLapse)
|
||||
UserModeExceptionLapsePolicy exceptionLapse,
|
||||
ICrashReporterSightings reporters)
|
||||
{
|
||||
_reporters = reporters;
|
||||
_profiles = profiles;
|
||||
_exceptions = exceptions;
|
||||
_tolerance = tolerance;
|
||||
@@ -120,7 +126,8 @@ internal sealed class AgentRecording
|
||||
_observer,
|
||||
_policy,
|
||||
_profiles,
|
||||
_exceptionLapse);
|
||||
_exceptionLapse,
|
||||
_reporters);
|
||||
}
|
||||
|
||||
/// <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>
|
||||
@@ -134,6 +141,7 @@ internal sealed class AgentRecording
|
||||
NvapiTelemetrySource? l3 = null;
|
||||
CompositeTelemetrySource? composite = null;
|
||||
SystemTelemetrySource? system = null;
|
||||
GameMemoryReader? game = null;
|
||||
try
|
||||
{
|
||||
pdh = new PdhAdapterMemoryCounter();
|
||||
@@ -151,9 +159,13 @@ internal sealed class AgentRecording
|
||||
// The machine beside the GPU (2026-09-21): CPU busy time and memory unprivileged, the CPU temperature only
|
||||
// where this process is elevated and PawnIO is installed. The poller owns it with the layers.
|
||||
system = SystemTelemetrySource.Create();
|
||||
var poller = new TelemetryPoller(composite, new TelemetryPollerOptions { Interval = interval }, TimeProvider.System, ownsSource: true, system);
|
||||
// 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);
|
||||
composite = null;
|
||||
system = null;
|
||||
game = null;
|
||||
return poller;
|
||||
}
|
||||
finally
|
||||
@@ -164,6 +176,7 @@ internal sealed class AgentRecording
|
||||
l3?.Dispose();
|
||||
composite?.Dispose();
|
||||
system?.Dispose();
|
||||
game?.Dispose();
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Agent.Hosting;
|
||||
using FrameLedger.Application.AntiCheat;
|
||||
using FrameLedger.Application.Capture;
|
||||
@@ -91,14 +94,7 @@ internal static class AgentServices
|
||||
services.AddSingleton<IRuntimeModuleSnapshot>(static _ => new RuntimeModuleSnapshot(CensusNames.ModuleFileNames));
|
||||
AddNvidia(services);
|
||||
|
||||
// The recorder's adapters (PR-D).
|
||||
services.AddSingleton<IPartialSessionStore>(_ => new PartialSessionStore(paths.Tmp));
|
||||
services.AddSingleton<ICrashEventSource, EventLogCrashSource>();
|
||||
services.AddSingleton<IHardwareSnapshotSource>(static _ => new HardwareSnapshotSource(new DxgiAdapters()));
|
||||
services.AddSingleton<ISeriesCodec, DeflateSeriesCodec>();
|
||||
services.AddSingleton<SessionFinalizer>();
|
||||
services.AddSingleton(static sp => new PartialRecovery(sp.GetRequiredService<IPartialSessionStore>(), sp.GetRequiredService<SessionFinalizer>()));
|
||||
services.AddSingleton<AgentRecording>();
|
||||
AddRecording(services, paths);
|
||||
|
||||
// The watcher (this PR): snapshots, identity, and the orchestrator over an unbounded recorder.
|
||||
services.AddSingleton<IProcessSnapshotSource, ToolhelpProcessSnapshotSource>();
|
||||
@@ -112,6 +108,20 @@ internal static class AgentServices
|
||||
return services;
|
||||
}
|
||||
|
||||
/// <summary>The recorder's adapters (PR-D), and since beta.14 the witness of engine crash reporters the watcher feeds and the recorder asks.</summary>
|
||||
private static void AddRecording(IServiceCollection services, AgentPaths paths)
|
||||
{
|
||||
services.AddSingleton<IPartialSessionStore>(_ => new PartialSessionStore(paths.Tmp));
|
||||
services.AddSingleton<ICrashEventSource, EventLogCrashSource>();
|
||||
services.AddSingleton<CrashReporterWitness>();
|
||||
services.AddSingleton<ICrashReporterSightings>(static sp => sp.GetRequiredService<CrashReporterWitness>());
|
||||
services.AddSingleton<IHardwareSnapshotSource>(static _ => new HardwareSnapshotSource(new DxgiAdapters()));
|
||||
services.AddSingleton<ISeriesCodec, DeflateSeriesCodec>();
|
||||
services.AddSingleton<SessionFinalizer>();
|
||||
services.AddSingleton(static sp => new PartialRecovery(sp.GetRequiredService<IPartialSessionStore>(), sp.GetRequiredService<SessionFinalizer>()));
|
||||
services.AddSingleton<AgentRecording>();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// D33 (owner decision 2026-09-26): the user-mode exception's option (one row in <c>settings</c>), its channel to the
|
||||
/// Overlay (<c>Local\FrameLedger.Tolerate.<pid></c>, created before an injection under it), and the policy that ends
|
||||
@@ -137,6 +147,25 @@ internal static class AgentServices
|
||||
services.AddSingleton<IDriverProfileSource>(static sp => sp.GetRequiredService<NvapiDriverProfileSource>());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// An entry whose game is no longer installed and that had no session goes (beta.19, D55): asked by the detection sweep after
|
||||
/// the relocator, behind the user's switch, never while a session of it is recorded or waits to be recovered — the merge's
|
||||
/// own busy test — and never for an entry carrying an anti-cheat block or exception (the delete's SQL checks again).
|
||||
/// </summary>
|
||||
private static void AddUninstalledEntryPrune(IServiceCollection services)
|
||||
{
|
||||
services.AddSingleton<IGamePrune>(static sp => new SqliteGamePrune(sp.GetRequiredService<LedgerDatabase>()));
|
||||
services.AddSingleton<IExecutablePresence>(static _ => new ExecutablePresenceProbe(VolumeRoots.IsReady));
|
||||
services.AddSingleton(static sp => new UninstalledEntryPrune(
|
||||
sp.GetRequiredService<IGamePrune>(),
|
||||
sp.GetRequiredService<IExecutablePresence>(),
|
||||
ct => sp.GetRequiredService<RegisteredSettings>().GetBooleanAsync(SettingsRegistry.RetentionRemoveUninstalledGames, ct),
|
||||
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|
||||
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id),
|
||||
static line => Serilog.Log.Information("{Line}", line),
|
||||
sp.GetRequiredService<IIpcEventPublisher>()));
|
||||
}
|
||||
|
||||
/// <summary>The static detection sweep (P4 PR-1, <c>05_DETECTION</c> §Caching): hosted under <c>--serve</c> only, composed and inert under <c>--console</c>.</summary>
|
||||
private static void AddDetection(IServiceCollection services, AgentPaths paths)
|
||||
{
|
||||
@@ -158,13 +187,15 @@ internal static class AgentServices
|
||||
merge: sp.GetRequiredService<IGameMerge>(),
|
||||
busy: id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|
||||
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id)));
|
||||
AddUninstalledEntryPrune(services);
|
||||
services.AddSingleton(static sp => new DetectionSweep(
|
||||
sp.GetRequiredService<IGameRepository>(),
|
||||
sp.GetRequiredService<IDetectionRulesSource>(),
|
||||
sp.GetRequiredService<IGameFileProbe>(),
|
||||
sp.GetRequiredService<IExecutableIdentitySource>(),
|
||||
static line => Serilog.Log.Information("{Line}", line),
|
||||
sp.GetRequiredService<ExecutableRelocator>()));
|
||||
sp.GetRequiredService<ExecutableRelocator>(),
|
||||
sp.GetRequiredService<UninstalledEntryPrune>()));
|
||||
|
||||
// The anti-cheat pre-scan of the library (beta.8, 19_SAFETY §What a finding does to the game): every entry through
|
||||
// the guard's advisory checks 3 and 4, again whenever the rules or the executable change. It waits while a session
|
||||
@@ -235,7 +266,8 @@ internal static class AgentServices
|
||||
static line => Serilog.Log.Information("{Line}", line),
|
||||
sp.GetRequiredService<ILaunchRecorderFactory>(),
|
||||
sp.GetRequiredService<ExecutableRelocator>(),
|
||||
sp.GetRequiredService<LatestProcessSnapshot>()));
|
||||
sp.GetRequiredService<LatestProcessSnapshot>(),
|
||||
sp.GetRequiredService<CrashReporterWitness>()));
|
||||
services.AddSingleton<ILaunchRecorderFactory, AgentLaunches>();
|
||||
|
||||
}
|
||||
@@ -272,7 +304,9 @@ internal static class AgentServices
|
||||
// D33: the user-mode exception's option and disclosure version (D38: no session count any more).
|
||||
new AntiCheatExceptionCommands(
|
||||
sp.GetRequiredService<IUserModeExceptionSwitch>(),
|
||||
AntiCheatExceptionDisclosure.Version));
|
||||
AntiCheatExceptionDisclosure.Version),
|
||||
// beta.11 (D40): Delete all sessions, of one game or of every game — the Agent's rows, deleted by the Agent.
|
||||
sp.GetRequiredService<ISessionRepository>());
|
||||
|
||||
/// <summary>
|
||||
/// <c>HelloAck.telemetrySource</c>: the layers this machine composes, read once on the first <c>Hello</c> by
|
||||
|
||||
@@ -12,6 +12,10 @@
|
||||
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
|
||||
<AssemblyName>FrameLedger.Agent</AssemblyName>
|
||||
<RootNamespace>FrameLedger.Agent</RootNamespace>
|
||||
<!-- beta.14 (D50): Task Manager lists a process by its file description, and until beta.14 this one read
|
||||
"FrameLedger.Agent" - the SDK's default, the assembly name - with the same as its company and product. -->
|
||||
<AssemblyTitle>FrameLedger Agent</AssemblyTitle>
|
||||
<Description>FrameLedger Agent: watches the games you added and records their sessions. Identifies itself deliberately; see https://github.com/poli0981/frameledger</Description>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
@@ -41,6 +45,7 @@
|
||||
-->
|
||||
<Import Project="$(MSBuildThisFileDirectory)..\..\FrameLedger.Guard.targets" />
|
||||
<Import Project="$(MSBuildThisFileDirectory)..\..\FrameLedger.NvapiBridge.targets" />
|
||||
<Import Project="$(MSBuildThisFileDirectory)..\..\FrameLedger.ProcessStats.targets" />
|
||||
|
||||
<!-- The seed the Agent installs to the product location on first run (§S20). -->
|
||||
<Import Project="$(MSBuildThisFileDirectory)..\..\FrameLedger.Rules.targets" />
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Data.Common;
|
||||
using FrameLedger.Application.AntiCheat;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Data.Common;
|
||||
using FrameLedger.Application.Detection;
|
||||
using FrameLedger.Application.Vulkan;
|
||||
@@ -36,10 +39,10 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
|
||||
DetectionSweepReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
|
||||
// Said when something happened or changed (2026-09-23): an unreadable entry used to repeat this line every
|
||||
// 15 s — 5,760 a day — with nothing new in it.
|
||||
if (r.Scanned > 0 || r.Relocated > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
|
||||
if (r.Scanned > 0 || r.Relocated > 0 || r.Removed > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
|
||||
{
|
||||
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}{Rules}",
|
||||
r.Scanned, r.Current, r.Unreadable, r.RulesUnusable ? ", rules unusable" : string.Empty);
|
||||
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}, removed {Removed}{Rules}",
|
||||
r.Scanned, r.Current, r.Unreadable, r.Removed, r.RulesUnusable ? ", rules unusable" : string.Empty);
|
||||
}
|
||||
|
||||
previous = r;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.Ipc;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Serilog;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.Ipc;
|
||||
using Serilog;
|
||||
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Infrastructure.Ipc;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Serilog;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Application.Recording;
|
||||
using FrameLedger.Application.Watch;
|
||||
using Microsoft.Extensions.Hosting;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
// FrameLedger.Agent — the capture orchestrator (P2 PR-F).
|
||||
//
|
||||
// The shipped host of the guard loop, by design (01_ARCHITECTURE §Component model; §S18 blocker 3):
|
||||
@@ -350,7 +353,7 @@ internal static class Program
|
||||
builder.Services.AddHostedService<PipeServerHostedService>();
|
||||
// Finalize's grace on shutdown (04_CAPTURE §Threading model): a session that does not make it leaves
|
||||
// its .partial for the next start's recovery.
|
||||
builder.Services.Configure<HostOptions>(static o => o.ShutdownTimeout = TimeSpan.FromSeconds(15));
|
||||
builder.Services.Configure<HostOptions>(static o => o.ShutdownTimeout = Shared.Ipc.IpcProtocol.AgentShutdownGrace);
|
||||
|
||||
using IHost host = builder.Build();
|
||||
AgentConsole.Line($@"serve: ledger {paths.Database}; logs {paths.Logs}; pipe \.\pipe\{Shared.Ipc.IpcProtocol.PipeName}; Ctrl+C stops");
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||||
<!-- Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE -->
|
||||
|
||||
<Application x:Class="FrameLedger.App.App"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Globalization;
|
||||
using System.IO;
|
||||
using System.Windows;
|
||||
@@ -12,7 +15,6 @@ using FrameLedger.Application.Settings;
|
||||
using FrameLedger.Application.Watch;
|
||||
using FrameLedger.Infrastructure.Diagnostics;
|
||||
using FrameLedger.Infrastructure.Import;
|
||||
using FrameLedger.Infrastructure.Ipc;
|
||||
using FrameLedger.Infrastructure.Persistence;
|
||||
using FrameLedger.Infrastructure.Watch;
|
||||
using Microsoft.Extensions.DependencyInjection;
|
||||
@@ -75,6 +77,9 @@ public partial class App : System.Windows.Application
|
||||
HookCrashHandlers();
|
||||
// 08_UI §Accessibility (P4 PR-8): Esc closes the open ContentDialog or MessageBox, before any window exists.
|
||||
DialogKeyboard.Register();
|
||||
// beta.14: ui.hide_scrollbars reaches every scroller as it is laid out (beta.17: not only as it loads), those in a
|
||||
// control's template too.
|
||||
ScrollBarHiding.Register();
|
||||
_run = DiagReport.Requested(e.Args) ? DiagAsync() : RunAsync();
|
||||
}
|
||||
|
||||
@@ -99,11 +104,18 @@ public partial class App : System.Windows.Application
|
||||
var registered = new RegisteredSettings(store);
|
||||
LoggingLevel.SetDebug(await registered.GetBooleanAsync(SettingsRegistry.LogDebug).ConfigureAwait(true));
|
||||
FpsDecimals.Two = await registered.GetBooleanAsync(SettingsRegistry.UiFpsDecimals).ConfigureAwait(true);
|
||||
ScrollBarHiding.Apply(await registered.GetBooleanAsync(SettingsRegistry.UiHideScrollBars).ConfigureAwait(true));
|
||||
var closePolicy = new WindowClosePolicy { MinimizeToTray = await registered.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true) };
|
||||
|
||||
_host = BuildHost(_db, appearance, registered, closePolicy);
|
||||
await _host.StartAsync().ConfigureAwait(true);
|
||||
Log.Information("ui: started ({Version}), ledger {Ledger}", UiIdentity.Version, UiPaths.Database);
|
||||
// beta.21: tier 0 is software rendering (a VM without a GPU, Remote Desktop) - every scroll drawn on the CPU.
|
||||
Log.Information("ui: render tier {Tier} (2 = the GPU draws; 0 = software)", System.Windows.Media.RenderCapability.Tier >> 16);
|
||||
if (UiPaths.IsViewer)
|
||||
{
|
||||
Log.Warning("ui: a VIEWER over {Folder} (--data-dir, D52): no Agent is started or contacted, nothing on this PC is changed", UiPaths.DataDirectory);
|
||||
}
|
||||
|
||||
// A second start of the App hands over to this one: bring the window forward, from the tray too.
|
||||
if (Instance is not null)
|
||||
@@ -182,7 +194,8 @@ public partial class App : System.Windows.Application
|
||||
Log.Warning(ex, "diag: the hardware could not be read; its lines are n/a");
|
||||
}
|
||||
|
||||
string report = DiagReport.Build(UiIdentity.Version, UiPaths.DataDirectory, UiPaths.Logs, schema, values, new AgentLauncher().CanLaunch, now, hardware);
|
||||
string report = DiagReport.Build(UiIdentity.Version, UiPaths.DataDirectory, UiPaths.Logs, schema, values, new AgentLauncher().CanLaunch, now, hardware,
|
||||
System.Windows.Media.RenderCapability.Tier >> 16);
|
||||
string path = DiagReport.Write(UiPaths.Logs, report, now);
|
||||
await Console.Out.WriteLineAsync(string.Format(CultureInfo.CurrentCulture, Strings.Diag_Written_Format, path)).ConfigureAwait(true);
|
||||
Log.Information("ui: --diag written to {Path}", path);
|
||||
@@ -269,7 +282,9 @@ public partial class App : System.Windows.Application
|
||||
builder.Services.AddSingleton(closePolicy);
|
||||
builder.Services.AddSingleton<IThemeApplier, WpfThemeApplier>();
|
||||
|
||||
AddAgentLink(builder.Services);
|
||||
// The Agent link, the Run entry, the Agent's maintenance flags and the updater: a viewer's composition holds none of
|
||||
// them that reaches past its ledger (beta.15, D52).
|
||||
MachineFacingServices.Add(builder.Services, UiPaths.Mode);
|
||||
|
||||
// FR-2.1 (P3 PR-4): the consent dialog and the request it ends in; the toggle that opens it is the game page's (PR-5).
|
||||
builder.Services.AddSingleton<IConsentPrompt, ConsentPrompt>();
|
||||
@@ -280,17 +295,12 @@ public partial class App : System.Windows.Application
|
||||
// The admin mode's disclosure (beta.10, D34), shown before capture.run_elevated is turned on.
|
||||
builder.Services.AddSingleton<IAgentAdminPrompt, AgentAdminPrompt>();
|
||||
builder.Services.AddSingleton<AntiCheatExceptions>();
|
||||
// beta.11 (D40): Delete all sessions, of one game (its page) or of every game (Settings ▸ Data), through the Agent.
|
||||
builder.Services.AddSingleton<SessionDeletion>();
|
||||
|
||||
AddLibrary(builder.Services);
|
||||
|
||||
// The shell: the window is TRANSIENT because a language change rebuilds it (09_I18N §Mechanics); the
|
||||
// shell host tracks the live one. Pages and their view models are transient (16 §Navigation).
|
||||
builder.Services.AddSingleton<ShellHost>();
|
||||
builder.Services.AddSingleton<IShellPresence>(static sp => sp.GetRequiredService<ShellHost>());
|
||||
builder.Services.AddSingleton<TrayViewModel>();
|
||||
builder.Services.AddSingleton<TrayHost>();
|
||||
builder.Services.AddTransient<MainWindow>();
|
||||
builder.Services.AddSingleton<MainWindowViewModel>();
|
||||
AddShell(builder.Services);
|
||||
builder.Services.AddTransient<DashboardPage>();
|
||||
builder.Services.AddTransient<DashboardViewModel>();
|
||||
builder.Services.AddTransient<GamesPage>();
|
||||
@@ -307,22 +317,21 @@ public partial class App : System.Windows.Application
|
||||
return builder.Build();
|
||||
}
|
||||
|
||||
/// <summary>The Agent over the pipe (07_IPC §Client behavior): connect, start it when it is not there, tell the shell.</summary>
|
||||
private static void AddAgentLink(IServiceCollection services)
|
||||
/// <summary>
|
||||
/// The shell: the window is TRANSIENT because a language change rebuilds it (09_I18N §Mechanics); the shell host tracks
|
||||
/// the live one. Pages and their view models are transient (16 §Navigation). The singletons that wrote their text once
|
||||
/// read it again after a change of language (beta.15, <see cref="ILanguageFollower"/>, called by ShellHost.Rebuild).
|
||||
/// </summary>
|
||||
private static void AddShell(IServiceCollection services)
|
||||
{
|
||||
// The admin mode's prompt (beta.10) belongs to the main window; the handle is read when a start asks, never earlier.
|
||||
services.AddSingleton<IAgentLauncher>(static sp => AgentLauncher.ForApp(() => sp.GetRequiredService<ShellHost>().Handle));
|
||||
services.AddSingleton(static sp => new AgentConnection(
|
||||
sp.GetRequiredService<IAgentLauncher>(),
|
||||
static () => new PipeClient(),
|
||||
new AgentConnectionOptions(),
|
||||
UiIdentity.Version));
|
||||
services.AddHostedService<AgentConnectionHostedService>();
|
||||
services.AddSingleton<IAgentRequests>(static sp => sp.GetRequiredService<AgentConnection>());
|
||||
services.AddSingleton<IAgentLink>(static sp => sp.GetRequiredService<AgentConnection>());
|
||||
// What the Agent runs right now (2026-09-23), for the pages rebuilt on every visit; built before the connection's
|
||||
// first round by AgentConnectionHostedService, so it never misses a session.
|
||||
services.AddSingleton(static sp => new LiveSessions(sp.GetRequiredService<IAgentLink>()));
|
||||
services.AddSingleton<ShellHost>();
|
||||
services.AddSingleton<IShellPresence>(static sp => sp.GetRequiredService<ShellHost>());
|
||||
services.AddSingleton<TrayViewModel>();
|
||||
services.AddSingleton<TrayHost>();
|
||||
services.AddTransient<MainWindow>();
|
||||
services.AddSingleton<MainWindowViewModel>();
|
||||
services.AddSingleton<ILanguageFollower>(static sp => sp.GetRequiredService<TrayHost>());
|
||||
services.AddSingleton<ILanguageFollower>(static sp => sp.GetRequiredService<MainWindowViewModel>());
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -350,12 +359,13 @@ public partial class App : System.Windows.Application
|
||||
services.AddTransient<SystemInfoViewModel>();
|
||||
services.AddSingleton<Charts.SessionSeriesLoader>();
|
||||
services.AddSingleton<IFileSaver, FileSaver>();
|
||||
services.AddSingleton<ISessionSummaryOpener, SessionSummaryOpener>();
|
||||
services.AddSingleton<SessionSummaryOpener>();
|
||||
services.AddSingleton<ISessionSummaryOpener>(static sp => sp.GetRequiredService<SessionSummaryOpener>());
|
||||
services.AddSingleton<ISessionWindows>(static sp => sp.GetRequiredService<SessionSummaryOpener>()); // beta.11: Delete all sessions closes them
|
||||
services.AddSingleton<IMixedTierPrompt, MixedTierPrompt>();
|
||||
|
||||
// Settings, the safety notices and the Logs page (P3 PR-8a): the Run entry, the notices over the pipe's
|
||||
// events, the tail and the bundle over the logs directory.
|
||||
services.AddSingleton<IRunAtLogon, RunAtLogonRegistry>();
|
||||
// Settings, the safety notices and the Logs page (P3 PR-8a): the notices over the pipe's events, the tail and the
|
||||
// bundle over the logs directory (the Run entry is MachineFacingServices').
|
||||
services.AddSingleton<SafetyNotices>();
|
||||
services.AddSingleton(static _ => new LogTail(UiPaths.Logs));
|
||||
services.AddSingleton(static sp => new BugBundleBuilder(UiPaths.Logs, sp.GetRequiredService<RegisteredSettings>(), crashDumpDirectory: UiPaths.CrashDumps, redactor: LogRedactor.ForCurrentUser()));
|
||||
@@ -372,9 +382,9 @@ public partial class App : System.Windows.Application
|
||||
|
||||
AddImport(services);
|
||||
|
||||
// The layer registration and the logon task (P3 PR-8b): read from the machine, written by the Agent's flags.
|
||||
// The layer registration and the logon task (P3 PR-8b): read from the machine, written by the Agent's flags
|
||||
// (IAgentTool, MachineFacingServices').
|
||||
services.AddSingleton<IMaintenanceState, MaintenanceState>();
|
||||
services.AddSingleton<IAgentTool, AgentTool>();
|
||||
|
||||
AddUpdates(services);
|
||||
|
||||
@@ -385,18 +395,20 @@ public partial class App : System.Windows.Application
|
||||
services.AddSingleton<ILegalAcceptanceStore, SqliteLegalAcceptanceStore>();
|
||||
services.AddSingleton(static sp => new LegalGate(sp.GetRequiredService<ILegalAcceptanceStore>(), LegalDocuments.Load()));
|
||||
services.AddSingleton<IFirstRunFlow, FirstRunFlow>();
|
||||
|
||||
// beta.12: Help ▸ Limitations and Help ▸ About, rendered from what this build embeds.
|
||||
services.AddSingleton<IDocumentWindows, DocumentWindows>();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The updater (P4 PR-5, <c>11_UPDATER</c>): Velopack behind the <see cref="IUpdateClient"/> port, the dialogs behind
|
||||
/// <see cref="IUpdatePrompts"/>, the flow that holds FR-12, and the startup check as a hosted service.
|
||||
/// The updater (P4 PR-5, <c>11_UPDATER</c>): the dialogs behind <see cref="IUpdatePrompts"/> and the flow that holds
|
||||
/// FR-12. Velopack behind the <see cref="IUpdateClient"/> port and the startup check are MachineFacingServices': a
|
||||
/// viewer has neither.
|
||||
/// </summary>
|
||||
private static void AddUpdates(IServiceCollection services)
|
||||
{
|
||||
services.AddSingleton<IUpdateClient, VelopackUpdateClient>();
|
||||
services.AddSingleton<IUpdatePrompts, UpdatePrompts>();
|
||||
services.AddSingleton<UpdateService>();
|
||||
services.AddHostedService<UpdateHostedService>();
|
||||
}
|
||||
|
||||
/// <summary>FR-1.2's library import (P4 PR-4): the stores, the executable guess, the importer over the games port, the review checklist behind a port.</summary>
|
||||
@@ -409,6 +421,14 @@ public partial class App : System.Windows.Application
|
||||
services.AddSingleton<IStoreLibrarySource>(static _ => new EpicLibrarySource());
|
||||
services.AddSingleton<IStoreLibrarySource>(static _ => new ItchLibrarySource(log: static line => Serilog.Log.Information("{Line}", line)));
|
||||
services.AddSingleton<IExecutableLocator, ExecutableLocator>();
|
||||
// beta.21 (D59): Play reads the same records to find the store that installed a game, and GOG GALAXY's program.
|
||||
services.AddSingleton<Application.Play.IGogGalaxyLocator>(static _ => new GogGalaxyLocator());
|
||||
services.AddSingleton(static sp => new GamePlayer(
|
||||
sp.GetRequiredService<Application.Settings.RegisteredSettings>(),
|
||||
sp.GetServices<IStoreLibrarySource>(),
|
||||
sp.GetRequiredService<Application.Play.IGogGalaxyLocator>(),
|
||||
sp.GetRequiredService<IShellStarter>(),
|
||||
sp.GetRequiredService<IAgentRequests>()));
|
||||
services.AddSingleton<IExecutableIdentitySource, ExecutableIdentitySource>();
|
||||
services.AddSingleton(static sp => new LibraryImporter(
|
||||
sp.GetServices<IStoreLibrarySource>(),
|
||||
@@ -417,6 +437,8 @@ public partial class App : System.Windows.Application
|
||||
sp.GetRequiredService<IExecutableLocator>(),
|
||||
static line => Serilog.Log.Information("{Line}", line)));
|
||||
services.AddSingleton<IImportReview, ImportReviewPrompt>();
|
||||
// beta.11: the Games page on screen reloads when an import adds games (navigating to itself does nothing).
|
||||
services.AddSingleton<LibraryChanges>();
|
||||
services.AddSingleton<ImportLibraryFlow>();
|
||||
}
|
||||
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Windows;
|
||||
|
||||
[assembly: ThemeInfo(
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Windows;
|
||||
using ScottPlot;
|
||||
using Wpf.Ui.Appearance;
|
||||
@@ -22,13 +25,15 @@ public sealed record ChartPalette(
|
||||
Color SensorSecondary,
|
||||
Color Segment,
|
||||
Color Histogram,
|
||||
Color Percentile)
|
||||
Color Percentile,
|
||||
Color SensorTertiary)
|
||||
{
|
||||
/// <summary>The keys both dictionaries must carry, in the record's order.</summary>
|
||||
public static readonly IReadOnlyList<string> Keys =
|
||||
[
|
||||
"Chart_Figure", "Chart_Data", "Chart_Axis", "Chart_Grid", "Chart_Native", "Chart_Displayed", "Chart_Stutter",
|
||||
"Chart_StutterPso", "Chart_Sensor", "Chart_SensorSecondary", "Chart_Segment", "Chart_Histogram", "Chart_Percentile",
|
||||
"Chart_SensorTertiary",
|
||||
];
|
||||
|
||||
private static readonly Dictionary<ApplicationTheme, ChartPalette> _cache = [];
|
||||
@@ -54,7 +59,7 @@ public sealed record ChartPalette(
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(dictionary);
|
||||
Color[] c = [.. Keys.Select(k => Convert(dictionary, k))];
|
||||
return new ChartPalette(c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7], c[8], c[9], c[10], c[11], c[12]);
|
||||
return new ChartPalette(c[0], c[1], c[2], c[3], c[4], c[5], c[6], c[7], c[8], c[9], c[10], c[11], c[12], c[13]);
|
||||
}
|
||||
|
||||
/// <summary>The colour a key names — how a chart that assigns palette entries to series by name reads them (<c>SensorsChart</c>).</summary>
|
||||
@@ -73,6 +78,7 @@ public sealed record ChartPalette(
|
||||
"Chart_Segment" => Segment,
|
||||
"Chart_Histogram" => Histogram,
|
||||
"Chart_Percentile" => Percentile,
|
||||
"Chart_SensorTertiary" => SensorTertiary,
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(key), key, "not a chart palette key"),
|
||||
};
|
||||
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using ScottPlot;
|
||||
using ScottPlot.WPF;
|
||||
using Wpf.Ui.Appearance;
|
||||
@@ -67,10 +70,14 @@ public static class ChartTheme
|
||||
(byte)Math.Round((top.B * a) + (under.B * (1 - a))));
|
||||
}
|
||||
|
||||
/// <summary>Registers a control so a theme change re-applies and refreshes it (weakly held; a closed window is forgotten).</summary>
|
||||
/// <summary>
|
||||
/// Registers a control so a theme change re-applies and refreshes it (weakly held; a closed window is forgotten), and
|
||||
/// gives it the App's wheel: a plain wheel scrolls the page, Ctrl+wheel zooms (<see cref="ChartWheel"/>, beta.14).
|
||||
/// </summary>
|
||||
public static void Attach(WpfPlot control)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(control);
|
||||
ChartWheel.Attach(control);
|
||||
lock (_lock)
|
||||
{
|
||||
_live.RemoveAll(static w => !w.TryGetTarget(out _));
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Windows;
|
||||
using System.Windows.Input;
|
||||
using System.Windows.Media;
|
||||
using ScottPlot.WPF;
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
/// <summary>
|
||||
/// The mouse wheel over a chart (beta.14). ScottPlot 5's <see cref="WpfPlot"/> zooms on every wheel and never marks it
|
||||
/// handled, so with the pages scrolling again (<c>16_WPFUI_SYNTAX</c> §Gotchas: they did not until beta.14) a wheel over a
|
||||
/// chart would have zoomed it AND scrolled the page under the pointer. A plain wheel now belongs to the page — ScottPlot
|
||||
/// never sees it — and Ctrl+wheel to the chart, which zooms and keeps the page where it is. Every plot reaches this through
|
||||
/// <see cref="ChartTheme.Attach"/>.
|
||||
/// </summary>
|
||||
internal static class ChartWheel
|
||||
{
|
||||
/// <summary>Whether a wheel with these modifier keys zooms the chart rather than scrolling the page: Ctrl held.</summary>
|
||||
public static bool Zooms(ModifierKeys modifiers) => (modifiers & ModifierKeys.Control) == ModifierKeys.Control;
|
||||
|
||||
/// <summary>
|
||||
/// The modifier keys the two handlers read: <see cref="Keyboard.Modifiers"/>, which is the machine's real keyboard — a
|
||||
/// thread that never had keyboard focus still reads it (measured 2026-10-06: a fresh background thread's
|
||||
/// <c>GetKeyState</c> reported the machine's NumLock). So a test driving the wheel end to end held whatever key a person
|
||||
/// pressed while it ran — the one input it did not control, and the plain half went red once in a gate on the developer's
|
||||
/// machine and never on CI. The tests set this for the length of one dispatcher work item and put it back; the App never
|
||||
/// sets it.
|
||||
/// </summary>
|
||||
internal static Func<ModifierKeys> CurrentModifiers { get; set; } = static () => Keyboard.Modifiers;
|
||||
|
||||
public static void Attach(WpfPlot plot)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(plot);
|
||||
plot.PreviewMouseWheel += OnPreviewMouseWheel;
|
||||
plot.MouseWheel += OnMouseWheel;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The tunnelling half, before ScottPlot's own handler on its inner element: a plain wheel is taken from the plot and
|
||||
/// raised again on the plot's parent, from where it bubbles to the page's scroller as any other wheel would.
|
||||
/// </summary>
|
||||
private static void OnPreviewMouseWheel(object sender, MouseWheelEventArgs e)
|
||||
{
|
||||
if (e.Handled || Zooms(CurrentModifiers()) || sender is not DependencyObject plot)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
e.Handled = true;
|
||||
if (VisualTreeHelper.GetParent(plot) is UIElement parent)
|
||||
{
|
||||
parent.RaiseEvent(new MouseWheelEventArgs(e.MouseDevice, e.Timestamp, e.Delta) { RoutedEvent = UIElement.MouseWheelEvent, Source = sender });
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The bubbling half, after ScottPlot has zoomed: Ctrl+wheel stops here, so the page does not scroll as well.</summary>
|
||||
private static void OnMouseWheel(object sender, MouseWheelEventArgs e)
|
||||
{
|
||||
if (Zooms(CurrentModifiers()))
|
||||
{
|
||||
e.Handled = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,6 @@
|
||||
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||||
<!-- Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE -->
|
||||
|
||||
<UserControl x:Class="FrameLedger.App.Charts.CompareChart"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Windows.Controls;
|
||||
using ScottPlot;
|
||||
using ScottPlot.Plottables;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
/// <summary>One session's percentile curve on the Compare overlay: its legend label and the 101 points.</summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
/// <summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||||
<!-- Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE -->
|
||||
|
||||
<UserControl x:Class="FrameLedger.App.Charts.DistributionChart"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
@@ -17,6 +20,6 @@
|
||||
</Grid.ColumnDefinitions>
|
||||
<sp:WpfPlot x:Name="Histogram" Grid.Column="0" />
|
||||
<sp:WpfPlot x:Name="Percentiles" Grid.Column="2" />
|
||||
<ui:TextBlock x:Name="Note" Grid.Row="1" Grid.ColumnSpan="3" Margin="0,4,0,0" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
|
||||
<ui:TextBlock x:Name="Note" Grid.Row="1" Grid.ColumnSpan="3" Margin="0,4,0,0" Style="{StaticResource TertiaryText}" TextWrapping="Wrap" Visibility="Collapsed" />
|
||||
</Grid>
|
||||
</UserControl>
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Globalization;
|
||||
using System.Windows;
|
||||
using System.Windows.Controls;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Domain.Metrics;
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
@@ -1,17 +1,21 @@
|
||||
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||||
<!-- Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE -->
|
||||
|
||||
<UserControl x:Class="FrameLedger.App.Charts.FrametimeChart"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
xmlns:ui="http://schemas.lepo.co/wpfui/2022/xaml"
|
||||
xmlns:sp="clr-namespace:ScottPlot.WPF;assembly=ScottPlot.WPF"
|
||||
MinHeight="260">
|
||||
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's.
|
||||
<!-- 08_UI §Session summary / FR-5.1: the frametime timeline, min/max decimated (FR-5.3); zoom and pan are ScottPlot's —
|
||||
zoom with Ctrl+wheel since beta.14, a plain wheel scrolls the page (ChartWheel).
|
||||
The note above it says what the lines are not, when that is not obvious (beta.8). -->
|
||||
<Grid>
|
||||
<Grid.RowDefinitions>
|
||||
<RowDefinition Height="Auto" />
|
||||
<RowDefinition Height="*" />
|
||||
</Grid.RowDefinitions>
|
||||
<ui:TextBlock x:Name="Note" Grid.Row="0" Margin="0,0,0,4" Appearance="Tertiary" TextWrapping="Wrap" Visibility="Collapsed" />
|
||||
<ui:TextBlock x:Name="Note" Grid.Row="0" Margin="0,0,0,4" Style="{StaticResource TertiaryText}" TextWrapping="Wrap" Visibility="Collapsed" />
|
||||
<sp:WpfPlot x:Name="Plot" Grid.Row="1" />
|
||||
</Grid>
|
||||
</UserControl>
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Globalization;
|
||||
using System.Windows;
|
||||
using System.Windows.Controls;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
/// <summary>FR-6.3: a hardware-snapshot difference between two consecutive sessions, as a marker on the trend line ("GPU driver 572.16 → 576.02").</summary>
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
<!-- SPDX-License-Identifier: GPL-3.0-only -->
|
||||
<!-- Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE -->
|
||||
|
||||
<UserControl x:Class="FrameLedger.App.Charts.LatencyChart"
|
||||
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using System.Windows.Controls;
|
||||
using ScottPlot;
|
||||
using ScottPlot.Plottables;
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
||||
|
||||
using FrameLedger.Domain.Metrics;
|
||||
|
||||
namespace FrameLedger.App.Charts;
|
||||
|
||||
Loaded 100 of 1303 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user