Compare commits
62
Commits
No files matched your search
@@ -38,4 +38,6 @@ review questions from `docs/19_SAFETY_AND_ANTICHEAT.md` §Review checklist.
|
||||
## Notes for the reviewer
|
||||
|
||||
<!-- Anything that would be hard to see from the diff. If you resolved an item
|
||||
in docs/20_OPEN_QUESTIONS.md, say which one and delete it from that file. -->
|
||||
in docs/20_OPEN_QUESTIONS.md, say which one, mark it resolved in §S24, and move
|
||||
the entry verbatim to docs/open-questions/closed-*.md with its row in the table
|
||||
at the end of its series (beta.24, D66). -->
|
||||
@@ -47,7 +47,7 @@ jobs:
|
||||
global-json-file: global.json
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ jobs:
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
if: matrix.language == 'cpp'
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@ jobs:
|
||||
global-json-file: global.json
|
||||
|
||||
- name: Set up MSVC (x64)
|
||||
uses: ilammy/msvc-dev-cmd@v1
|
||||
uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
|
||||
with:
|
||||
arch: x64
|
||||
|
||||
@@ -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
|
||||
@@ -154,7 +170,9 @@ jobs:
|
||||
$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
|
||||
@@ -195,8 +213,12 @@ jobs:
|
||||
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)
|
||||
|
||||
@@ -210,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
|
||||
|
||||
@@ -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"
|
||||
@@ -0,0 +1,22 @@
|
||||
# SonarCloud Automatic Analysis — read from the default branch (docs/13_CI_CD.md §SonarCloud, decision D67).
|
||||
# Automatic Analysis reads only this file: sonar.issue.ignore.* is not supported here, so the rules accepted by design
|
||||
# are recorded in docs/13_CI_CD.md and marked by the owner in SonarCloud's own UI.
|
||||
|
||||
# What is not FrameLedger's code, or not code at all:
|
||||
# - src/native/third_party: the vendored SDK headers (NVAPI, Streamline, FidelityFX, Vulkan-Headers) — 51 headers,
|
||||
# 66 thousand lines, consumed unmodified (each folder's README says so and license-check holds it).
|
||||
# - Strings.Designer.cs: generated by tools/resx-gen.ps1.
|
||||
# - dxr_raygen_dxil.h: a compiled shader as a byte array, generated.
|
||||
# - vendor-stubs: test fixtures that carry the vendors' export names and signatures on purpose.
|
||||
# - tests/fixtures: the detection corpus (empty marker binaries and expected JSON).
|
||||
# - legal/licenses, docs/vendor-exports.json: licence texts and a generated export list.
|
||||
# - Migrations: SQLite scripts, which a SQL analyser reads as another dialect.
|
||||
sonar.exclusions=src/native/third_party/**,**/Strings.Designer.cs,src/native/tools/hook-harness/dxr_raygen_dxil.h,src/native/tools/vendor-stubs/**,tests/fixtures/**,legal/licenses/**,docs/vendor-exports.json,src/FrameLedger.Infrastructure/Persistence/Migrations/**
|
||||
|
||||
# Tests repeat their arrange steps on purpose; duplication there is not a defect.
|
||||
sonar.cpd.exclusions=tests/**,src/native/tests/**
|
||||
|
||||
# The native code is C++20 (src/native/CMakeLists.txt); report against it, not a later standard.
|
||||
sonar.cfamily.reportingCppStandardOverride=c++20
|
||||
|
||||
sonar.sourceEncoding=UTF-8
|
||||
+45
-5581
File diff suppressed because it is too large.
Load diff
@@ -16,7 +16,7 @@ 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.
|
||||
@@ -30,6 +30,8 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
|
||||
> **Amended 2026-09-06 (Leg 0 landed): narrowed, not withdrawn.** `sl.dlss_g.dll` is a startup-time load on that title (frame generation off, census unchanged, twice), and the same morning's ×4 capture measured the discriminator the gate lacked: the 2.8.0 pacer's generated presents are DXGI presents on the hooked chain (§H5 row P1-DXGI), counted through `dxgiUnseen` into `Native 70.52 → Displayed 282.08 (×4 FG)`. So a counted `none` beside a READ `IDXGISwapChain::GetLastPresentCount` with zero unseen is `none`, printed with DXGI's agreement; it is withheld only when the counter was not read.
|
||||
>
|
||||
> **Amended 2026-09-17 (owner decision): the steady state.** A session whose frame-generation state changed (menus, loading, a settings change) has no session-wide factor — averaging ×1 menus with ×4 gameplay is the inflated-or-deflated single number this rule forbids — but it is no longer left with none: *Native → Displayed (×N FG)* is shown for the state the session spent most of its generating time in, **always with the share of the session it covers** (`62 → 118 FPS (×1.9 FG · 75%)`), never as a session average (`docs/03_METRICS.md` §The steady state).
|
||||
>
|
||||
> **Amended 2026-10-19 (owner decision D62): the mix.** Beside the steady state, the session summary lists every frame-generation state the session held — each with its own *Native → Displayed*, its factor and its share of the presenting time (`×4.0 frame generation · 35.33% · 70 → 282 FPS`) — then the time with no frame generation and the time no state claims. Every row is one state's own numbers; nothing is averaged across states, and a state's factor never appears without its rates (`docs/03_METRICS.md` §The mix).
|
||||
7. **RT / PT / RR are tri-state** (`Yes` / `No` / `N/A`) with manual override. They are now *measured*, not guessed — but where measurement is genuinely impossible, the honest answer is still `N/A`. Never fabricate `Yes`.
|
||||
|
||||
> **Amended 2026-08-20 with the PR that wrote the hooks, per the owner ruling of 2026-08-14.** This rule named *"inline RayQuery without DXIL scan"* as one of the impossible cases, and that conflated two questions. **Whether rays are being traced is measurable** — `BuildRaytracingAccelerationStructure` is called by RayQuery titles and by `DispatchRays` titles alike, which is why both hooks exist and why the `No` branch requires the AS-build hook to have been *installed*. What needs a DXIL scan is **classifying the technique as RayQuery**, and that stays `N/A`. So the impossible cases are: naming the technique, and path-tracing classification, which has no API-level signature at all (`03_METRICS` §RT/PT/RR — a confidence score that may only ever *suggest*).
|
||||
@@ -70,7 +72,8 @@ build.ps1 # the quality gate; CI runs this identical script
|
||||
src/
|
||||
native/
|
||||
FrameLedger.Overlay/ # C++20 DLL injected into the game (hooks + ring writer + optional overlay)
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe
|
||||
FrameLedger.Injector/ # C++20 static lib: launch/attach injection, AC guard probe; also builds
|
||||
# FrameLedger.Guard.dll, the guard's C ABI the Agent loads (line added 2026-10-14)
|
||||
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)
|
||||
@@ -113,7 +116,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
|
||||
@@ -136,7 +141,10 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
|
||||
# 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
|
||||
# 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),
|
||||
# docs-split-check (beta.24, D66: CHANGELOG/HANDOFF and their parts agree)
|
||||
# (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
|
||||
@@ -149,8 +157,13 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
|
||||
# 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
|
||||
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/
|
||||
```
|
||||
|
||||
@@ -187,7 +200,10 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
|
||||
0. **`docs/HANDOFF.md` — what to do next and in what order.** It carries sequencing,
|
||||
decisions that live in no other file, and the traps that cost a cycle each. It
|
||||
deliberately carries **no status**: it points at the four files that do. Start there
|
||||
if you are picking up work; start at 1 if you are learning the system.
|
||||
if you are picking up work; start at 1 if you are learning the system. *(Since beta.24, D66, the history of every
|
||||
train, the passed owner-only items and the traps live in `docs/handoff/`; HANDOFF.md's §How this file is split and
|
||||
§Decisions index resolve every old citation. CHANGELOG.md likewise keeps `[Unreleased]` and links each release's
|
||||
file under `docs/changelog/`.)*
|
||||
1. `docs/19_SAFETY_AND_ANTICHEAT.md` — the guard, the refusal list, what we will not build
|
||||
2. `docs/01_ARCHITECTURE.md` — processes, injection flow, lifecycle
|
||||
3. `docs/02_SPEC.md` — FR/NFR ids used everywhere
|
||||
@@ -203,7 +219,8 @@ The version handshake is wired end to end as of 2026-08-05: `FlGuardBuildId` giv
|
||||
PR (D36, 2026-09-27). **`docs/LIST_GAME_TESTED.md`** — the real games FrameLedger has been run with and what each
|
||||
session measured, from a copy of the owner's ledger and the repository's own evidence (D35).
|
||||
|
||||
**Before writing native or capture code, read `docs/20_OPEN_QUESTIONS.md`.** It
|
||||
**Before writing native or capture code, read `docs/20_OPEN_QUESTIONS.md`** (its open entries; since beta.24 the
|
||||
resolved ones are in `docs/open-questions/`, a table at the end of each series lists them). It
|
||||
lists the defects and gaps that survived the doc audit — things the other
|
||||
documents cannot answer because they need an empirical result or a decision. The
|
||||
S-series items are safety items and block the first real injection. If you are
|
||||
|
||||
@@ -27,6 +27,16 @@ That is the whole quality gate, and continuous integration runs the identical sc
|
||||
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`:
|
||||
|
||||
@@ -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'))">
|
||||
|
||||
@@ -75,9 +75,9 @@
|
||||
</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="Microsoft.VisualStudio.Threading.Analyzers" Version="18.7.23" />
|
||||
<PackageVersion Include="Roslynator.Analyzers" Version="5.0.1" />
|
||||
<PackageVersion Include="Meziantou.Analyzer" Version="3.0.307" />
|
||||
<PackageVersion Include="Microsoft.VisualStudio.Threading.Analyzers" Version="18.12.1" />
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup Label="Testing">
|
||||
|
||||
+1
-1
@@ -68,7 +68,7 @@ share — and migrate — one database, and fight over the same pipe and shared
|
||||
| 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` in `src/native/CMakeLists.txt`, and the `ProductName` that `tools/versioninfo-check.ps1` requires | anti-cheat vendors and users identify the DLLs loaded into games by it (`docs/19_SAFETY_AND_ANTICHEAT.md`); it must name your project |
|
||||
| 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
|
||||
|
||||
+83
-7
@@ -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.12.*
|
||||
*Beta software: this page describes version 0.1.0-beta.24.*
|
||||
|
||||
## 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.
|
||||
@@ -39,6 +40,18 @@ 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
|
||||
@@ -52,15 +65,39 @@ 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))
|
||||
- **The mix of frame-generation states** in a session's summary (since 0.1.0-beta.24) is read over five-second
|
||||
windows: frame generation that changes faster than that — the NVIDIA App's *Dynamic* mode can — reads partly as
|
||||
*Not classified*, and a state shorter than 10 seconds is not listed. The multiplier chosen in a game's own menu is
|
||||
not read; the measured factor is its evidence. How the NVIDIA App's *Dynamic* ceiling and *Max refresh rate* target
|
||||
are stored by the driver is read from NVIDIA's own setting names and not yet checked against the App on a real
|
||||
game. Sessions recorded before 0.1.0-beta.24 have no mix. ([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
|
||||
reports it, the page says it is the driver's report.
|
||||
- **The quality preset** (Quality, Balanced, …) has not been reported on any game yet, and the render
|
||||
resolution is N/A where the game's own calls do not carry it (DLSS without Streamline, for one).
|
||||
- **The quality mode** (Quality, Balanced, DLAA, …) is shown only when it is known: the NVIDIA App's override
|
||||
where the NVIDIA driver reports it applied (marked *· NVIDIA App*, since 0.1.0-beta.24), or the mode the game
|
||||
passed to a call FrameLedger reads — which no game has done yet. The mode chosen in a game's own menu is not
|
||||
readable for DLSS without Streamline, and is not inferred from the render scale. How the driver numbers DLAA in
|
||||
its report is NVIDIA's documented value, not yet seen on a real game. The render resolution is N/A where the
|
||||
game's own calls do not carry it (DLSS without Streamline, for one). ([Metrics](docs/03_METRICS.md))
|
||||
- **Which DLSS ran** (since 0.1.0-beta.24) is named only from what the session showed: the model preset the NVIDIA
|
||||
driver reports (L or M: DLSS 4.5; J or K: DLSS 4), a measured multi-frame factor (×5 or ×6: DLSS 4.5; ×3 or ×4:
|
||||
DLSS 4), or a library whose major version names one (2.x, 3.x). A 310 library with no such evidence shows its
|
||||
version only. DLSS 5 is shown only as *runtime loaded*, by a library name not yet seen on a real game. Where each
|
||||
library was loaded from is read from its folder, for sessions recorded since 0.1.0-beta.24.
|
||||
- **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.
|
||||
@@ -96,8 +133,15 @@ 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
|
||||
|
||||
@@ -111,6 +155,11 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.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
|
||||
|
||||
@@ -128,8 +177,30 @@ you accept the prompt. Turn it on only if you trust everything that runs under y
|
||||
- The games FrameLedger has actually been run with, and what was measured on each, are listed in
|
||||
[LIST_GAME_TESTED.md](docs/LIST_GAME_TESTED.md). Everything was measured on one machine (an NVIDIA
|
||||
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.
|
||||
- **One real Vulkan game has been measured** (Everhex Demo, 2026-10-13) **and no OpenGL game**, beyond 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.
|
||||
|
||||
## Game artwork
|
||||
|
||||
- **Only the Steam and GOG GALAXY apps keep pictures FrameLedger can show** (since 0.1.0-beta.23). A game's page shows
|
||||
the cover and banner those apps keep on your PC for a game they installed, read where they keep them — nothing is
|
||||
downloaded or copied. A game from itch, the Epic Games Launcher or another store, or one whose `.exe` is outside a
|
||||
store's own folder, shows a picture only once you choose one (**Edit… ▸ Choose image…**). A GOG picture needs Windows'
|
||||
WebP support, which Windows 11 and most Windows 10 installs have. ([Game page](docs/08_UI.md))
|
||||
- The pictures belong to the games' owners; FrameLedger ships none ([names and trademarks](legal/TRADEMARKS.md)).
|
||||
|
||||
## Your data
|
||||
|
||||
@@ -146,3 +217,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.
|
||||
@@ -5,12 +5,14 @@
|
||||
> 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. What FrameLedger cannot do is on one page:
|
||||
[Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User guide, Help ▸ Limitations).
|
||||
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-10-04.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.12`** (2026-10-04), an unsigned installer built from that tag with its
|
||||
> ⚠ **What FrameLedger actually measures today — 2026-10-19.** The software is a beta; its latest
|
||||
> **pre-release is `0.1.0-beta.24`** (2026-10-19), 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
|
||||
@@ -19,8 +21,9 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
|
||||
>
|
||||
> - **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
|
||||
@@ -33,9 +36,14 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
|
||||
> was measured. Intel XeSS is **not** read (its SDK licence
|
||||
> forbids it), and neither is an upscaler compiled into the game: those read `N/A`, or "Unknown
|
||||
> upscaler" when another vendor's hook ran in the game. Vulkan and OpenGL titles read `N/A`.
|
||||
> - **Quality preset:** not reported on any title measured. The one route this software may use — the
|
||||
> DLSS options a Streamline title passes with its per-frame call — has not been seen on a real
|
||||
> title, and AMD's per-frame call carries no preset.
|
||||
> - **Quality mode:** shown only when it is known. When the NVIDIA App overrides DLSS Super Resolution for
|
||||
> the game and the NVIDIA driver reports that the override applied in the session, the override's mode is
|
||||
> shown and marked as the NVIDIA App's. Otherwise the mode the game itself passed: the DLSS options a
|
||||
> Streamline title passes with its per-frame call (not yet seen on a real title). In every other case no
|
||||
> mode is shown.
|
||||
> - **DLSS version:** the version of each DLSS library the game loaded and whether it came from the game or from
|
||||
> the NVIDIA driver; "DLSS 4" or "DLSS 4.5" only when the session shows it (the model preset the driver reports,
|
||||
> or a measured multi-frame factor); DLSS 5 only as "runtime loaded".
|
||||
> - **Render → output resolution:** measured where the vendor's own per-frame call carries the render
|
||||
> size (AMD FidelityFX dispatches, and Streamline titles whose resource tags state it); `N/A` where it
|
||||
> does not: DLSS titles that bypass Streamline, Streamline titles whose tags carry no size, and Vulkan
|
||||
@@ -47,12 +55,13 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
|
||||
> (menus, loading screens, a settings change), no session-wide factor is shown: the factor, Native and
|
||||
> Displayed are those of the state that held longest — five-second windows whose ratios agree within
|
||||
> 10 %, covering at least 10 s and 10 % of the time the game was presenting — and are always shown with
|
||||
> the share of the session they cover; with no such state, the reason is shown instead. DLSS-G and FSR
|
||||
> FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled into the game)
|
||||
> is shown only as active with the technology not identified, and is never named. Where a technology is
|
||||
> named but its frames could not be counted, or frame generation is not measured, the software shows
|
||||
> **Presented FPS** with a note on what it may include — never a Native figure. Where generated frames
|
||||
> were counted, the lows, median and stutter are taken over application frames only.
|
||||
> the share of the session they cover; with no such state, the reason is shown instead. The session
|
||||
> summary lists each state it held, with its share of the time and its own Native → Displayed rates.
|
||||
> DLSS-G and FSR FG are named from the calls the game makes; any other generator (XeSS-FG, one compiled
|
||||
> into the game) is shown only as active with the technology not identified, and is never named. Where a
|
||||
> technology is named but its frames could not be counted, or frame generation is not measured, the
|
||||
> software shows **Presented FPS** with a note on what it may include — never a Native figure. Where generated
|
||||
> frames were counted, the lows, median and stutter are taken over application frames only.
|
||||
> - **Ray tracing:** Yes/No measured on Direct3D 12 from ray-dispatch and acceleration-structure-build
|
||||
> calls; the technique and path tracing are `N/A`, and so is ray tracing on other APIs.
|
||||
> - **Display mode:** how each game's window was shown — exclusive full-screen, borderless, windowed or
|
||||
@@ -61,8 +70,11 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
|
||||
> 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
|
||||
@@ -73,6 +85,14 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
|
||||
> 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
|
||||
@@ -153,7 +173,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
|
||||
|
||||
## Install
|
||||
|
||||
> **The latest pre-release is `v0.1.0-beta.12` (2026-10-04); before it `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`.
|
||||
> **The latest pre-release is `v0.1.0-beta.24` (2026-10-19); before it `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `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 the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for 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**.
|
||||
@@ -183,6 +203,8 @@ FrameLedger is GPL-3.0-only free software, and you are welcome to build it, chan
|
||||
[`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).
|
||||
@@ -200,4 +222,4 @@ GPU telemetry is layered so the project never depends on a proprietary vendor li
|
||||
|
||||
---
|
||||
|
||||
**Status:** pre-release (beta). Twelve 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-three 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.
|
||||
@@ -320,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'
|
||||
@@ -450,6 +464,23 @@ function Invoke-ProjectGates {
|
||||
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 }
|
||||
|
||||
# beta.24 (D66): CHANGELOG.md and docs/HANDOFF.md keep their paths as the index of their parts under docs/changelog/
|
||||
# and docs/handoff/. A released section left in CHANGELOG.md, a release file whose heading is not its name or that
|
||||
# links relatively, or an index and its files that do not name each other both ways is red here.
|
||||
Write-Step 'docs-split-check'
|
||||
$splitTool = Join-Path $repo 'tools/docs-split-check.ps1'
|
||||
Invoke-Checked 'docs-split-check (self-test)' { & $splitTool -SelfTest }
|
||||
Invoke-Checked 'docs-split-check' { & $splitTool -RepoRoot $repo }
|
||||
|
||||
Write-Step 'changelog-check'
|
||||
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
|
||||
if (Test-Path $changelogTool) {
|
||||
@@ -465,6 +496,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.
|
||||
|
||||
@@ -135,9 +135,14 @@ logs\ui-*.log, agent-*.log, overlay-<pid>-*.log (native log flushed at session
|
||||
crashdumps\*.dmp
|
||||
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 (corrected 2026-10-04: never created — nothing writes games.cover_path)
|
||||
covers\game-<id>-<ms>.png the images users chose for their games (beta.23, D60) — ~~covers\*.jpg, never created~~;
|
||||
a store app's own artwork is shown from where that app keeps it, never copied here
|
||||
```
|
||||
|
||||
*(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.
|
||||
|
||||
+4
-2
@@ -7,10 +7,12 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
|
||||
### FR-1 Game library
|
||||
- FR-1.1 Add game by picking an `.exe`, or drag-dropping an exe/shortcut.
|
||||
- FR-1.2 Auto-import from Steam, GOG Galaxy, Epic, itch.io with a review checklist. **Import never enables hooking for anything.**
|
||||
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable.
|
||||
- FR-1.3 Editable metadata (name, cover, publisher, version, notes); auto-detected fields badged and overridable. *(The cover is built since beta.23, D60: the user's own image, else the Steam or GOG GALAXY app's artwork on this PC — `08_UI` §Games.)*
|
||||
- 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`)
|
||||
@@ -25,7 +27,7 @@ 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).
|
||||
|
||||
+136
-3
@@ -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`:
|
||||
@@ -432,6 +470,49 @@ F_app = Σ fgEvaluations (APPLICATION frames, counted at the
|
||||
> *(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.)*
|
||||
|
||||
> ### The mix — owner decision 2026-10-19 (D62)
|
||||
>
|
||||
> **The steady state names one state; a session can hold several.** A player who tries ×2, ×3 and ×4 in one session,
|
||||
> or whose NVIDIA App runs frame generation as *Dynamic*, got the longest state alone. Since beta.24 **every** state is
|
||||
> stored beside it: `Domain.Metrics.FgMix`, over the same five-second windows the steady state is read over (one cut,
|
||||
> `FgSlices.Cut`), from where `FgWindow` starts (the claimed suffix).
|
||||
>
|
||||
> **The rule.** Each window is classified by its own `presents ÷ tokens`: **active** (≥ 1.5, with ≥ 8 samples and
|
||||
> tokens), **no frame generation** (≤ 1.05, with ≥ 8 samples and tokens — and only where a counted `none` is allowed:
|
||||
> not on the shape `FgLadder.WithholdNone` withholds, §Frame Generation), else **not classified** (too few samples, no
|
||||
> tokens, the band between 1.05 and 1.5, or a withheld `none`). The active windows are grouped by repeating the steady
|
||||
> state's own extraction on what is left — the ±10 % cluster holding the most time, pooled, redrawn once — until no
|
||||
> cluster remains; a cluster under **10 s** returns its windows to *not classified*. A state's factor, Native and
|
||||
> Displayed are its own (Σ presents ÷ Σ tokens over its windows; each rate over its own seconds); a row's share is its
|
||||
> seconds over every window's, so the rows sum to 100 % and the longest state's share is `fg_steady_share` when the
|
||||
> session has one. Rows: the states by rising factor, then *no frame generation*, then *not classified*. **Never an
|
||||
> average across states** (CLAUDE.md rule 6), and ×5 and ×6 are 20 % apart and never pool.
|
||||
>
|
||||
> **When there is a mix.** Only where the session's frame generation was named (`Named` / `ActiveUnidentified`) and the
|
||||
> session-wide count either stood or was refused as `NonUniform` / `AmbiguousBand` — a change of state is exactly what a
|
||||
> mix describes. Every other refusal (not counted, unattributed, interleaved streams, either saturation, no
|
||||
> evaluations, too short, no batches) gets none — slicing does not make a refused record set trustworthy, the steady
|
||||
> state's rule — and so does a session in which no state formed.
|
||||
>
|
||||
> **Stored, never replayed.** `sessions.fg_mix` (schema 0020) holds the rows as JSON (`FgMixRecord`), written by the
|
||||
> recorder's aggregation beside the steady state. A session recorded before has none and is not rebuilt: `frame_blobs`
|
||||
> keep one Generated bit per frame and lose the presents only DXGI counted, so a mix rebuilt from them would be wrong on
|
||||
> exactly the titles that need one. The summary says so in one line for a session that counted frame generation and has
|
||||
> no mix.
|
||||
>
|
||||
> **What it shows, and what it cannot.** The summary's block (`08_UI` §Session summary): a bar of the shares, then a
|
||||
> row per state — `×4.0 frame generation · 35.33% · 70 → 282 FPS · 2m 05s` —, *No frame generation* with its one rate,
|
||||
> *Not classified* with its time; shown when the mix has two rows or more (one state throughout is the readout's own
|
||||
> number). Frame generation that changes faster than the five-second windows — the NVIDIA App's *Dynamic* mode can —
|
||||
> reads partly as *not classified* rather than as a factor nobody held. Above the rows, how frame generation was SET:
|
||||
> the NVIDIA App's Frame Generation Mode from the driver profile stored with the session (*Dynamic, up to ×6, target:
|
||||
> max refresh rate*; *Fixed ×4*), or that the profile sets none — the game's own menu chose
|
||||
> (`NvidiaOverrides.FrameGenerationContext`). That line is configuration, never one of the rows. The multiplier chosen
|
||||
> in a game's menu is not read — it reaches the runtime through `sl::DLSSGOptions`, the route `HANDOFF` §2b refused —
|
||||
> so the measured row is its evidence. The dynamic ceiling (`NGX_DLSSG_DYNAMIC_MULTI_FRAME_COUNT_MAX`) is decoded as
|
||||
> `NGX_DLSSG_MULTI_FRAME_COUNT` is (frames generated per rendered frame) and the automatic target as "max refresh
|
||||
> rate"; NVIDIA's header names neither, and owner-only item 20(a) checks both against the App.
|
||||
|
||||
`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)*
|
||||
@@ -512,8 +593,27 @@ carries the three shapes.
|
||||
> or memory, CLAUDE.md rule 4) and the driver's own per-process override report in full (`ngx_driver_words`: preset,
|
||||
> mode, ratio beside the masks). Both are shown as what the driver was set to do and what it says it did — "NVIDIA
|
||||
> profile …: DLSS override (preset K, Quality)" — and neither changes a measured value, a rung of the upscaler ladder or
|
||||
> the frame-generation factor: those stay what the hooks saw. A profile override the hooks contradict is two true
|
||||
> statements about different things, and the page shows both.
|
||||
> the frame-generation factor: those stay what the hooks saw. ~~A profile override the hooks contradict is two true
|
||||
> statements about different things, and the page shows both.~~ *(Struck 2026-10-19 for the quality mode only — the
|
||||
> amendment below; render size, ratio and the frame-generation factor are unchanged.)*
|
||||
>
|
||||
> **Amended 2026-10-19 (owner decision D63): the override is the standard for the quality MODE — when the driver
|
||||
> confirms it applied.** The owner, shown the note above: an NVIDIA App override is what the game ran at, so it is the
|
||||
> mode a session states. `Application.Recording.QualityResolver`, read at display time from what every session already
|
||||
> stores (`ngx_driver_words` since P2, `driver_profile` since beta.8 — so a session recorded before reads alike): when
|
||||
> DLSS super resolution ran (a hook named it, or the driver reports the feature created and evaluated) and the driver's
|
||||
> per-process report says the override applied (`ENABLED` with `PERF_MODE`, `SR_DLAA_MODE` or `SCALING_RATIO`), the mode
|
||||
> is the profile's `NGX_DLSS_SR_MODE` (documented: 0 Performance, 1 Balanced, 2 Quality, 4 DLAA, 5 Ultra Performance,
|
||||
> 6 a custom ratio with `NGX_DLSS_SR_OVERRIDE_SCALING_RATIO`), checked against the report's `performanceMode`; DLAA from
|
||||
> its bit. **The report is in NGX's own numbering, not the profile's** — measured on the owner's ledger: Silent Hill 2
|
||||
> (2026-10-13) under the App's *Ultra Performance* (profile 5) was reported as **3**, NGX's Ultra Performance, where the
|
||||
> profile's 3 is "the game's own" (Expedition 33's Quality was 2 in both). When the two disagree, or the report alone
|
||||
> carries a value that does not settle, the session reads as overridden with no mode — never the game's own value,
|
||||
> which the override replaced. Otherwise the mode the game passed to a hooked call (the Streamline byte); otherwise
|
||||
> none. Every surface says it the same way (`Formats.UpscalerOf`): *DLSS (driver-reported) Quality · NVIDIA App*,
|
||||
> *DLSS · NVIDIA App override*, *DLSS Quality*. The live card names what the report settles by itself
|
||||
> (`upscalerQualityOverride`, `07_IPC`). Nothing infers a mode from the render scale (`HANDOFF` §7a). Silent Hill 2's
|
||||
> own session reads no mode: its word lacks `CREATED | EVALUATE`, so no super resolution ran that the driver saw.
|
||||
|
||||
From the upscaler hooks we get, per frame:
|
||||
|
||||
@@ -576,7 +676,9 @@ Tier 2 has none of this: `upscaler = unknown`, ratio `N/A`.
|
||||
>
|
||||
> **What it may claim: the vendor and the feature, attributed to the driver.** What it may NOT claim,
|
||||
> each one measured: a quality (`performanceMode` / `renderPreset` are populated only under an
|
||||
> NVIDIA-app override and are then the OVERRIDE's values), a ratio or render size (`scalingRatio` is
|
||||
> NVIDIA-app override and are then the OVERRIDE's values — *which is why, since 2026-10-19 (D63), the
|
||||
> override's mode IS the session's mode where the report says it applied: §Upscaling's amendment above*),
|
||||
> a ratio or render size (`scalingRatio` is
|
||||
> 0 even under the override), a frame-generation multiplier (`FG_MODE` / `FG_MULTI_FRAME` stay clear
|
||||
> and `frameGenerationCount` is 0 at ×4 — it is the override target). **Corrected the same day, on the
|
||||
> loop's own readings:** the FG word DOES follow DLSS-G once the feature exists — `CREATED | EVALUATE`
|
||||
@@ -602,6 +704,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`).
|
||||
@@ -798,6 +906,27 @@ Per session over 1 Hz samples: `avg` (mean of non-null), `max` — and since bet
|
||||
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.
|
||||
|
||||
**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
|
||||
@@ -814,6 +943,10 @@ data are `N/A`, never 0.
|
||||
| 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 |
|
||||
|
||||
+36
-4
@@ -154,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
|
||||
@@ -180,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)~~ *(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`)*: `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` —
|
||||
@@ -208,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.
|
||||
>
|
||||
@@ -437,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`.
|
||||
|
||||
+141
-12
@@ -18,7 +18,7 @@ Derived in the Agent from the record stream; the mapping is in `03_METRICS`. Sum
|
||||
| Graphics API + swapchain format, buffer count, swap effect, flags | `CreateSwapChain*` / present hooks |
|
||||
| Present mode (flip / blt / independent flip) | swapchain desc + `presentFlags` + `syncInterval` |
|
||||
| HDR output | `SetColorSpace1` |
|
||||
| Upscaler identity + quality preset | NGX / Streamline / FFX / XeSS create+evaluate calls — **or, when no hook saw one, the NVIDIA driver's per-process NGX word, out of process and attributed (`03_METRICS` §Upscaling, the driver-reported rung, 2026-09-06): identity only, never the preset** |
|
||||
| Upscaler identity + quality preset | NGX / Streamline / FFX / XeSS create+evaluate calls — **or, when no hook saw one, the NVIDIA driver's per-process NGX word, out of process and attributed (`03_METRICS` §Upscaling, the driver-reported rung, 2026-09-06): identity only, never the game's preset** — since beta.24 (D63) an NVIDIA App override's mode, where that report says the override applied, is the session's quality mode, marked as the App's (`QualityResolver`) |
|
||||
| Render resolution vs output resolution (incl. mid-session changes) | upscaler parameter reads + `ResizeBuffers` |
|
||||
| Frame Generation mode + factor | NGX/SL/FFX FG feature evaluation, then cadence — **Tier 1 only**. ~~then (Tier 2 only) PresentMon `FrameType`~~ retired (§S31 row P2), and Tier 2 no longer produces frames to run cadence over either |
|
||||
| Ray Tracing active | AS builds + `DispatchRays` (both, to catch inline RayQuery) |
|
||||
@@ -143,12 +143,12 @@ 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~~ `N/A` *(corrected 2026-10-04: no extractor — `strings_regex` reads only the executable)* |
|
||||
@@ -246,6 +246,68 @@ 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 |
|
||||
@@ -256,6 +318,14 @@ wrote, where detection wrote it.
|
||||
| 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 |
|
||||
|
||||
> **The stores' artwork on this PC (beta.23, owner decision D60).** A game's page shows the cover and banner the Steam and
|
||||
> GOG GALAXY apps already keep — Steam's `appcache\librarycache\<appid>\` (files flat or in hash-named folders), GOG
|
||||
> GALAXY's `webcache\<user>\gog\<productId>\` — found for the store whose own records own the game's folder
|
||||
> (`StoreRecords.Owning`, as Play finds it). `Infrastructure.Art.SteamArtCache` and `GogArtCache` read them; nothing is
|
||||
> downloaded, so the *(opt-in)* online lookup in the publisher/version order below still does not exist. Epic, itch and
|
||||
> other stores keep no image files: their games show the image the user chooses, or none. The detail: `08_UI` §Games ›
|
||||
> Game detail, *The header's cover*.
|
||||
|
||||
**Auto-import (FR-1.2):** Steam via `libraryfolders.vdf` → all `appmanifest_*.acf` except `SteamLibrarySource.KnownTools` (2026-09-22: Steamworks Common Redistributables, Borderless Gaming, Wallpaper Engine, SteamVR, the Proton and Steam Linux Runtime entries, Blender — tools Steam's manifests do not distinguish from games, and which became library rows the watcher recorded); GOG via `HKLM\SOFTWARE\WOW6432Node\GOG.com\Games\*`; Epic via `Manifests\*.item`; itch by receipt scan. Import presents a review checklist; nothing is launched, nothing is hooked on import.
|
||||
|
||||
> **Built 2026-09-14 (P4 PR-4).** `Application.Import.LibraryImporter` over four `IStoreLibrarySource` adapters in
|
||||
@@ -293,7 +363,36 @@ 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".
|
||||
|
||||
**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".)*
|
||||
> **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~~ *(never built — FrameLedger makes no request to a store, `privacy.online_metadata` is reserved, and a game's artwork (beta.23, D60) is read from the store app's own files on the disk; struck 2026-10-14)*. *(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)
|
||||
|
||||
@@ -341,21 +440,51 @@ detection (`DetectionWrite`, `games.exe_machine` / `exe_file_version` / `exe_pro
|
||||
"FSR 2.2" number: the DLL's version is the SDK's, and no table of that mapping has been measured.
|
||||
|
||||
**Shipped is not loaded.** `library_versions` is what the game folder holds. What the process loaded is
|
||||
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL — the NVIDIA
|
||||
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name. The session
|
||||
summary prints the loaded list and names such a difference ("the game ships 3.7.10.0: another copy was loaded");
|
||||
it does not claim who loaded it.
|
||||
`sessions.runtime_modules` (Tier 1), and the two differ exactly when something else supplied the DLL. ~~— the NVIDIA
|
||||
App's DLSS override loads the driver's `nvngx_dlss.dll` from the driver store under the same name.~~ *(Struck
|
||||
2026-10-19: unmeasured, and the one measurement says otherwise — the owner's Silent Hill 2 session ran ×6 frame
|
||||
generation through the NVIDIA App's override and no module with a census name was loaded. Since beta.24 every module
|
||||
under `%ProgramData%\NVIDIA\NGX` is recorded whatever its name, with its folder class — §DLSS generation below —, and
|
||||
owner-only item 20(c) records what the override loads.)* The session summary prints the loaded list and names such a
|
||||
difference ("the game ships 3.7.10.0: another copy was loaded"); since beta.24 the DLSS line says where each DLSS
|
||||
library was loaded from (the game, the graphics driver, Windows) — by folder, never who put it there.
|
||||
|
||||
## DLSS generation — evidence-bound (beta.24, owner decision D64)
|
||||
|
||||
**What a session can say about which DLSS ran, and nothing more.** `Domain.Detection.DlssGeneration` names a
|
||||
generation only from something the session observed, strongest first; `App.Services.DlssText` prints it with what it
|
||||
rests on, every DLSS library's version and folder class (`sessions.runtime_module_sources`, schema 0021 — the class,
|
||||
never the path), and the super-resolution preset the driver reports applied:
|
||||
|
||||
| Evidence (strongest first) | Label | Where it comes from |
|
||||
|---|---|---|
|
||||
| Super-resolution render preset **L or M** that the NVIDIA driver reports applied, in a session where super resolution ran | DLSS 4.5 (2nd-gen transformer) | `ngx_driver_words` — the SR word's `PRESET` bit and `renderPreset`; presets L/M arrived with DLL 310.5.0 (NVIDIA's DLSS 4.5 release, driver 591.74) |
|
||||
| A DLSS Frame Generation state measured at **×5 or more** | DLSS 4.5 (Dynamic / 6× multi-frame generation) | `fg_mix` / `fg_factor` with `fg_mode = dlssg` |
|
||||
| Preset **J or K** reported applied | DLSS 4 (transformer) | as above |
|
||||
| A DLSS Frame Generation state at **×3 or ×4** | DLSS 4 (multi-frame generation) | as above |
|
||||
| `nvngx_dlss.dll` **2.x** | DLSS 2 | `runtime_modules` |
|
||||
| `nvngx_dlss.dll` **3.x**, or `nvngx_dlssg.dll` **1.x–3.x** | DLSS 3 | `runtime_modules` |
|
||||
| A **310.x** library alone, a CNN preset (A–F), ×2 | *no label* — the versions are shown | DLSS 4 and 4.5 ship the same major number; the preset is what names the model |
|
||||
| `nvngx_dlssnr.dll` loaded | "DLSS 5 runtime loaded" — never a generation of these features | the module name is community-sourced until owner-only item 20(d) sees it load |
|
||||
|
||||
Never a default preset inferred from a version: what a DLL "would" run by default is the game's and the driver's to
|
||||
decide. A preset the driver applied to a super resolution it never saw created and evaluated names the model of
|
||||
nothing and is not used (the owner's Silent Hill 2 session: preset L applied, no SR feature created — its label is
|
||||
the ×6.0 state's). **Sources:** NVAPI's `NV_NGX_DLSS_OVERRIDE_GET_STATE_PARAMS_V1` (the vendored
|
||||
`src/native/third_party/nvapi/nvapi.h`); presets L/M with DLL 310.5.0 — PCGH's DLSS 4.5 test and NVIDIA's driver
|
||||
591.74 release notes; DLSS 4.5's Dynamic MFG and 6× — NVIDIA's announcement (driver 595, RTX 50); DLSS 5 — NVIDIA's
|
||||
GTC 2026 announcement and its 2026-09-03 launch; `nvngx_dlssnr.dll` — community reports only.
|
||||
|
||||
## Anti-cheat pre-scan (static)
|
||||
|
||||
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.
|
||||
- **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
|
||||
|
||||
+75
-9
@@ -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. **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 ▸ Delete sessions too* (FR-1.4) deletes the `games` row, cascading to its sessions, segments, blobs and annotations), `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,10 +47,17 @@ 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,
|
||||
cover_path TEXT, notes TEXT, -- cover_path: written since beta.23 (D60) — the image the user chose, as
|
||||
-- covers\game-<id>-<unix ms>.png relative to the data folder (a PNG copy
|
||||
-- <= 1200 px); followed only when it is one of those names under covers\
|
||||
-- and never through a junction or a symbolic link (a viewer's copy could
|
||||
-- name a share); NULL = the store app's own artwork
|
||||
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
|
||||
-- (sessions.game_id is NOT NULL, ON DELETE CASCADE) but leaves the
|
||||
-- library; a later launch of the same exe restores it (removed_at = NULL)
|
||||
@@ -197,7 +204,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
|
||||
@@ -221,7 +230,8 @@ 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, and fsr since 2026-09-04 (FL_UPSCALER_FSR_UNVERSIONED; added 2026-10-04)
|
||||
@@ -295,6 +305,24 @@ CREATE TABLE sessions (
|
||||
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 0021 (2026-10-19, beta.24, D64): each loaded runtime module's folder class — 05_DETECTION §DLSS generation
|
||||
runtime_module_sources TEXT, -- {"nvngx_dlss.dll":"graphics_driver", …}: game | graphics_driver | windows; never a path
|
||||
|
||||
-- schema 0020 (2026-10-19, beta.24, D62): every frame-generation state the session held — 03_METRICS §The mix
|
||||
fg_mix TEXT, -- {"Rows":[{"Kind":"generated","Factor":4.0,"NativeFps":…,"DisplayedFps":…,
|
||||
-- "Seconds":…,"Share":…,"Windows":…}, …]}: states by rising factor, then
|
||||
-- "none", then "unclassified"; NULL with no state, and before 0020
|
||||
|
||||
-- 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 —
|
||||
@@ -362,7 +390,10 @@ CREATE TABLE sensor_blobs (
|
||||
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)
|
||||
-- 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.
|
||||
@@ -415,15 +446,20 @@ 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 |
|
||||
| `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) |
|
||||
| `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`)* |
|
||||
| `ui.game_art` | bool | `1` | | UI (beta.23, owner decision D60): a game's page shows its artwork — the image the user chose, else what the Steam or GOG GALAXY app keeps on this PC; nothing is downloaded. Settings ▸ Games (`08_UI` §Games) |
|
||||
| `ui.game_art_tint` | bool | `1` | | UI (beta.23, owner decision D61): the page's header band takes the artwork's colour, at the strongest opacity that keeps its text readable. Settings ▸ 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 |
|
||||
@@ -633,6 +669,36 @@ Sequential embedded SQL (`Migrations/0001_init.sql`, `0002_*.sql`, …), applied
|
||||
> `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.**
|
||||
|
||||
> **`0020_fg_mix.sql` (beta.24, 2026-10-19, owner decision D62) — every frame-generation state a session held.** One
|
||||
> TEXT column, ADD COLUMN only: `fg_mix`, `Application.Recording.FgMixRecord`'s JSON of `Domain.Metrics.FgMix` — each
|
||||
> state's pooled factor, its own Native and Displayed rates, its seconds, its share of the presenting time and its
|
||||
> five-second windows; then the time with no frame generation and the time no state claims (`03_METRICS` §The mix).
|
||||
> Written by the recorder's aggregation (`SessionAggregator.ApplyFg`, beside the steady state) for a hooked session whose
|
||||
> frame generation was named and whose count stood or was refused only as `non_uniform` / `ambiguous_band`; NULL
|
||||
> otherwise. A session before it has none and is **never rebuilt** from its `frame_blobs` (one Generated bit per frame,
|
||||
> the DXGI-counted presents lost). The `.partial` needs no change: a recovered session is aggregated from its records
|
||||
> like any other. `LatestVersion` is 20; `LedgerDatabaseTests.ScriptTwentyAddsTheFgMixColumnAndAnEarlierSessionHasNone`,
|
||||
> `SqliteSessionRepositoryTests.ASessionRoundTripsColumnForColumn`. **A beta.23 cannot open a ledger beta.24 migrated.**
|
||||
|
||||
> **`0021_runtime_module_sources.sql` (beta.24, 2026-10-19, owner decision D64) — where each loaded module lived.** One
|
||||
> TEXT column, ADD COLUMN only: `runtime_module_sources`, `{file: class}` beside `runtime_modules` — `game`,
|
||||
> `graphics_driver` (Windows' driver store or `%ProgramData%\NVIDIA`) or `windows`, from the path the module snapshot
|
||||
> read (`Application.Capture.RuntimeModuleSources`). The class is stored; **the path never is** (Privacy Policy 2.12).
|
||||
> Since the same release the snapshot also records every module under `%ProgramData%\NVIDIA\NGX` whatever its name.
|
||||
> Written by the recorder's aggregation (`SessionAggregator.ApplyWitnesses`); NULL before, and on a session recovered
|
||||
> from its crash file (which carries no module list). `LatestVersion` is 21;
|
||||
> `LedgerDatabaseTests.ScriptTwentyOneAddsTheModuleSourcesColumnAndAnEarlierSessionHasNone`, the repository round trip.
|
||||
|
||||
> **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
|
||||
|
||||
+14
-4
@@ -393,7 +393,7 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
|
||||
| `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.)* |
|
||||
@@ -404,11 +404,12 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
|
||||
| `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?, 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 |
|
||||
| `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). **`upscalerQualityOverride` added 2026-10-19 (beta.24, D63), optional:** the mode an NVIDIA App override set when the driver reports it applied in the target and DLSS super resolution ran there — `performance`, `balanced`, `quality`, `ultra_performance`, `ultra_quality`, `dlaa`, or `override` when the driver's report alone does not settle the mode (the profile is the stored session's); absent otherwise. **`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, guardReason? }` — **`guardReason` (beta.13, optional)** is the guard's own reason when it named a family; `BlockedService` / `BlockedDriver` is a finding on the PC, not in the game, and the notice says so (§S23-3); `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. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
|
||||
| `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 |
|
||||
@@ -481,6 +482,15 @@ message, and that message always re-scans.
|
||||
and SYSTEM) each carry an explicit descriptor. The instance lock and the elevation marker are only ever probed, and a
|
||||
probe that is refused reads as "held".
|
||||
- Treat the pipe as unreliable: library, history and charts must all work with the Agent offline. Only live status degrades.
|
||||
- **A request the Agent never answered is neither a failure nor a refusal (beta.22).** `IAgentRequests.RequestAsync` fails
|
||||
in one of four ways: `InvalidOperationException` — not connected, nothing was sent; `IpcRequestException` — the Agent
|
||||
answered `Error`; `TimeoutException`; and `IOException` — the connection closed before the answer, whatever closed it
|
||||
(`AgentConnection.AnsweredAsync` turns the `IpcFramingException` and `ObjectDisposedException` that `PipeClient` can fail a
|
||||
request in flight with into it, so a caller handles one). The last two mean *whether it was carried out is not known*
|
||||
(`AgentAnswers.IsUnanswered`): the caller says so in words (`Agent_Unanswered`) and reads what is stored again — deleting
|
||||
sessions, the hooking switch, the anti-cheat exception and Play alike. Until beta.22 deleting sessions caught no
|
||||
`IOException` (the App's crash dialog) and showed a timeout's own message, and the hooking switch and the exception
|
||||
showed `IOException` or `TimeoutException` as their notice.
|
||||
- SQLite is the source of truth for anything persisted; pipe events are refresh signals (except `SessionProgress`, which is live-only by design).
|
||||
- `CaptureRefused`, `SafetyUnhook` and (since 2026-09-25) `HookingTurnedOff` are **never** collapsed into a generic error toast — they get dedicated, explanatory UI (`08_UI` §Notifications).
|
||||
|
||||
|
||||
+285
-18
@@ -19,6 +19,22 @@ 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**
|
||||
@@ -31,12 +47,16 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
|
||||
> 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) — embedded in the
|
||||
> **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.
|
||||
> 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`
|
||||
@@ -46,7 +66,14 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
|
||||
> 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). Links
|
||||
> 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`:
|
||||
@@ -101,8 +128,12 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
|
||||
> Dashboard), Exit (a real exit through `ShellHost.Quit`, whatever minimize-to-tray says); a left click opens the
|
||||
> window. **Minimize to tray on close** hides the live window when `ui.minimize_to_tray` is on and a tray icon
|
||||
> exists (`WindowClosePolicy`); a language rebuild's old window is unaffected. **FR-3.8's balloon** — "Session
|
||||
> saved — <game> — click to view" — is raised only while the window is off screen; on screen, the Dashboard's
|
||||
> snackbar carries the same event (one event, exactly one channel), and its click opens the summary window.
|
||||
> saved — <game> — click to view" — is raised only while the window is off screen; on screen, ~~the Dashboard's~~ the
|
||||
> App's snackbar carries the same event (one event, exactly one channel), and its click opens the summary window.
|
||||
> *(Corrected 2026-10-14, beta.23: the snackbar's notice was raised by the Dashboard's view model, and it reached the
|
||||
> other pages only because no Dashboard ever went away — each visit made one, the root container kept every one, each
|
||||
> subscribed, so twenty visits were twenty notices for one session. It is `Services.SessionNotices` now, one
|
||||
> subscription for the App's life; the Dashboard listens only while it is on screen.)*
|
||||
> A safety event is never a balloon (`TrayViewModelTests` asserts it). Tools ▸ Agent status… and Tools ▸ Vulkan
|
||||
> layer registration… now navigate (Dashboard, Settings) instead of saying "not yet".
|
||||
|
||||
@@ -111,7 +142,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.
|
||||
|
||||
@@ -150,6 +181,26 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
|
||||
> 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.
|
||||
@@ -232,7 +283,17 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> 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). **The page reloads by itself** while it is on screen when a session ends (`SessionCompleted`) or an
|
||||
> `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
|
||||
@@ -242,12 +303,48 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> `…TheImportChecklistRendersWithTheExistingRowsShown`.
|
||||
>
|
||||
- **Game detail:**
|
||||
- Header: cover, name, publisher, version, platform, engine+version, API + Present Mode of last session, `FpsReadout` (lifetime avg), TriState chips, Edit button.
|
||||
- Header: cover *(built in beta.23, the note below)*, 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.
|
||||
|
||||
> **What opening the page and choosing a session cost, beta.23 (owner request 2026-10-14; `spike-notes` §21).** The
|
||||
> Sessions grid is bounded (`MaxHeight` 520, as Compare's list is): inside the page's own scroller it was measured with no
|
||||
> height limit and built every row — 100 sessions were 100 rows of 17 columns, 1.2–1.5 s to open the page; it builds the
|
||||
> rows on screen now, scrolls itself, and hands the wheel to the page at its ends
|
||||
> (`PagesLoadTests.TheSessionsGridBuildsTheRowsOnScreenAndHandsTheWheelOnAtItsEnd`). A session's series is read and
|
||||
> decoded on the thread pool — Microsoft.Data.Sqlite completes its asynchronous calls synchronously, so the decode of a
|
||||
> two-million-frame session ran on the UI thread whatever `ConfigureAwait` said — and what the charts derive from the whole
|
||||
> session (one sort of its frames where the Distribution tab did three, the histogram, the percentile curve, the presents
|
||||
> line) is worked out there once (`Charts.SeriesDigest`): choosing such a session froze the window 0.8–1.0 s, 17 ms now.
|
||||
> Whether the executable is on disk is asked off the UI thread, as the library page has asked since beta.19.
|
||||
|
||||
> **The header's cover, built in beta.23 (owner decisions D60/D61, request 2026-10-14) — never before: the line above said
|
||||
> "cover" from the first draft and nothing drew one.** The image the user chose (Edit… ▸ *Choose image…*, a PNG copy ≤ 1200 px
|
||||
> in the data folder's `covers\game-<id>-<unix ms>.png`, `games.cover_path` relative to the data folder; *Use the store's
|
||||
> image* drops it), else what the app of the store that installed the game keeps on this PC — Steam's
|
||||
> `appcache\librarycache\<appid>\` (its files flat or in hash-named folders: `library_600x900.jpg` / `library_capsule.jpg`,
|
||||
> `library_hero.jpg`, `header.jpg` / `library_header.jpg`) and GOG GALAXY's `webcache\<user>\gog\<productId>\`
|
||||
> (`*_glx_vertical_cover.webp`, `*_glx_bg_top_padding_*.webp`). Which store installed the game is asked of the stores' own
|
||||
> records, as Play asks (`StoreRecords.Owning`, D59) — Steam's and GOG's only, cached two minutes; nothing is downloaded
|
||||
> (`privacy.online_metadata` stays reserved). The page: a band (`ArtBand`, rounded) holding the banner (`ui:Image`, as tall
|
||||
> as its proportions make it, ≤ 240, fading into the band through an alpha mask set in code) above the usual header with the
|
||||
> cover beside the name (120×180, or 230×107 for a landscape header); a game with no artwork shows no band. No text is
|
||||
> drawn on a picture. **The band's colour** (`Controls.ArtTint`, D61): the cover's — else the banner's — dominant colour (`Services.ColorMath`: a
|
||||
> hue histogram of a 48-px copy, vivid pixels weighted, a grey picture none) over the card's fill at the strongest opacity
|
||||
> — ≤ 30 % on a dark theme, ≤ 22 % on a light one — at which primary and secondary text keep 4.5:1, tertiary 3:1, and the
|
||||
> pills' and the warning's text 4.5:1 on their fills; recomputed through a resource reference when the theme changes;
|
||||
> untinted with the option off, a grey picture or high contrast. Everything is read and decoded on the thread pool
|
||||
> (`Services.GameArt`; the twelve newest images kept); the text shows first and the picture when ready. A chosen image's
|
||||
> path is followed only when it is one of these names in the data folder's `covers`, and never through a junction or a
|
||||
> symbolic link — a viewer's copy (D52) could name a share, or hold a link to one. Settings ▸ Games: *Show game artwork* (`ui.game_art`) and *Colour the game page from its artwork*
|
||||
> (`ui.game_art_tint`), both on. Tests: `GameArtTests`, `CoverStoreTests`, `ColorMathTests` (the hardest colours in both
|
||||
> themes against the tests' own WCAG), `EditGameViewModelTests`, `PagesLoadTests.EveryTextIsReadableInBothThemes` (the
|
||||
> surfaces' game page has artwork), `…TheArtworkBandFollowsAThemeSwitch` and `…TheGamePagesArtworkIsDrawn` with
|
||||
> `AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate` (the cover once took its place and drew nothing, a
|
||||
> `ui:Image` style not based on WPF UI's; caught in a render before it shipped). The library's cards still have no image.
|
||||
|
||||
> **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~~ no sparkline was built — corrected 2026-10-04); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's
|
||||
@@ -259,7 +356,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
|
||||
@@ -334,6 +434,14 @@ 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".~~ (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).
|
||||
@@ -399,7 +507,14 @@ All screens are `Page`s registered with the navigation page provider and navigat
|
||||
> 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.
|
||||
> 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
|
||||
@@ -428,9 +543,78 @@ 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).
|
||||
|
||||
> **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.24 (D64): the DLSS line.** Under the header's library line, the summary says which DLSS ran (`DlssText.Line`): a
|
||||
> generation only where the session shows one, with what it rests on — *DLSS 4.5 (preset L)*, *DLSS 4.5 (a ×6.0
|
||||
> frame-generation state)*, *DLSS 3 (library 3.7.10)* — else *DLSS*; then each DLSS library with its version and where
|
||||
> it was loaded from (*Super Resolution 310.5.0, from the graphics driver, preset L (2nd-gen transformer model)*), then
|
||||
> *DLSS 5 runtime loaded* when it was. The game page's *Last session measured* repeats the label; the CSV export gains
|
||||
> `# dlss:`. `DlssTextTests`.
|
||||
|
||||
> **beta.24 (D63): the quality mode, on every surface alike.** The summary's header line, a Sessions-tab row, the game
|
||||
> page's *Last session measured* and the live card name the upscaler through one entry point (`Formats.UpscalerOf`):
|
||||
> the NVIDIA App's override where the driver reports it applied — *DLSS (driver-reported) Quality · NVIDIA App*, or
|
||||
> *DLSS · NVIDIA App override* when its mode is not settled —, else the mode the game passed (*DLSS Quality*), else the
|
||||
> name alone. Mode names come from the resources (`Nv_Mode_*`). Chart segments stay the hooks' (a segment carries no
|
||||
> driver report). The driver line reads the report's mode in NGX's numbering (it read it through the profile's table
|
||||
> until beta.24). CSV export: `# quality_mode:` (`quality (nvidia_app)`, `stored 9 (game)`, `N/A`).
|
||||
|
||||
> **beta.24 (D62): the frame-generation mix.** Under the stat cards, **Frame generation in this session** — shown when
|
||||
> the session stored a mix of two rows or more (`sessions.fg_mix`, `03_METRICS` §The mix): a line saying how frame
|
||||
> generation was set (the NVIDIA App's Frame Generation Mode from the stored driver profile — *Set in the NVIDIA App:
|
||||
> Dynamic, up to ×6, target: max refresh rate*, *Fixed ×4* — or *Set in the game — no NVIDIA App frame-generation
|
||||
> override*; a value the driver ships in its own profile is said as the driver's; no line where no NVIDIA profile was
|
||||
> read), a bar of the shares (`Controls/FgMixBar`: drawn from code in the chart palette — a state by its multiplier,
|
||||
> `Chart_MixNone` and `Chart_MixUnclassified` for the other two — following a theme switch through
|
||||
> `ApplicationBackgroundColor` as `ArtTint` does; announced by its `AutomationProperties.Name`), and a table: a colour
|
||||
> swatch, the row (*×4.0 frame generation*, *No frame generation*, *Not classified*), its share to two decimals
|
||||
> (`<0.01%` for a sliver, never 0), its own *Native → Displayed* (one rate with no frame generation, none where no state
|
||||
> was read), and its time. A sentence explains *Not classified* when the table has it. A session that counted frame
|
||||
> generation and stored no mix — recorded before beta.24, or no state of 10 s — says so in one tertiary line. The CSV
|
||||
> export gains `# fg_mix:`; the JSON carries the column in its aggregates. Tests: `FgMixPresentationTests`,
|
||||
> `NvidiaOverridesTests`, `SessionSummaryViewModelTests`, `SessionExporterTests`, and the summary surface in
|
||||
> `PagesLoadTests` carries a mix so the block is read in both themes and through a switch.
|
||||
|
||||
> **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
|
||||
@@ -535,6 +719,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).
|
||||
@@ -552,18 +743,43 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
|
||||
> `PagesLoadTests`.
|
||||
|
||||
### Settings
|
||||
> **beta.23 (owner decisions D60/D61).** The Games section has, under the Play button, **Show game artwork**
|
||||
> (`ui.game_art`, on) and **Colour the game page from its artwork** (`ui.game_art_tint`, on; disabled while the first is
|
||||
> off) — the game page's artwork and its band's colour (§Games › Game detail, *The header's cover*). Neither downloads
|
||||
> anything; the App reads both at each page load, the Agent neither.
|
||||
>
|
||||
> **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~~ *(removed in beta.12 — nothing read it; corrected 2026-10-04)*. 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.~~ *(Not shown since 2026-09-16: no code makes the request and `privacy.online_metadata` stays reserved — the built Settings below; struck 2026-10-14.)* 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`
|
||||
@@ -579,7 +795,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,
|
||||
@@ -599,7 +816,7 @@ Agent section: elevation state with a plain explanation of what elevation *optio
|
||||
> `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
|
||||
@@ -676,6 +893,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
|
||||
|
||||
@@ -693,7 +916,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),
|
||||
@@ -714,8 +938,12 @@ which is why the handler is ours.
|
||||
|
||||
Colours come from the WPF UI theme dictionaries and nothing else, so contrast is the Fluent themes' — both of which
|
||||
meet it — and cannot be broken locally: `AccessibilityTests.NoXamlHardCodesAColour` fails on any `#RRGGBB` or named
|
||||
colour in the App's XAML. The chart palette is the one deliberate exception (`16_WPFUI_SYNTAX` §ScottPlot: one
|
||||
palette per theme, chosen with the theme).
|
||||
colour in the App's XAML. The chart palette is ~~the one~~ a deliberate exception (`16_WPFUI_SYNTAX` §ScottPlot: one
|
||||
palette per theme, chosen with the theme). *(Corrected 2026-10-14, beta.23: the game page's artwork band is the second —
|
||||
a colour worked out at run time from the artwork and the theme's own text and fill colours, at the strongest opacity at
|
||||
which every text on it keeps 4.5:1 (tertiary 3:1), so it is held by construction rather than by the theme;
|
||||
`ColorMathTests` checks the hardest colours in both themes against the tests' own WCAG, and `PagesLoadTests` measures the
|
||||
rendered band. Its banner's fade is an alpha mask set in code, no colour at all.)*
|
||||
|
||||
> **"Cannot be broken locally" had a hole, closed 2026-09-16.** `ui:Badge Appearance="Info"` — the Games card's
|
||||
> "Hooking on/off" and the edit dialog's "Detected" — paints its background with WPF UI's `PaletteLightBlueBrush`, a
|
||||
@@ -743,6 +971,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
|
||||
|
||||
|
||||
@@ -17,6 +17,12 @@ Languages: **en** (neutral/default) · **vi** · **ja**. Same `.resx` pattern as
|
||||
- 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`.
|
||||
**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
|
||||
|
||||
@@ -3,6 +3,8 @@
|
||||
## 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`).~~
|
||||
- Template: `[{Timestamp:HH:mm:ss.fff} {Level:u3}] {SourceContext} {Message:lj} {Properties:j}{NewLine}{Exception}`.
|
||||
|
||||
+54
-2
@@ -1,11 +1,14 @@
|
||||
# 11 — Updater
|
||||
|
||||
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.)*
|
||||
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. ~~(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.
|
||||
@@ -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.~~ *(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.)*
|
||||
- ~~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
|
||||
@@ -106,6 +114,50 @@ flow, and the tests run the flow over a fake client because nothing here may tou
|
||||
longer claims the updater provides one.
|
||||
- ~~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~~ *(corrected 2026-10-04: the feed has existed since
|
||||
|
||||
+55
-6
@@ -44,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`~~ 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.
|
||||
**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
|
||||
|
||||
@@ -75,6 +75,16 @@ implemented. What exists: `FrameLedger.exe` starts `FrameLedger.Agent.exe --serv
|
||||
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). A copy of the database alone has no `covers\`: the games whose image the user
|
||||
chose show the store's artwork instead (beta.23), and choosing one in the viewer writes into the copy's own `covers\`. 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`:**
|
||||
|
||||
- **msys2 / MinGW on `PATH` breaks the native build.** `vcvars64` *prepends* to
|
||||
@@ -170,6 +180,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.
|
||||
@@ -179,7 +212,8 @@ assumed to.
|
||||
```
|
||||
cmake --build --preset x64-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 -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
|
||||
```
|
||||
|
||||
@@ -188,7 +222,9 @@ vpk pack --packId FrameLedger.App --packVersion {ver} --packDir out/app --mainEx
|
||||
> take `-p:Version=<tag>` (§Version). No `--icon`: `assets/icon.ico` does not exist, and this line named it
|
||||
> 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`.
|
||||
> (`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
|
||||
@@ -223,7 +259,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
|
||||
|
||||
@@ -237,6 +273,16 @@ substitutes it with ~~the tag date~~ the run's UTC date (corrected 2026-10-04) w
|
||||
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`:
|
||||
@@ -255,7 +301,7 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
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
|
||||
@@ -263,8 +309,11 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
|
||||
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)
|
||||
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), and since beta.24 three over a temporary tree: a version with its own `docs/changelog/<version>.md` is read from it, one without from `CHANGELOG.md`, a prefix of a file name is not that file. 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)
|
||||
14d. **`tools/docs-split-check.ps1 -SelfTest`, then live** (beta.24, owner decision D66) — `CHANGELOG.md` holds no released section beside `[Unreleased]`; each `docs/changelog/<version>.md` holds one `## ` heading, its own `## [<version>] - date`, and no relative link (the App renders release notes as `CHANGELOG.md`); `CHANGELOG.md` and the files under `docs/changelog/`, and `docs/HANDOFF.md` and the files under `docs/handoff/` — and since PR-5 `docs/20_OPEN_QUESTIONS.md` and `docs/open-questions/`, `docs/spike-notes.md` and `docs/spike-notes/` — name each other in both directions. Eleven self-test cases, both directions
|
||||
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
|
||||
|
||||
+112
-4
@@ -7,7 +7,7 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
## Workflows (`.github/workflows/`)
|
||||
|
||||
### `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.
|
||||
- `runs-on: windows-latest`, .NET SDK pinned by `global.json` via `actions/setup-dotnet`, MSVC via `ilammy/msvc-dev-cmd` (pinned to its v1.13.0 commit since beta.24 — the one third-party action, SonarCloud `githubactions:S7637`; Dependabot moves the pin), 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.
|
||||
- **The hosted runner refuses guard scans intermittently — THREE failures in eight gate runs, measured
|
||||
@@ -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
|
||||
@@ -127,6 +138,10 @@ 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
|
||||
@@ -135,7 +150,15 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- **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
|
||||
@@ -176,6 +199,90 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
|
||||
- **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.
|
||||
|
||||
## SonarCloud — Automatic Analysis, no workflow (beta.24, owner decision D67)
|
||||
|
||||
The project `poli0981_frameledger` is analysed by SonarCloud's GitHub app in **Automatic Analysis** mode: on every
|
||||
push to `main` and on every pull request, with no workflow in this repository and no logs published. Its check on a
|
||||
pull request (*SonarCloud Code Analysis*) is advisory — it is not a required status.
|
||||
|
||||
**What it reads is set by `.sonarcloud.properties`** at the root, the only file Automatic Analysis reads, from the
|
||||
default branch. It excludes what is not FrameLedger's code or not code: the vendored SDK headers under
|
||||
`src/native/third_party/` (51 headers, 66 thousand lines — before this file they were 41.7 thousand of the project's
|
||||
94 thousand counted lines, classed C), the generated `Strings.Designer.cs` and `dxr_raygen_dxil.h`, the vendor stubs
|
||||
(fixtures that carry the vendors' export names on purpose), `tests/fixtures/`, the licence texts, the generated
|
||||
`docs/vendor-exports.json` and the SQLite migrations (a SQL analyser reads them as another dialect). It reports C++
|
||||
against C++20, the standard `src/native/CMakeLists.txt` sets. `build/`, `bin/`, `obj/` and `presentmon/` are
|
||||
git-ignored and never reach it.
|
||||
|
||||
**What it cannot do.** `sonar.issue.ignore.*` is not read by Automatic Analysis, so a rule this project breaks by
|
||||
design is recorded here and marked in SonarCloud's own UI — by the owner, who holds the account. A CI-based scan (the
|
||||
only way to import coverage or analyse one build variant of the C++) would mean turning Automatic Analysis off, a
|
||||
`SONAR_TOKEN` secret, OpenCover output beside today's Cobertura and a full-depth checkout; it is not done.
|
||||
|
||||
**The triage of 2026-10-19** — the analysis of `main` at `372389c` (2026-09-28; nothing had been analysed since),
|
||||
341 open issues, none resolved. Rules broken by design are *Accept*ed and false positives marked as such, each with
|
||||
the comment below; the rest are fixed in the same train (beta.24 PR-2).
|
||||
|
||||
| Rule | Issues | Verdict | Comment for the UI |
|
||||
|---|---|---|---|
|
||||
| `cpp:S8417` atomics should be sequentially consistent | 225 | **Accept** — by design | The SPSC ring and the hook counters use explicit acquire/release and relaxed orders on purpose (`07_IPC`); sequential consistency would add fences on the per-present path. |
|
||||
| `csharpsquid:S6640` unsafe code blocks | 31 | **Accept** — by design | Interop with the native layer and the shared-memory mirror, confined to `Infrastructure` and `Shared` (CLAUDE.md: the native layer is reachable only through `Infrastructure`). |
|
||||
| `cpp:S6232` union type-punning | 24 | **False positive** | `LARGE_INTEGER.QuadPart` is how the Windows API returns the value. |
|
||||
| `cpp:S5813` bounds when computing string length | 19 | **Accept** for the 17 below; the 2 with a buffer bound at hand were bounded (beta.24 PR-2: `FlGuardRulesFilePath` reads `wcsnlen(out, cap)`, the NVAPI bridge `strnlen` over the driver's `NvAPI_ShortString`) | Every string measured is NUL-terminated by construction — see the list under this table. |
|
||||
| `csharpsquid:S2077` dynamic SQL | 3 | **False positive** | A `PRAGMA` argument cannot be bound; the values are an `int` and closed sets of constants (`wal_checkpoint` mode, the tri-state column), never user text. |
|
||||
| `cpp:S935` `FlGetBuildId` returns no value | 1 | **False positive** | `FL_BUILD_ID` is defined by the build (`12_BUILD` §Version); the analysis compiles without it. |
|
||||
| `cpp:S3519` out-of-bounds `memcpy` | 1 | **False positive** | `fl_patch_check.h` reads the prologue of a function this DLL hooked, under SEH, by design (`17_HOOK_ENGINE` §Unhooking). |
|
||||
| `cpp:S836` garbage value returned | 1 | **False positive** | `hook-harness`'s `VtableOf` reads the vtable of a COM object it created itself. |
|
||||
| `csharpsquid:S3869` `DangerousGetHandle` | 1 | **Accept** | `ParentDump` passes the dump file's handle to `MiniDumpWriteDump` inside the `using` that owns the stream, on the same thread, so it cannot be released during the call; CsWin32 generates no `SafeHandle` overload here (`NativeMethods.json`: `useSafeHandles: false`). |
|
||||
| `cpp:S1669`, `cpp:S6191`, `csharpsquid:S4036`, `githubactions:S7637`, `csharpsquid:S2190`, `S3427`, `S8949` | 35 | **Fixed** in beta.24 PR-2 — 5 of the 23 `S1669` were in the vendored Vulkan headers and leave with the exclusions | — |
|
||||
|
||||
**`cpp:S5813`, the 17 accepted, and why each string is terminated** (lines as of beta.24):
|
||||
|
||||
- `fl_ac_rules.cpp` — `IStartsWith`/`IContains` (`:38`, `:43-44`) and `TokenIs` (`:74`) measure rule fragments and
|
||||
literals the guard itself holds; `:151` and `:288` measure a value `CopyToken` has just written, which refuses a token
|
||||
that does not fit and always writes the terminator; `CopyLiteral` (`:176`) measures a compiled literal; `:834`
|
||||
measures `SHGetKnownFolderPath`'s answer, terminated by the API.
|
||||
- `fl_guard.cpp:109` — the guard's own DLL path, built and terminated by its caller before injection.
|
||||
- `fl_guard_sources.cpp` — `:345` measures the executable's path the guard read itself and walked to its terminator
|
||||
in the loop just above; `:753` the install root the guard resolved from it; `VdfValue` (`:582`) measures the
|
||||
compiled keys its callers pass (`"installdir"`, `"appid"`), and `AllDigits` (`:617`) a value `VdfValue` copied with
|
||||
its own bound.
|
||||
- `fl_prescan.cpp` — `IsKernelDriverName` (`:40`) measures a name the directory walk handed over terminated;
|
||||
`SegmentIs` (`:181`) a literal; `:337` the executable's folder the pre-scan built itself.
|
||||
- `layer.cpp:99` (the Vulkan layer) — a leaf of `GetModuleFileNameA`'s result, which the line above has already
|
||||
checked is shorter than `MAX_PATH`, so it is terminated.
|
||||
- `fl-baseline-probe/main.cpp:55` — a literal (a developer probe, not shipped).
|
||||
|
||||
**The owner's steps** after the next analysis of `main`: for each rule above, open
|
||||
`https://sonarcloud.io/project/issues?id=poli0981_frameledger&resolved=false&rules=<rule>`, select all, *Bulk change*,
|
||||
choose *Accept* or *False positive* and paste the comment. Optionally, *Administration ▸ General Settings ▸ Analysis
|
||||
Scope ▸ Ignore issues on multiple criteria*: `cpp:S8417` and `cpp:S6232` on `src/native/**/*`, `csharpsquid:S6640`
|
||||
on `src/FrameLedger.Infrastructure/**/*` and `src/FrameLedger.Shared/**/*`, so new instances of the by-design rules
|
||||
stop reappearing on pull requests.
|
||||
|
||||
## Dependabot (`.github/dependabot.yml`)
|
||||
|
||||
```yaml
|
||||
@@ -195,7 +302,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) *(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).
|
||||
- Release: in ONE commit, bump `VERSION` and move the `[Unreleased]` entries of `CHANGELOG.md` under `## [X.Y.Z] - date` (Keep a Changelog format) *(since beta.24, D66: into their own file, `docs/changelog/X.Y.Z.md`, which opens with that heading, plus its row in `CHANGELOG.md`'s Releases table — `release-notes.ps1` reads the version's own file)* → 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 +314,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)
|
||||
@@ -219,4 +326,5 @@ Central package management makes Dependabot PRs single-file diffs.
|
||||
- [ ] `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)
|
||||
- [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)
|
||||
+65
-1
@@ -16,6 +16,13 @@ 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).
|
||||
@@ -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* *(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)* |
|
||||
| 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
|
||||
|
||||
|
||||
+1
-1
@@ -328,7 +328,7 @@ WPF UI shell (`16_WPFUI_SYNTAX`), library, per-game hooking consent flow, Dashbo
|
||||
~~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** — 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.
|
||||
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~~ a pre-release at each step since, listed in the CHANGELOG *(corrected 2026-10-14: the count went stale at the next release)* — (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.
|
||||
|
||||
|
||||
+89
-4
@@ -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,14 @@ 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.
|
||||
- **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.
|
||||
- Second exception (beta.23, D61): the game page's artwork band, `Controls/ArtTint` — a colour worked out in code from the
|
||||
artwork and the theme's own text and fill colours, the strongest tint at which every text on it still reads (4.5:1,
|
||||
tertiary 3:1). It follows a theme switch through a **resource reference on the band** (`SetResourceReference` on a
|
||||
private attached property bound to `ApplicationBackgroundColor`), not through `ApplicationThemeManager.Changed`, which
|
||||
only `ApplicationThemeManager.Apply` raises — a page made and switched in the tests' harness would never hear it.
|
||||
|
||||
## FlowDocument (rendered documents, beta.12)
|
||||
|
||||
@@ -227,9 +234,87 @@ 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.
|
||||
- [ ] **A style of the App's for a WPF UI control replaces the style that holds its template** (beta.23). WPF UI 4.3.0 gives
|
||||
its controls their templates in its own styles (`DefaultImageStyle`, …), applied only to a control with no style of its
|
||||
own: a local `<Style TargetType="ui:Image">` with no `BasedOn` leaves the control with no template, and it takes its
|
||||
place and draws nothing — the game page's cover was an empty space beside the name while the banner above it, with no
|
||||
style, drew (caught in a render before it shipped). Base it on WPF UI's (`BasedOn="{StaticResource DefaultImageStyle}"`).
|
||||
`AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate`, `PagesLoadTests.TheGamePagesArtworkIsDrawn`.
|
||||
- [ ] **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.
|
||||
- [ ] **Microsoft.Data.Sqlite completes its "async" calls synchronously** (measured 2026-10-14, beta.23): a
|
||||
`ConfigureAwait(false)` after a ledger read does not leave the thread that asked, so a view model's load, a session's
|
||||
decode, a sort over its frames all ran on the UI thread. Work that must not run there goes in `Task.Run` —
|
||||
`Charts.SessionSeriesLoader`, the game page's executable check (`spike-notes` §21).
|
||||
- [ ] **A transient page's view model is never `IDisposable`** (beta.23). Pages and their view models are transient, and
|
||||
the root container keeps every transient disposable it makes until the App exits: every Dashboard and Logs page ever
|
||||
opened stayed in memory, and each Dashboard stayed subscribed to the Agent — at a session's end every one reloaded its
|
||||
lists on the UI thread and raised its own notice. Listen on Loaded and stop on Unloaded (`Attach`/`Detach`, as Games,
|
||||
the game page and the Dashboard do); `DashboardViewModelTests.ADashboardOffScreenHearsNothing…`.
|
||||
- [ ] **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.
|
||||
+14
-2
@@ -705,11 +705,23 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
|
||||
> `__func__` — never from a hook body. Codes: `RING_CREATED`, `PRESENT_HOOKS`, `HOOK_INSTALLED` (one per
|
||||
> patch, with the target address), `SYMBOL_MISSING` (once per pair, and only when the module IS mapped),
|
||||
> `FAULT`, `STOP` (the reason), `UNHOOK_RESTORED` / `UNHOOK_DECLINED` (one per patch), `LOADER_DETOUR`,
|
||||
> `SUPERVISION_LOST`. **Three flush points, none on a present path:** the end of `InitThread` (so the
|
||||
> `SUPERVISION_LOST`, and since beta.24 `STOP_FLUSHED` (the last line after a stop: `a=1` when the stop had finished
|
||||
> writing). **Three flush points, none on a present path:** the end of `InitThread` (so the
|
||||
> file exists from the start of the session and a crash mid-session still leaves it), the watchdog when
|
||||
> `FlControlBlock.logFlushRequested` changes (a counter the Agent bumps at session end; nothing clears it),
|
||||
> and the watchdog on its way out after any stop. Appended, never recreated; events overwritten before a
|
||||
> flush are counted in a `#` line. Path: `%LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-<yyyymmdd-hhmmss>.log`,
|
||||
> flush are counted in a `#` line.
|
||||
>
|
||||
> **The stop and the last flush, beta.24 (`fl_guard`'s native-log case, red under load since beta.9).** A stop sets
|
||||
> `g_observing` to 0 first and writes its `STOP` / `UNHOOK_*` lines after, and the watchdog's loop returns the moment
|
||||
> it reads 0. When the stop ran on a presenting thread — `MayObserve`'s one-frame safety stop — the watchdog's one
|
||||
> final flush could run while that thread was still writing, and the lines after it (the kernelbase loader detour is
|
||||
> the last patch) reached the ring after the last flush ever made. The stop now says when its last line is in, and
|
||||
> wakes the watchdog; the final flush waits for that, bounded at 2 s, then writes `STOP_FLUSHED`. And each slot has a
|
||||
> commit word written after its fields: `LogNote` claims a slot with one `fetch_add` and fills it afterwards, so a
|
||||
> flush on another thread could print a slot still being filled. A flush now prints only slots whose writer has
|
||||
> finished — an ordinary flush stops at the first that is not, for the next one; the final flush names it in a `#`
|
||||
> line. Nothing on a present path changed. Path: `%LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-<yyyymmdd-hhmmss>.log`,
|
||||
> resolved by `SHGetKnownFolderPath` (§S21's rule, not the environment). No allocation: static ring,
|
||||
> static 64 KiB format buffer, static path. The CaptureHost prints the file and its `FAULT` / `STOP` /
|
||||
> `UNHOOK_*` / `SYMBOL_MISSING` / `SUPERVISION_LOST` lines at the end of every session
|
||||
|
||||
@@ -237,7 +237,7 @@ Still resolve **entry points defensively at runtime**: `nvapi64.dll` may be abse
|
||||
| Memory | `NvAPI_GPU_GetMemoryInfoEx` — **not `NvAPI_GPU_GetMemoryInfo`**, which this table named until 2026-08-05. The vendored headers mark it `__nvapi_deprecated_function` ("deprecated in release 520"), so under `/W4 /WX` a call to it fails the native build. **Neither is called (2026-09-10):** the vendored `nvapi.h` (`cd6918f6`) does not declare `GetMemoryInfoEx` at all — the deprecation message names a function the same header set does not ship — so the bridge's `vram` field is **reserved**, its bit is never set, and VRAM stays L1's PDH adapter counter. Taking a newer header set is the way to change that, not a call to the deprecated one |
|
||||
| **Throttle reasons** | `NvAPI_GPU_GetPerfDecreaseInfo` — not available from L1 or L2. **Bridge (2026-09-10):** the raw reason mask, and 0 is a measurement (no reason), not a clear bit |
|
||||
| Driver version | `NvAPI_SYS_GetDriverAndBranchVersion` — **bridge (2026-09-10):** `FlNvDriverVersion`, surfaced as `616.64 (r616_41)` |
|
||||
| **NGX per-process state** | `NvAPI_NGX_GetNGXOverrideState` (R570+) — the driver's feedback word per DLSS feature for a PID, read OUT OF PROCESS by `fl-probe-nvapi --ngx-state` and, since 2026-09-06, by the capture host beside each module snapshot — **in-process through the bridge since 2026-09-10** (`NvapiNgxStateProbe`; the spawn is retired and the words, the merge and the printed block are unchanged). Measured: the SR word's `CREATED \| EVALUATE` is set without an NVIDIA-app override; the FG word follows DLSS-G once created (`CREATED \| EVALUATE` at ×4, corrected the same day — the first reading was blind because it was early), the multiplier bits stay clear; `scalingRatio` is 0 even under an override. Identity only, SR and FG (`03_METRICS` §Upscaling) |
|
||||
| **NGX per-process state** | `NvAPI_NGX_GetNGXOverrideState` (R570+) — the driver's feedback word per DLSS feature for a PID, read OUT OF PROCESS by `fl-probe-nvapi --ngx-state` and, since 2026-09-06, by the capture host beside each module snapshot — **in-process through the bridge since 2026-09-10** (`NvapiNgxStateProbe`; the spawn is retired and the words, the merge and the printed block are unchanged). Measured: the SR word's `CREATED \| EVALUATE` is set without an NVIDIA-app override; the FG word follows DLSS-G once created (`CREATED \| EVALUATE` at ×4, corrected the same day — the first reading was blind because it was early), the multiplier bits stay clear; `scalingRatio` is 0 even under an override. Identity only, SR and FG (`03_METRICS` §Upscaling) — and, since beta.24 (D63), the mode an NVIDIA App override set where the word says it applied; its `performanceMode` is in NGX's own numbering (Silent Hill 2, 2026-10-13: the App's Ultra Performance, profile value 5, reported as 3) |
|
||||
| **Reflex / PC latency** | `NvAPI_D3D_GetLatency` → per-frame sim/render/present/driver/GPU timestamps; hooking `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` in the Overlay tells us the game enabled Reflex (`17_HOOK_ENGINE`) |
|
||||
|
||||
Reflex latency is the single strongest reason L3 exists — it is genuinely unavailable anywhere else.
|
||||
|
||||
@@ -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
|
||||
@@ -237,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
|
||||
@@ -307,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
|
||||
@@ -352,6 +387,21 @@ 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`
|
||||
@@ -363,9 +413,11 @@ Implemented in `FrameLedger.Injector` and reached from managed code through a th
|
||||
> 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.
|
||||
@@ -469,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).
|
||||
@@ -511,7 +566,7 @@ says so, including that a ban can arrive days later and that FrameLedger cannot
|
||||
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`
|
||||
@@ -693,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 |
|
||||
@@ -836,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`,
|
||||
@@ -1078,6 +1145,11 @@ outlives a rules change, a game update and *Change executable*; §What a finding
|
||||
## 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~~ *(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)*.
|
||||
|
||||
|
||||
+46
-2499
File diff suppressed because it is too large.
Load diff
+224
-2133
File diff suppressed because it is too large.
Load diff
@@ -9,8 +9,9 @@ the owner's review; sessions since 2026-09-27, and the game-memory figures beta.
|
||||
|
||||
**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
|
||||
measurement below is Direct3D 11 or 12. What the tiers mean and what FrameLedger cannot do: [LIMITATIONS.md](../LIMITATIONS.md).
|
||||
graphics card and no second machine has been tested**, and ~~**no real Vulkan or OpenGL game has been measured** — every
|
||||
measurement below is Direct3D 11 or 12~~ **one real Vulkan game has been measured (Everhex Demo, 2026-10-13) and no
|
||||
OpenGL game** — every other measurement below is Direct3D 11 or 12 *(corrected 2026-10-14)*. What the tiers mean and what FrameLedger cannot do: [LIMITATIONS.md](../LIMITATIONS.md).
|
||||
|
||||
**Two periods.** From 2026-08-03 to 2026-09-06 the games were measured with the developer's capture tool, one run at a
|
||||
time against the game's own settings menu (reports in [spike-notes.md](spike-notes.md)). From 2026-09-16 the shipped
|
||||
@@ -43,12 +44,13 @@ with the 2026-09-16 recovery and with library entries removed since.
|
||||
| 恋しかるべき (KOISHIKARUBEKI) | Unity 6000.3 | D3D11 | Presented 59.6 FPS | 2026-09-03 | [spike-notes §9](spike-notes.md) |
|
||||
| Flower in Us | RPG Maker MV/MZ (NW.js) | D3D11 | Presented 59.8 FPS over three swap chains, after two refusals that found the game's browser process ambiguous (fixed) | 2026-09-03 → 09-04 | [spike-notes §9](spike-notes.md) |
|
||||
| UMIGARI | Unreal Engine 5.5.4 | D3D12 | Presented 95–97 FPS, frame generation *none*, ray tracing *No* | 2026-09-05 → 09-06 | run reports only |
|
||||
| Everhex Demo | — | Vulkan | Presented 239.7 FPS (1 % low 213.5), 14,955 frames in 69 s, through FrameLedger's Vulkan layer — the first real Vulkan game measured; started by Play set to *Start directly* | 2026-10-13 | database *(row added 2026-10-14 from a copy of the database)* |
|
||||
|
||||
## Recorded without measurement (Tier 2)
|
||||
|
||||
| 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 |
|
||||
@@ -62,6 +64,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).
|
||||
|
||||
+10
-3
@@ -7,7 +7,8 @@ This folder is for people who build, change or review FrameLedger. **If you only
|
||||
|
||||
| You want to… | Read |
|
||||
|---|---|
|
||||
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (D1…D46) and the traps that each cost a cycle. It carries no status on purpose |
|
||||
| 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) |
|
||||
@@ -68,7 +69,11 @@ are safety items, and something listed there as unresolved should not be built t
|
||||
| [`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 |
|
||||
| [`HANDOFF.md`](HANDOFF.md) | Sequencing, the open owner-only items, the index of the owner's decisions |
|
||||
| [`handoff/`](handoff/) | Since beta.24 (D66): the history of every train and phase, the passed owner-only items, the traps — moved out of `HANDOFF.md` verbatim |
|
||||
| [`open-questions/`](open-questions/) | Since beta.24 (D66): the entries §S24 marks resolved, moved out of `20_OPEN_QUESTIONS.md` verbatim — a table there lists them |
|
||||
| [`spike-notes/`](spike-notes/) | Since beta.24 (D66): one file per measurement section; `spike-notes.md` is the index that resolves `spike-notes §N` |
|
||||
| [`changelog/`](changelog/) | Since beta.24 (D66): each release's notes in its own file, and the ledger kept before the first tag; `../CHANGELOG.md` keeps `[Unreleased]` and the list |
|
||||
| [`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 |
|
||||
@@ -76,7 +81,9 @@ are safety items, and something listed there as unresolved should not be built t
|
||||
|
||||
## Beside this folder
|
||||
|
||||
- [`../guide/`](../guide/README.md) — the user guide (players, English).
|
||||
- [`../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.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.1] - 2026-09-16
|
||||
|
||||
**The first pre-release.** An unsigned installer, `FrameLedger.App-win-Setup.exe`, built by `release.yml` from
|
||||
this tag; `SHA256SUMS.txt` is published beside it and printed below. SmartScreen will warn (no code signing —
|
||||
`docs/11_UPDATER.md`); verify the hash, then *More info → Run anyway*. It installs into `%LOCALAPPDATA%\FrameLedger.App`
|
||||
and keeps its data in `%LOCALAPPDATA%\FrameLedger`; uninstalling asks before touching the data. Windows 10 22H2 is
|
||||
the supported floor and is **unmeasured** — every measurement below was taken on one Windows 11 machine with an NVIDIA
|
||||
GPU (`docs/spike-notes.md`).
|
||||
|
||||
### What it is
|
||||
|
||||
- **A desktop app and a background Agent.** The App (WPF) holds the library, imports it from Steam, GOG, Epic and
|
||||
itch.io, shows the Dashboard, session summaries, charts, trends and comparisons, Settings, Logs, the tray, the
|
||||
first-run Legal Gate and the bug report. The Agent watches the library at 1 Hz, records a session whenever a
|
||||
library game runs, and stores it in a local SQLite ledger. Nothing leaves the machine except the update check
|
||||
(`legal/PRIVACY_POLICY.md` 2.2).
|
||||
- **Measurement by hooking, opt-in per game, behind a hard anti-cheat gate.** For a game you enabled — and only
|
||||
after the consent dialog — the Agent loads `FrameLedger.Overlay.dll` into the game and reads what the game passes
|
||||
to the graphics APIs: frame times and output resolution from the present call (Direct3D 11/12, OpenGL; Vulkan
|
||||
through an implicit layer, today only when the Agent itself launches the title); upscaler identity and
|
||||
render→output resolution from Streamline and FidelityFX calls; the frame-generation factor from Streamline's frame
|
||||
token and FidelityFX's dispatches, **counted, never assumed**; ray tracing from DXR dispatch and
|
||||
acceleration-structure hooks. Before injecting, and every 30 s during a session, the guard scans the process
|
||||
tree for anti-cheat and anti-tamper modules, services and drivers and **refuses** — there is no override — and a
|
||||
refusal mid-session unhooks within a frame. A game that is not enabled, or is refused, is recorded as duration
|
||||
and hardware sensors with the reason, and every measured field reads N/A.
|
||||
- **Honest numbers by rule.** Where frame generation is active the readout is *Native → Displayed (×N FG)*;
|
||||
where it was identified but the count refused — a session whose frame-generation state changed (menus,
|
||||
loading screens, alt-tab), or a title with two swapchains — the chip says "factor not counted" and its tooltip
|
||||
says which bucket and by how much. Ray tracing, path tracing and Ray Reconstruction are Yes / No / N/A, measured
|
||||
or not at all. The one number that stands alone carries a qualifier saying whether a frame-generation runtime
|
||||
was loaded.
|
||||
- **Telemetry** from DXGI and PDH (every vendor), LibreHardwareMonitor (GPU sensors unelevated), and NVAPI on
|
||||
NVIDIA. CPU and board sensors need PawnIO and elevation and are off by default.
|
||||
- **Safety and legal surface:** the consent dialog with the disclosure text in en/vi/ja (ja machine-drafted,
|
||||
marked for review), the kill switch, a crash within 60 s of injection twice auto-disabling hooking for that game,
|
||||
the Legal Gate (EULA 1.0, Disclaimer 2.2, Privacy Policy 2.2), the bug bundle built locally and redacted,
|
||||
crash dumps offered only when ticked.
|
||||
|
||||
### What it is not, yet
|
||||
|
||||
- **No rules feed.** The anti-cheat blocklist and the detection rules ship with the build and update only with the
|
||||
next release (`docs/20_OPEN_QUESTIONS.md` §S20). A missed anti-cheat is a safety report (`SECURITY.md`).
|
||||
- **Vulkan in attach mode is unmeasured**, and the layer is registered only when you ask (Settings).
|
||||
- **The DLSS quality preset reads N/A** on every title measured: no title chains the structure that carries it.
|
||||
- **AMD and Intel GPUs are unmeasured** for telemetry and for their frame-generation runtimes; XeSS and the newer
|
||||
FidelityFX frame generation are identified by module, not counted.
|
||||
- **The frame-generation factor is refused rather than guessed** on whole play sessions that changed state; a
|
||||
steady-state figure over the uniform part of a session is a decision not yet taken.
|
||||
- **The ≤ 0.5 % FPS-impact run and the "against the game's own menu" readings** in `docs/spike-notes.md` §14 are
|
||||
still the owner's to take.
|
||||
|
||||
### The record
|
||||
|
||||
Everything that landed before this tag — every PR from 2026-08-04 to 2026-09-16, with its reasoning — is the
|
||||
section *Ledger before 0.1.0-beta.1* below, kept verbatim.
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.10] - 2026-09-28
|
||||
|
||||
**The tenth pre-release: how each game was shown, the agent as administrator if you choose it, and the exact Unreal
|
||||
Engine version.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
What changed for a user:
|
||||
|
||||
- **The display mode** — exclusive full-screen, borderless, windowed or minimised, as a share of each session, with the
|
||||
window's size and the monitor's — on the session summary, the game page, the Trend (three new metrics) and Compare,
|
||||
for measured and unmeasured sessions alike. Only a measured Direct3D game can say *exclusive*; others read
|
||||
*full-screen or borderless* when the window covers the screen.
|
||||
- **Run the agent as administrator** — a Settings option, off by default. Windows asks every time the agent starts;
|
||||
games you start from FrameLedger still run with your standard rights; it changes nothing in the anti-cheat guard.
|
||||
- **The exact Unreal Engine version** on a game's page, read from its executable, with what it rests on.
|
||||
- **What FrameLedger cannot do** is one page — Help ▸ Limitations, and `LIMITATIONS.md` — and the games it has been run
|
||||
with are listed in `docs/LIST_GAME_TESTED.md`.
|
||||
- **The Privacy Policy (2.5) and the Disclaimer (2.8) say so**, so the Legal Gate opens once after the update. The EULA
|
||||
is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.9`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schemas 0015 and 0016 add columns; the database opens in place. Sessions recorded before show the display mode as N/A.
|
||||
- The shared-memory layout between the agent and a measured game changed (version 4): **a game that was running while
|
||||
you updated must be restarted before it can be measured** — the app says so when it meets the old layout.
|
||||
- Every game is re-detected once (rules `2026.09.6`), which fills in the Unreal Engine versions.
|
||||
|
||||
### Added
|
||||
|
||||
- **The exact Unreal Engine version on a game's page** (owner request, beta.10). The Agent reads it from the game's
|
||||
shipping executable on disk — its version number and the engine's build name compiled into it (`++UE5+Release-5.1`)
|
||||
— and the page says which of the two it rests on: *Unreal Engine 4.27.2* for Lies of P, *5.4.4* for Clair Obscur:
|
||||
Expedition 33, *5.1* for SILENT HILL 2 (whose studio replaced the version number with its own), and "not found in the
|
||||
executable" where neither says anything (Cronos, Rune Factory). Measured on ten installed Unreal titles before it was
|
||||
written: eight read, two honestly none. The file is read, never the game's process; a protected executable is scanned
|
||||
whole, once per version of the file (up to 7.5 s on a USB drive for Black Myth: Wukong), and the scan stops if the Agent
|
||||
is asked to. Rules `2026.09.6`: every game is re-detected once. Schema 0015 adds `games.engine_version_source`.
|
||||
|
||||
- **How each game was shown, and for how much of the session** (owner request, beta.10): exclusive fullscreen, borderless,
|
||||
windowed or minimised, with the window's size, the monitor it was on and its refresh rate, and the swap chain's back
|
||||
buffer. On the session summary (a *Display* card and a line with every share), the game page (the last measured session,
|
||||
and a *Display* column in Sessions), the Trend (three new metrics: the share of each session in exclusive fullscreen,
|
||||
borderless and windowed), Compare (three rows, never ranked) and both exports (the CSV's `# display:` line, the JSON's
|
||||
aggregates). **Both tiers:** a game that was not hooked has its window read from outside, which can say windowed or
|
||||
*fullscreen or borderless* but never which of those two — only the swap chain of a hooked DirectX game can say
|
||||
exclusive. What Windows does with an exclusive game behind the scenes ("fullscreen optimizations") is not visible to
|
||||
FrameLedger, and a game's menu may call a borderless window "Fullscreen": the swap chain's answer is the one shown.
|
||||
Sessions recorded before, and one recovered after a crash, read N/A. Schema 0016 adds fifteen `sessions.display_*`
|
||||
columns, and `sessions.swap_effect` — a column with no writer since the first schema — is now filled.
|
||||
|
||||
- **Run the capture agent as administrator — your choice, off by default** (owner request, beta.10). Settings ▸ Capture
|
||||
agent ▸ *Run the agent as administrator* shows what it adds (measuring a game that itself runs as administrator; the CPU
|
||||
temperature where PawnIO is installed), what it does not change (a game with anti-cheat is still refused; a Vulkan game
|
||||
run as administrator is still not measured) and the risk of a per-user, unsigned install, before it turns on. Then
|
||||
**Windows asks every time the agent starts** — also at logon, when its prompt may wait on the taskbar; there is no
|
||||
silent way. Answer No and the agent runs with your standard rights and says so; answer with another administrator
|
||||
account and that agent refuses to run, because its data would not be yours. **Games you start from FrameLedger always
|
||||
run with your standard rights**, and nothing FrameLedger does enables a privilege (a CI test on an elevated runner and a
|
||||
source check hold both). While the prompt waits, the status pill says so. With the option off, an App started as
|
||||
administrator no longer makes the agent an administrator's too. Updating now also waits for an administrator agent's
|
||||
process to let go of its files.
|
||||
|
||||
- **What FrameLedger cannot do, in one place** (beta.10). `LIMITATIONS.md` lists the limits of the whole software in
|
||||
plain words — the games it will not measure, what an unmeasured session holds, frame generation, upscaling and ray
|
||||
tracing, the display mode, the engine version, sensors, the admin mode, the platform and your data — each linked to its
|
||||
details; the app shows it under **Help ▸ Limitations**. `docs/LIST_GAME_TESTED.md` lists the real games FrameLedger has
|
||||
been run with and what was measured on each.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The legal documents say what beta.10 does** — you will be shown two of them again once. **Privacy Policy 2.5** adds
|
||||
how a tracked game's window is shown (read from Windows) and the engine version read from an Unreal Engine game's
|
||||
executable, and says for the first time two things the software already did: it reads the content of a library game's
|
||||
executable (engine and library markers, its import table) and the processor load and memory in use. **Disclaimer 2.8**
|
||||
adds §5A — running the capture agent as administrator, what it does and does not do, and its risk — and points at the
|
||||
new limitations page and the tested-games list. The End-User License Agreement is unchanged (1.3).
|
||||
|
||||
- **Groundwork for the display mode (beta.10): the injected component reports how the game presents** — whether its swap
|
||||
chain is in exclusive fullscreen, which window it presents to, its back buffer and swap effect — at most twice a second,
|
||||
from two getters on the swap chain the game passed (measured at 13–15 ns each on the test fixture: nothing a frame rate
|
||||
can see). The shared-memory layout moves to version 4 (a new region; the frame ring moved behind it): **a game that is
|
||||
running while FrameLedger is updated must be restarted before it can be measured**, which the app already says when it
|
||||
meets an old layout. What the app shows from it is the display mode under *Added*.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **An Unreal game's engine version was a bare "4" or "5"** — and for most titles nothing at all. The rule's pattern had two
|
||||
capture groups and the evaluator keeps the first, and it read only a version string most executables leave empty.
|
||||
Schema 0015 removes the digits the old rule wrote (only where detection wrote them — a version you typed stays), and the
|
||||
rules validator now refuses any version pattern that does not compile or that captures anything but exactly one group.
|
||||
|
||||
- **A Direct3D 12 game that resized through `ResizeBuffers1` kept its old output size in every later frame.** That call is
|
||||
not hooked; the swap chain's size is now re-read twice a second, so a resize by either route is seen.
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,
|
||||
outside the game's folder, so nothing of the game's own can name it and the list does, by Steam id only (no executable
|
||||
name was verified). ANOTHER EDEN, which a community list also names, is left out: its store page says nothing of the
|
||||
kind. Rules `2026.10.1` — every game is re-checked once, and these games' hooking is turned off like any title-list
|
||||
finding, never under a user-mode exception (`19_SAFETY` check 3).
|
||||
|
||||
### Changed
|
||||
|
||||
- **The user-mode anti-cheat exception no longer needs sessions measured before it — its first two sessions are a
|
||||
trial** (owner decision D38, beta.11). D33 asked for two successful hooked sessions before a grant, but since beta.8 a
|
||||
game is blocked the moment it is added, so a blocked game could never earn them, and a reset ledger lost the ones it
|
||||
had: after the owner deleted theirs, GIRLS' FRONTLINE 2 read *"Not eligible: 0 successful hooked session(s), two are
|
||||
needed"* for good. A grant now needs no session. Until two sessions under it have succeeded, the game page says
|
||||
*trial: N of 2*, and any end during the trial — a crash, a safety unhook, the Overlay's own stop, a new finding, or a
|
||||
stored hooked session that recorded no frame or did not end normally — ends the exception **for good** (schema 0017,
|
||||
`games.ac_exception_trial_failed_at`, set once and never cleared; the Agent refuses a grant with `TrialFailed` and the
|
||||
store refuses one in SQL; a twin merge keeps the mark). Every other condition is unchanged — one user-mode family, no
|
||||
`.sys` in the game's folder, no title list — and after the trial an end is what it was. The disclosure is
|
||||
`ac-exception-dialog/2`: it names no session count and has a *Trial* paragraph (`ja` stays English until reviewed).
|
||||
**Legal text:** Disclaimer 2.9 (§2A) and EULA 1.4, so the Legal Gate opens once; the accuracy block, `SECURITY.md` and
|
||||
`LIMITATIONS.md` say the same; CLAUDE.md rule 2 carries the amendment (`19_SAFETY` §The user-mode exception).
|
||||
|
||||
### 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
|
||||
games it can act on; a tolerant scan that found nothing of the family was said as "the check could not finish" — it
|
||||
says the family was not found; and a blocked game whose executable could not be read stayed *Checking…* for ever — the
|
||||
sweep now answers it. **Refresh** shows only while a row is being checked, the one time it can change anything.
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,49 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,117 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,49 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,17 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,37 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,48 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,53 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,114 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.2] - 2026-09-17
|
||||
|
||||
**The second pre-release.** The same unsigned installer as `0.1.0-beta.1`: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user: a finished session whose frame generation
|
||||
did not stay in one state — a menu, a loading screen — now shows the factor of its steady state with the share of
|
||||
the session it covers, where `0.1.0-beta.1` showed "factor not counted" for most real sessions; and three faults from
|
||||
the first day of use are fixed: an App started as administrator started another Agent every few seconds, and each of
|
||||
them recorded every game; closing the App ended in an error; and a crash dump could hang the process it described.
|
||||
|
||||
**Updating from `0.1.0-beta.1`:**
|
||||
|
||||
- **Quit the App (tray icon → Exit), then end every `FrameLedger.Agent.exe` in Task Manager before installing.** If the
|
||||
App was ever started as administrator, some Agents run elevated, and Task Manager can end those only when it runs
|
||||
as administrator itself.
|
||||
- On its first start the ledger migrates to schema 6. Sessions recorded before keep the frame-generation result they
|
||||
were stored with; the steady state applies to sessions recorded from this version on.
|
||||
- Sessions recorded while more than one Agent was running appear once per Agent. Nothing removes them automatically.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Closing the App no longer ends in a Fatal error and exit code 1 (2026-09-17).** Measured on the installed
|
||||
0.1.0-beta.1: `ui-*.log` recorded `ui: the run ended in an exception` — "the calling thread cannot access this object
|
||||
because a different thread owns it" — from `TrayHost.Dispose` on every close after an update check. The App waited
|
||||
with `WaitForShutdownAsync`, which resumes on the thread pool and stops the hosted services there, so the tray icon (a
|
||||
WPF object whose disposal unsubscribes `Application.Exit`) was removed off its thread; `TearDownAsync` then stopped every
|
||||
service a second time. The App now waits for the stop request on the dispatcher and stops the host once, from the UI
|
||||
thread, and `TrayHost.Dispose` marshals to the icon's own dispatcher from any thread (bounded at 5 s; skipped when the
|
||||
dispatcher has already shut down). Test: `TrayHostTests` disposes a real tray icon from a pool thread while the UI
|
||||
thread pumps — red on the old code with that exception, green now; skipped where the session has no notification area.
|
||||
|
||||
- **A crash dump can no longer hang the process it describes, and the test suite no longer freezes (2026-09-17).**
|
||||
`FrameLedger.Infrastructure.Tests` hung about one run in eight — it cancelled the first tag's release run after 58
|
||||
minutes — and the verbose reporter of a hung run showed thirteen tests started and none finished, one of them
|
||||
`CrashDumpWriterTests.WritesAMinidumpOfThisProcess…`. That test, and the product's crash path in the App and the Agent,
|
||||
called `MiniDumpWriteDump` on the calling process, which suspends every other thread of it; one holding the heap or
|
||||
loader lock deadlocks the dumper, and the whole process freezes with it. Forty runs without the test: no hang. The dump
|
||||
is written by a child now: `CrashDumpWriter.TryWrite` starts `FrameLedger.Agent.exe --write-crash-dump <file>` and waits
|
||||
up to 30 s, and the helper (`Infrastructure.Diagnostics.ParentDump`) dumps its parent with the same flags — it takes no
|
||||
pid and refuses unless the parent is still running, started before it and sits in the helper's own directory, so it can
|
||||
only ever read the App or the Agent (CLAUDE.md rule 4). Forty runs of the suite with the new tests: no hang.
|
||||
`--blame-hang` (#196) did not stop the hung xUnit v3 executable, so `build.ps1` runs `dotnet test` under a 25-minute
|
||||
wall-clock limit, kills the tree on expiry and names the test projects that wrote no `results.trx`. Tests:
|
||||
`ParentDumpTests` (a real minidump of another process; which parent is ours), `CrashDumpWriterTests` (a failing and a
|
||||
missing dumper), `CrashDumpHelperTests` (the shipped Agent dumps the test process from outside; it refuses a parent
|
||||
from System32; the flag's surface). Docs: `10_LOGGING` §Crash handling, `12_BUILD` Agent flags, `13_CI_CD` tally.
|
||||
**A hang in one test process no longer fails the others.** The migration mutex was one name for every ledger
|
||||
(`Local\FrameLedger.Ledger.Migrate`), so a suite frozen mid-migration held every other process's scratch ledger: on
|
||||
#199's run `Infrastructure.Tests` hung and seven App and Agent tests failed after 30 s with "another process has been
|
||||
migrating the ledger". It is the file's now (`MigrationRunner.LockNameFor`; `MigrationLockTests`; `06_DATA_MODEL`
|
||||
§Migrations). And a failed dump names dbghelp's error instead of 0: CsWin32 declares `MiniDumpWriteDump` without
|
||||
`SetLastError`, so the code is read with `GetLastSystemError` (`ParentDumpTests`: an exited process).
|
||||
|
||||
- **One Agent per data folder: an App started as administrator no longer starts an Agent per connect round
|
||||
(2026-09-17).** On the owner's machine the installed 0.1.0-beta.1 ran four `FrameLedger.Agent.exe --serve`: the App
|
||||
opened at 10:04 was elevated, the pipe of the Agent already serving refused it, and it took the refusal for an absent
|
||||
Agent and started three more, elevated like itself, 17 seconds apart. Nothing in the Agent noticed the first — the
|
||||
single instance `01_ARCHITECTURE` §Lifecycle specified was never built — so every game launched in the next hour was
|
||||
injected, read and recorded by all four (four copies of each session, equal frame counts), and the three extras
|
||||
logged "accept failed" every 260 ms for four hours. The cause of the refusal: `PipeOptions.CurrentUserOnly` compares
|
||||
the pipe's owner with the client token's default *owner*, which an elevated token sets to Administrators (the elevated
|
||||
Agents' log files are owned by Administrators, measured), not with its *user*.
|
||||
- `Infrastructure.Startup.AgentInstanceLock`: a named mutex per data folder, claimed by `--serve` and the console's
|
||||
`capture` / `launch` / `recover` before logging, rules and the ledger; a second process exits **10** with one line.
|
||||
- The App starts an Agent only when no process holds the folder and the one it started last has exited; it logs why a
|
||||
connect failed, once per reason, and the exit code of the Agent it started.
|
||||
- The pipe states its owner (`O:<user>` in the SDDL) and the client checks the owner against its token user
|
||||
(`PipeAccessControl.RequireOwnedByCurrentUser`), so an elevated App and an unelevated Agent reach each other in both
|
||||
directions.
|
||||
- A pipe instance that cannot be created backs off 250 ms → 10 s and is logged with its Win32 error, once per streak
|
||||
(CsWin32 declares `CreateNamedPipeW` without `SetLastError`; the error is read with `GetLastSystemError`).
|
||||
- Tests: `AgentInstanceLockTests`, `OneAgentPerDataFolderTests` (the shipped binary against a claimed scratch folder),
|
||||
`AgentConnectionTests` (an Agent that is up and does not answer is never started again; the real launcher sees the
|
||||
claim), `PipeServerClientTests` (the owner; an Administrators-owning token trusts its user's pipe and refuses an
|
||||
Administrators one — on CI's elevated runner; the backoff logs once with error 231). Docs: `01_ARCHITECTURE`
|
||||
§Lifecycle, `07_IPC` §C and §Client behavior, `08_UI`, `12_BUILD`, `20_OPEN_QUESTIONS` §G.
|
||||
|
||||
### Added
|
||||
|
||||
- **A session whose frame-generation state changed publishes its steady state, with its share (2026-09-17, owner
|
||||
decision — `03_METRICS` §The steady state).** The owner saw the live card show the FG factor all session and the
|
||||
finished session show "factor not counted" most of the time, and suspected the path from the hook to the UI. The
|
||||
path is whole: the stored per-frame counts of all nine hooked sessions of 2026-09-16 read 2.00 / 3.00 / 4.00 inside
|
||||
gameplay. The live card looks at five seconds; the stored row looked at the whole session, split it in eight and
|
||||
refused it when one bucket departed — and every real session opens with a splash, a menu or a loading screen, so
|
||||
one session in nine published. The refusal is right (Wukong's session averages to 2.22; its gameplay ran ×4.1) and
|
||||
stays; what changes is that the gameplay's number is no longer thrown away with the average.
|
||||
`Domain.Metrics.FgSteadyState`: five-second windows (the live card's own), the ACTIVE windows agreeing within 10 %
|
||||
that hold the most time, published at ≥ 10 s and ≥ 10 % of the presenting time — `fg_factor` / `native_fps` /
|
||||
`displayed_fps` from that state's own windows, `fg_factor_scope = 'steady'`, `fg_steady_share` (schema **0006**),
|
||||
the refusal and its detail kept beside it. The readout is the generated shape with the chip **`×2.0 FG · 75%`** —
|
||||
the share is never omitted — and a tooltip saying why there is no session-wide factor. Replayed over the nine
|
||||
sessions through the real `FgWindow`: eight publish (Onimusha ×4.00 60 → 240, Lies of P ×2.00, Hell Is Us ×3.03,
|
||||
Cronos ×2.00 225 → 451, Wukong ×4.11); the ninth had nine seconds of gameplay. **Two constants moved with it:**
|
||||
`BucketTolerance` 25 % → 10 % (at 25 % a ×3-then-×4 session published 3.69, and the one published session read
|
||||
×2.04 for a gameplay of 2.00), and `MultipleStreams` refuses only when the chains' samples interleave — Onimusha
|
||||
recreates its swapchain on entering gameplay, one stream at a time, and had been refused as two on every session.
|
||||
CLAUDE.md rule 6 amended. Two strings (en/vi/ja). Tests: `FgSteadyStateTests`, `FgWindowTests` (interleaved vs
|
||||
sequential), `SessionAggregatorTests`, `FpsPresentationTests`, `LedgerDatabaseTests` (script six), the repository
|
||||
round trip. Existing rows are not re-aggregated.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The first tag ran (2026-09-16).** `v0.1.0-beta.1` on `becc208`; `release.yml` run 35111939019. The first attempt
|
||||
passed the version gate and the substitution and then sat in `Infrastructure.Tests` for 58 minutes — every other
|
||||
suite green, the same suite 42 s in the rehearsal — until the job's 60-minute limit cancelled it with no test named;
|
||||
`gh run rerun --failed` on the same tag went green in 11 minutes and created the pre-release with the section's notes
|
||||
and the checksums appended. `build.ps1` now runs `dotnet test` with `--blame-hang --blame-hang-timeout 15m` (#196) so
|
||||
the next hang is a named failure; the capture-host suite's `Kill` waits for exit (#194) and the layer-registration
|
||||
test deletes only its own registry subtree (#188), the two harness races the same evening's merge train kept hitting.
|
||||
Docs: `13_CI_CD` §release.yml and §ci.yml's tally, `12_BUILD` §Publish & package (the runner's sizes),
|
||||
`15_ROADMAP` §P5.
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,64 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [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,0 +1,19 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.22] - 2026-10-13
|
||||
|
||||
**The twenty-second pre-release: a request the capture agent never answered is said as such, never as a crash.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.21`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing is
|
||||
shown to accept and no game is read again: the legal documents and the detection rules (`2026.10.4`) are beta.21's.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A request the capture agent never answered is said as such, never as a crash.** When the agent stopped, or restarted
|
||||
for an update, while FrameLedger was asking it something, deleting sessions ended in the crash dialog, and turning a
|
||||
game's hooking on or off or making or withdrawing an anti-cheat exception showed *IOException* or *TimeoutException* as
|
||||
its notice. Each now says that the agent did not answer and that whether it was done is not known, and the page shows
|
||||
what is stored; Play says the same (it said the agent was not running). A request that could not be sent because the
|
||||
agent was already gone still says that nothing was changed (`docs/07_IPC.md` §Client behavior).
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.23] - 2026-10-14
|
||||
|
||||
**The twenty-third pre-release: a game's artwork on its page, in a band that takes the picture's colour, and pages
|
||||
that open and change session without freezing.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.22`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
|
||||
Privacy Policy (2.11) is shown once for you to accept. No game is read again: the detection rules (`2026.10.4`) are
|
||||
beta.22's. The artwork shows by itself for the games Steam or GOG GALAXY installed; **Settings ▸ Games** turns it, or
|
||||
its colour, off.
|
||||
|
||||
### Added
|
||||
|
||||
- **A game's page shows its artwork** (owner request 2026-10-14, decisions D60/D61). At the top of the page: the
|
||||
banner and the cover the Steam or GOG GALAXY app already keeps on your PC for the game it installed — read where that
|
||||
app keeps them, never downloaded and never copied — or an image you choose yourself in **Edit… ▸ Choose image…** (a
|
||||
copy is kept in the data folder's `covers` folder; **Use the store's image** goes back). The band they sit in takes the
|
||||
picture's main colour, never so strongly that a text on it gets hard to read (primary and secondary text keep 4.5:1,
|
||||
the faintest 3:1, in both themes), and follows a theme switch. A game from itch, the Epic Games Launcher or another
|
||||
store has a picture only once you choose one, because those apps keep no image files. **Settings ▸ Games** has *Show
|
||||
game artwork* and *Colour the game page from its artwork*, both on. **Privacy Policy 2.11** names the images read and
|
||||
the copies kept; FrameLedger still makes no request to any store.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The list of tested games has its first Vulkan game**: Everhex Demo, measured through FrameLedger's Vulkan layer on
|
||||
2026-10-13 when Play started it directly (`docs/LIST_GAME_TESTED.md`, `LIMITATIONS.md`). Four places in the developer
|
||||
documents that described something never built, or kept a count that went stale, are corrected in place.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A game's page opens and changes session without freezing the window** (owner request 2026-10-14). Measured on the
|
||||
dev PC over a ledger shaped like the owner's (`docs/spike-notes.md` §21): a game with 100 sessions took 1.2–1.5 s to
|
||||
open — its Sessions list built every row, now only the rows on screen (it scrolls itself and hands the wheel to the
|
||||
page at its ends) — 0.37 s now; choosing a two-million-frame session froze the window 0.8–1.0 s — the session was read
|
||||
and decoded on the UI thread, then sorted three times for the Distribution tab — 17 ms now: it is read on the thread
|
||||
pool and what the charts need from all of it is worked out there once. The page also asks whether the game's `.exe` is
|
||||
on disk off the UI thread (a USB drive that sleeps answered on it), and no longer summarises every game to show one.
|
||||
- **Each visit to the Dashboard or Logs no longer stays in memory.** Every Dashboard ever opened stayed alive and kept
|
||||
listening to the capture agent, so at each session's end each one reloaded its lists and raised its own "Session
|
||||
saved" notice — twenty visits, twenty notices, the last one shown. The Dashboard listens only while it is on screen,
|
||||
and the notice has one home for the App's life, shown once whichever page is open; each Logs page kept its tail of up
|
||||
to 2 MB, twice.
|
||||
- **The Logs page reads its file only when it changed**, not every two seconds, and filters it off the UI thread; **Play**
|
||||
reads the stores' lists of installed games off the UI thread (Steam's manifests sit on whatever drive its libraries
|
||||
are on). At Debug level the App now logs how long each page took to appear (`ui: page … shown … ms`).
|
||||
- **The native ring-buffer tests no longer pass or fail by the scheduler's luck** (developers only). The
|
||||
hammering-writer test required the reader to keep more than half of the stream, which measured how the operating
|
||||
system scheduled two threads: on a hybrid Intel processor it failed 5 of 200 runs with the ring correct every time.
|
||||
Both concurrency tests now start the writer only once the reader is running, repeat until the reader really read
|
||||
the ring while the writer wrote it, and require that; the small-ring test's old check also passed a reader that
|
||||
started after the writer had finished (`src/native/tests/ring_test.cpp`).
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.24 was cut, 2026-10-19 (D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.24] - 2026-10-19
|
||||
|
||||
**The twenty-fourth pre-release: every frame-generation state a session held, the quality mode the NVIDIA App set, and
|
||||
which DLSS ran.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
|
||||
|
||||
**Updating from `0.1.0-beta.23`:** Help ▸ Check for updates, then *Restart to update* with no game running. The
|
||||
Disclaimer (2.11) and the Privacy Policy (2.12) are shown once for you to accept. The ledger moves to schema 21, which
|
||||
a beta.23 cannot open. No game is read again: the detection rules (`2026.10.4`) are beta.23's. The mix of
|
||||
frame-generation states and where each DLSS library was loaded from are kept for sessions recorded from now on; the
|
||||
quality mode the NVIDIA App set reads on sessions you already have.
|
||||
|
||||
### Added
|
||||
|
||||
- **Every frame-generation state a session held, in its summary** (owner request 2026-10-19, decision D62). Under the
|
||||
figures, *Frame generation in this session* lists each state — `×2.0`, `×3.0`, `×4.0`, `×6.0`… — with its own
|
||||
Native → Displayed and its share of the time to two decimals, then the time with no frame generation and the time no
|
||||
state explains (*Not classified*: switching, loading, a multiplier that changed faster than five seconds), above a bar
|
||||
of those shares. A line above them says how frame generation was set: in the NVIDIA App (*Dynamic, up to ×6, target:
|
||||
max refresh rate*, *Fixed ×4*, from the driver profile stored with the session) or in the game. Each state is read
|
||||
over the same five-second windows as the steady state and lasts at least 10 seconds; nothing is averaged across
|
||||
states (rule 6). Stored with the session (schema 0020, `sessions.fg_mix`): a session recorded before has none, and
|
||||
its summary says so in one line. The CSV export gains a `# fg_mix:` line; the JSON carries the column. The FG×
|
||||
column's two formats are translated strings now, and the driver-profile line's automatic dynamic target reads as the
|
||||
NVIDIA App says it: *max refresh rate*.
|
||||
|
||||
- **The quality mode the NVIDIA App set, on every page that names the upscaler** (owner request 2026-10-19, decision
|
||||
D63). Where the NVIDIA App overrides DLSS Super Resolution for a game and the NVIDIA driver reports that the
|
||||
override applied in the session, the summary, the Sessions tab, the game page and the live card say so:
|
||||
*DLSS (driver-reported) Quality · NVIDIA App*. It is read from what every session already stores, so sessions
|
||||
recorded before read the same; when the profile and the driver disagree, or the driver's report alone cannot settle
|
||||
the mode, the session reads *· NVIDIA App override* with no mode — never the game's own value in its place. The CSV
|
||||
export gains a `# quality_mode:` line. `legal/ACCURACY.md`'s *Quality mode* bullet says so, in the words approved
|
||||
with the plan; **the Disclaimer is 2.11** and the Legal Gate shows it once.
|
||||
|
||||
- **Which DLSS a session ran** (owner request 2026-10-19, decision D64). The summary's DLSS line gives each DLSS
|
||||
library's version and whether it was loaded from the game or from the graphics driver (the NVIDIA App's override
|
||||
loads the driver's own copy), the model preset the NVIDIA driver reports, and *DLSS 4* or *DLSS 4.5* only where the
|
||||
session shows it — the preset (L or M: 4.5; J or K: 4) or a measured multi-frame factor (×5–×6: 4.5; ×3–×4: 4) —;
|
||||
DLSS 2 and 3 from their libraries; *DLSS 5 runtime loaded* when its library is. The game page repeats the label and
|
||||
the CSV export gains `# dlss:`. The module snapshot now records every library under the NVIDIA override folder,
|
||||
whatever its name, and each module's folder class (schema 0021, `sessions.runtime_module_sources` — never the path),
|
||||
plus five more libraries by name (`sl.dlss_d.dll`, `sl.common.dll`, `sl.reflex.dll`, `amd_fidelityfx_loader_dx12.dll`,
|
||||
`nvngx_dlssnr.dll`). **Privacy Policy 2.12** says so, in the words approved with the plan; `legal/ACCURACY.md` gains
|
||||
the *DLSS version* bullet.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The analyzers are Meziantou.Analyzer 3.0.307 and Microsoft.VisualStudio.Threading.Analyzers 18.12.1**
|
||||
(developers only): the update Dependabot proposed in #314 and then closed itself as "updatable in another way" —
|
||||
applied by hand, with the two suppressions it needed merged earlier in the train.
|
||||
- **SonarCloud analyses only FrameLedger's own code** (developers only; owner request 2026-10-19, decision D67). A
|
||||
`.sonarcloud.properties` at the root keeps the vendored SDK headers, generated files, test fixtures, licence texts and
|
||||
the SQLite migrations out of the analysis and reports the native code against C++20; `docs/13_CI_CD.md` §SonarCloud
|
||||
records the triage of the 341 issues the last analysis left — the rules this project breaks by design and why, the
|
||||
false positives, and the ones the next change fixes — with the steps to mark them in SonarCloud.
|
||||
- **The long documents are split** (developers only; owner request 2026-10-19, decision D66). `CHANGELOG.md`
|
||||
keeps `[Unreleased]` and a table of the releases; each release's section now lives in its own file,
|
||||
`docs/changelog/<version>.md`, and the ledger kept before the first tag in five parts — moved verbatim: the notes
|
||||
`tools/release-notes.ps1` takes for each of the 23 releases are byte for byte what they were, and it reads the
|
||||
version's own file. `docs/HANDOFF.md` (2,844 lines, now 299) keeps what to do next, the open owner-only items and an
|
||||
index of every owner decision; the history of each phase and train, the passed owner-only items and the traps
|
||||
moved to `docs/handoff/`, and a table there resolves every section the code and the documents cite. A new gate,
|
||||
`tools/docs-split-check.ps1`, keeps each index and its files naming each other.
|
||||
- **The open questions and the measurement notes are split too** (developers only, D66). `docs/20_OPEN_QUESTIONS.md`
|
||||
(4,467 lines, now 2,008) keeps its rules, §S24 and every entry not resolved; the 30 entries §S24 marks resolved
|
||||
moved, with their reasoning and in their order, to `docs/open-questions/closed-s.md` and `closed-h.md`, and a table
|
||||
at the end of each series lists them. `docs/spike-notes.md` (2,816 lines) is now the index of its 24 sections, each
|
||||
in its own file under `docs/spike-notes/`; a new measurement gets the next number, its own file and a row. Both
|
||||
rebuild their originals byte for byte, and the same gate holds their indexes to their files.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The NVIDIA driver line read the driver's mode in the wrong numbering.** The driver reports the mode an override
|
||||
set in NGX's own numbering, not the driver profile's: the owner's Silent Hill 2 session ran under the NVIDIA App's
|
||||
Ultra Performance (profile value 5) and the driver reported 3 — which the line printed as nothing, and a DLAA
|
||||
override's 5 would have printed as "Ultra Performance". Five comments in the native code called a quality byte of
|
||||
0 "NGX MaxPerf" — in the numbering that byte carries, 0 is "DLSS off" (comments only, no code changes).
|
||||
- **Opening a folder in Explorer** — the logs, the data folder, the licences, a bug report's zip and the folder named
|
||||
after a failed start — starts `explorer.exe` from the Windows folder by its full path, never a program of that name
|
||||
found on the search path, and always hands it the path in quotes (three of the five places passed it bare).
|
||||
- **What SonarCloud found that was real** (developers only): the one third-party GitHub Action is pinned to its
|
||||
commit; two string reads in native code are bounded by their buffer (the guard's rules-file path handed to the Agent,
|
||||
and the driver's branch name the NVAPI bridge copies); the pipe server's accept loop states that it ends only when
|
||||
cancelled; a launch's own session names its absent stop token (`CancellationToken.None`, with the reason) where it
|
||||
wrote `default` — the same value, now said on purpose; an unused overload of
|
||||
the process launcher that hid the other is gone; the identifier `module` (a C++20 keyword in some positions) is
|
||||
renamed in the hook layer — a rename only, no code changes; and a hook-overhead probe no longer uses a compound
|
||||
assignment on a `volatile`, which C++20 deprecates. The analyzers Dependabot updates in #314 flag the first-start
|
||||
window's own answer task and one test fake's synchronous wait; both are suppressed with their reasons, so that update
|
||||
can merge.
|
||||
- **The game-side log keeps every line a stop writes.** When hooking stopped on a game's own drawing thread — the
|
||||
capture agent's safety stop takes effect within one frame there — the Overlay's last write of its log could happen
|
||||
while that thread was still listing the hooks it removed, and the last of them never reached the file
|
||||
(`overlay-*.log`, the file a bug report carries). The last write now waits, at most two seconds, for the stop to
|
||||
finish and ends with a `STOP_FLUSHED` line; a line still being written is never printed half-done. Nothing changes
|
||||
on the per-frame path. This was the native test that went red under load since beta.9 (`fl_guard`'s log case),
|
||||
now run 20 times with every processor busy.
|
||||
@@ -0,0 +1,140 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.3] - 2026-09-21
|
||||
|
||||
**The third pre-release.** The same unsigned installer as before: verify its hash against `SHA256SUMS.txt`, then
|
||||
*More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **The terms changed, so the Legal Gate opens once after the update.** They now say plainly that this is beta
|
||||
software with bugs, that your PC must meet each game's own minimum requirements, and what the new guard bypass means.
|
||||
- **CPU load, system memory and (when the Agent runs as administrator with PawnIO) CPU temperature are recorded**, and a
|
||||
game's Trend tab can chart them, the GPU's load and power, VRAM and the ×FG factor across that game's sessions.
|
||||
Settings ▸ System shows this PC as FrameLedger records it.
|
||||
- **DLSS is named.** Titles that call DLSS directly read "Unknown upscaler"; they now read "DLSS (driver-reported)"
|
||||
where the NVIDIA driver reports it — including sessions you already recorded.
|
||||
- **A game imported from Steam could never hook** when the import picked a helper executable instead of the game
|
||||
(GIRLS' FRONTLINE 2 was one). The import picks the game now, and the game page shows the executable and can change it.
|
||||
- **The platform and engine tags were blank white boxes in the light theme.** Fixed.
|
||||
- **New, off by default, per game: "Bypass the anti-cheat guard (at your own risk)".** Read its warning. Your account
|
||||
can be permanently banned, and the developers accept no responsibility if you turn it on.
|
||||
|
||||
**Updating from `0.1.0-beta.2`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) before installing, as before.
|
||||
- On its first start the ledger migrates to schema 7 (the guard-bypass columns; nothing existing is rewritten).
|
||||
- **A game an earlier Steam import created for the wrong executable is not rewritten.** Open it, check the path under
|
||||
its name, and use *Change executable…* (hooking is turned off for it and must be enabled again), or remove it.
|
||||
- Sessions recorded before this version keep N/A for CPU load, memory and CPU temperature: nothing measured them.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **DLSS read "Unknown upscaler" on most titles while FSR was named.** Most DLSS titles call NGX directly, and no NGX
|
||||
hook may exist (the SDK's licence; `20_OPEN_QUESTIONS`), so the hook runs and sees nothing. The NVIDIA driver does
|
||||
report the feature per process, the Agent has stored that on every session since P2
|
||||
(`sessions.upscaler_driver_reported`) and the capture host has printed it since 2026-09-06 — **the App never read
|
||||
it.** It does now: where no hook named an upscaler and the driver reports NGX super resolution created and
|
||||
evaluated, the library, the session summary, the game page and the live card say **DLSS (driver-reported)** —
|
||||
attributed, identity only, never a quality. A hook's name still outranks it. Sessions already recorded show it too,
|
||||
because the column was always written. `unknown` itself now reads "Upscaler not identified". Nothing native changed.
|
||||
- **A measured DLSS preset is its name, not its number**: `DLSS Balanced`, not `DLSS 2` (`Domain.Metrics.UpscalerNames`,
|
||||
which `03_METRICS` had promised from the start). Only the Streamline route produces the byte; a value with no name
|
||||
is shown as stored. A preset derived from the render scale is still not shown — that is an open owner decision.
|
||||
|
||||
- **The Games card's platform and engine tags were empty white boxes in the light theme.** They were
|
||||
`ui:Badge Appearance="Secondary"`, whose WPF UI 4.3.0 trigger repaints the background only and keeps the default
|
||||
badge's on-accent foreground: near-white text on a near-white fill. They, and the edit dialog's "Detected" marker,
|
||||
are the App's own `TagPill` now, with the theme's secondary text; `ContrastTests` refuses a Secondary badge in App
|
||||
XAML beside the four palette appearances it already refused (`08_UI` §Contrast).
|
||||
- **A game imported from Steam could be a game that never hooks.** Steam names no executable, so the import guessed
|
||||
"the largest non-helper", and on GIRLS' FRONTLINE 2: EXILIUM that was the embedded browser
|
||||
`GF2_Exilium_Data\Plugins\ZFGameBrowser.exe`, not the 675 KB Unity player `GF2_Exilium.exe`. Everything downstream is
|
||||
keyed on the executable path, so hooking enabled on that row could never match the running game, while the same
|
||||
game added by its exe worked. The locator now ranks by the engines' own layouts (Unity `X.exe` beside `X_Data`,
|
||||
Unreal `*-Win64-Shipping.exe`), then by a name matching the install folder, then by size; it skips `X_Data\Plugins`
|
||||
and redistributables folders, knows `browser`/`webview`/`subprocess`/`analyzer`/`vconsole` as helpers, and walks four
|
||||
levels instead of three. Verified read-only over the owner's Steam library: GF2, Red Dead Redemption 2 (was the
|
||||
Rockstar launcher installer), Counter-Strike 2 (was `vconsole2.exe`), Rune Factory, Dying Light: The Beast (was
|
||||
nothing at all). **A row an earlier import created for the wrong executable is not rewritten**: remove it, or use
|
||||
the new button below.
|
||||
|
||||
### Added
|
||||
|
||||
- **A per-game "bypass the anti-cheat guard" switch, at your own risk (owner decision 2026-09-21).** Off by default,
|
||||
never global: there is no setting, no command-line switch and no rules-file field for it. Turning it on opens its
|
||||
own disclosure, which says what the guard found for that game, that anti-cheat treats a loaded DLL as tampering
|
||||
whatever it does, that **your account can be permanently banned without warning or appeal**, that FrameLedger does
|
||||
not hide and never will, and that **by turning it on you accept the entire risk yourself and the developers accept
|
||||
no responsibility or liability**. It is accepted only by ticking the acknowledgement AND typing `BYPASS`; Enter keeps
|
||||
the guard on. The Agent stamps it (the App writes nothing), keyed on the executable like consent; turning hooking
|
||||
off or the executable changing turns it off again. **It overrules the guard's judgement and nothing else**: the kill
|
||||
switch, a game that was merely added, a missing consent, a foreign payload, a 32-bit target, a failed injection and
|
||||
a Vulkan title the guard refuses all still refuse. The guard still runs every check and still reports what it
|
||||
found; the verdict is `AllowedUnderUserBypass`, never `Allow`. **How FrameLedger injects is unchanged** — the same
|
||||
documented `LoadLibraryW`, the DLL's real name and version info, one chokepoint file (CLAUDE.md rule 3). Every
|
||||
session started under it is marked, permanently, with what the guard found: in the sessions list, the session
|
||||
summary, the CSV and JSON exports (schema 0007: `games.guard_bypass_*`, `sessions.guard_bypassed` /
|
||||
`guard_bypass_family` / `guard_bypass_signal`). A session recovered after an Agent crash does not carry the mark.
|
||||
CLAUDE.md rule 2, `19_SAFETY`, `02_SPEC` FR-2.7, `SECURITY.md` and `tools/chokepoint-check.ps1`'s own description
|
||||
are amended with it. Japanese shows this dialog in English until a reviewer signs the translation.
|
||||
|
||||
- **CPU load, memory in use and (elevated) CPU temperature are measured.** `sessions.avg_cpu_load`, `avg_cpu_temp`,
|
||||
`max_cpu_temp` and `avg_ram_mb`, and the `cpu_load` / `cpu_temp` / `ram_mb` sensor series, were in the schema from
|
||||
0001 with no producer. The telemetry poller now reads the machine beside the GPU on the same 1 Hz tick: CPU time
|
||||
busy across every logical processor (`GetSystemTimes` — not Task Manager's frequency-scaled "utility") and physical
|
||||
memory in use, both unprivileged and opening no process. **CPU temperature is read only when the Agent runs as
|
||||
administrator with PawnIO installed, and has not been checked on real hardware yet**; everywhere else it is N/A,
|
||||
never 0. Sessions recorded before this keep their nulls; no migration. The live card carries CPU load and
|
||||
temperature (`SessionProgress.cpuLoadPct`, optional).
|
||||
- **One game's sessions over time, beyond the frame rate.** The game page's Trend tab gains average GPU load, average
|
||||
GPU power, max VRAM (game), average CPU load, max CPU temperature, average memory in use, and the **×FG factor**. A
|
||||
factor that is its session's steady state (rule 6) covers part of the session, so it is left out by default and
|
||||
drawn marked when "include mid-session changes" is on — never as the session's. The Sensors chart draws CPU
|
||||
temperature, CPU load and system memory; Compare gains average GPU load, average CPU load and max CPU temperature;
|
||||
the session summary gains GPU and CPU cards (average load · peak temperature).
|
||||
- **Settings ▸ System shows this PC** — processor, graphics card and driver, memory, Windows build, primary display —
|
||||
as FrameLedger records it with every session, with a Copy button; nothing is sent anywhere. The session summary
|
||||
shows that session's snapshot under its header, and `--diag` prints the machine's. The bug bundle is unchanged.
|
||||
|
||||
- **Game page: the row's executable is shown, and "Change executable…" re-points it.** The remedy for a wrong import
|
||||
guess used to be remove-and-add. The row comes back exactly as a new game would — hooking off, no consent, pre-scan
|
||||
not run — with consent revoked over the pipe first, as removal does; a block is never cleared by it, and a path
|
||||
another row owns (in the library, or removed with its sessions kept) is refused.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The terms say what an end user needs to hear, and must be accepted again.** `legal/DISCLAIMER.md` 2.2 -> **2.3**:
|
||||
a new §0 (**this is pre-release software — it certainly still has bugs, and the developer is not responsible for
|
||||
incidents that result**), §2A (the guard bypass, entirely at your own risk, no liability), §4A (**your PC must meet
|
||||
at least the minimum requirements the game's developer or publisher states — read them first; problems on a machine
|
||||
below them, or on unstable, overclocked or overheating hardware, are yours and not the developer's**) and §7A (back
|
||||
up your own data; builds are unsigned, download only from the project's Releases page and verify the hash; no
|
||||
affiliation with any game, platform or vendor; numbers are for your own information). `legal/EULA.md` 1.0 -> **1.1**
|
||||
says the same in §2A/§2B. The first-run Legal step shows a short plain-language summary of those points in en/vi/ja
|
||||
above the documents, which remain the terms. Because both versions moved, the Legal Gate opens once after the update.
|
||||
The accuracy block's Safety bullet no longer says "There is no override anywhere".
|
||||
- **Docs that had gone stale.** `legal/THIRD_PARTY_NOTICES.md` gains the test-time row it never had (xUnit.net v3 4.x
|
||||
under Apache-2.0, FluentAssertions 7.x and why it is pinned, NSubstitute, coverlet, Test.Sdk, Catch2);
|
||||
`16_WPFUI_SYNTAX` named a TFM this repository never built; `14_TESTING` still called Catch2 and the blocked toggle
|
||||
future work; README's status line said "pre-alpha" beside three pre-releases; `build.ps1` "skipped" the coverage and
|
||||
rules gates when their tools were missing, which its own header calls worse than no gate — a missing tool fails now.
|
||||
- **Two flaky tests, seen on CI the same day.** The native-log test slept a fixed 1500 ms and read the Overlay's log
|
||||
between two lines (it polls for the last one now); `ParentDumpTests` dumped a child process microseconds after starting
|
||||
it and got `ERROR_PARTIAL_COPY` (it waits for the child to finish loading). Neither was a product defect.
|
||||
- **A local native build no longer fails on an uncommitted change.** After the first tag `git describe --dirty`
|
||||
produces `v0.1.0-beta.2-2-g<12 hex>-dirty`, 35 characters against `FlShmHandshake::buildId`'s 31, so every CMake
|
||||
configure of a dirty tree was fatal and the workaround was "commit before you build". The id now falls back to an
|
||||
8-digit abbreviation with `+` for dirty when the long form does not fit; a release is a clean checkout at a tag and
|
||||
never takes the fallback. Still too long after that is still fatal.
|
||||
- **Dependencies, 2026-09-21.** The test framework moves from xUnit.net v3 3.2.2 to **4.0.1**, referenced as
|
||||
`xunit.v3.mtp-off` with `xunit.runner.visualstudio` 4.0.0: 4.0 makes Microsoft Testing Platform v2 the default of the
|
||||
plain `xunit.v3` package, and `build.ps1`'s gates are VSTest-shaped on purpose (the `XPlat Code Coverage` collector,
|
||||
the `results.trx` the struct-mirror gate and the 25-minute wall clock read), so the projects take the same 4.x
|
||||
framework through the variant xunit publishes for that. The tree carried no v2-era API; the one test change is a
|
||||
race 4.0.1's scheduler found on its first gate run: eight `App.Tests` classes write the process-wide `Strings.Culture`
|
||||
and ran in parallel, so `StringsTests` read "Settings" where it had just written `vi`. They share one collection now.
|
||||
Also: Dapper 2.1.86, Microsoft.Data.Sqlite / Microsoft.Extensions.Hosting / System.Diagnostics.EventLog 10.0.12,
|
||||
CsWin32 0.3.333, Roslynator 5.0.0, Meziantou.Analyzer 3.0.266, Microsoft.NET.Test.Sdk 18.10.1, NSubstitute 6.2.0.
|
||||
**Deliberately not moved:** `WPF-UI [4.3.0]` and `FluentAssertions [7.2.2]` (8.x is not an OSI licence), both pinned
|
||||
with their reasons in `Directory.Packages.props`. `legal/licenses/nuget/` is regenerated for the shipped packages
|
||||
that moved.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.4] - 2026-09-21
|
||||
|
||||
**The fourth pre-release: four faults found in the first day of `0.1.0-beta.3`.** The same unsigned installer: verify
|
||||
its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **Only one FrameLedger window now.** Starting the App while it is already running (a double-click, or the shortcut
|
||||
while it sits in the tray) brings the running one forward instead of opening a second one with a second tray icon.
|
||||
- **The safety texts follow your language.** In a Vietnamese UI the consent dialog, the refusal notices and the
|
||||
guard-bypass card were English.
|
||||
- **The guard bypass is honest about what it cannot do.** A game whose anti-cheat protects its process (ELDEN RING
|
||||
under Easy Anti-Cheat is one) cannot be opened by any other program, so FrameLedger cannot measure it with or without
|
||||
the bypass, and it will not try to get around that protection. beta.3 showed nothing at all in that case; this build
|
||||
shows a notice that says so, the bypass warning says it before you accept, and the game page no longer says
|
||||
"Hooking is disabled" beside a hooking switch that is on.
|
||||
|
||||
**Updating from `0.1.0-beta.3`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
> **Corrected the same evening.** This bullet went on to say that on 2026-09-21 "an install over a running Agent left
|
||||
> a half-replaced folder and the App failed to start three times". **That cause was a guess and the logs do not
|
||||
> support it**: nothing was installed between the three failed starts (20:59–21:01, `Could not load …
|
||||
> Microsoft.Data.Sqlite`) and the start that worked at 21:02. What Windows' own event log shows for that hour is a
|
||||
> failing external USB drive (the owner's report: a loose cable) and two restarts of the PC at 20:57 and 21:02. The
|
||||
> three failed starts are **unexplained**; the advice to stop the Agent before installing stands on its own.
|
||||
- The Disclaimer moved to 2.4 (one paragraph about the bypass), so the Legal Gate opens once.
|
||||
- No schema change. A bypass you already accepted stays on; the new warning text is shown the next time you turn one on.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A second App could be started beside the first.** Nothing enforced one instance: the owner's log of 2026-09-21
|
||||
shows two started 360 ms apart from one double-click — two windows, two tray icons, a second log file, both writing
|
||||
one ledger — and with "minimize to tray" on, every click on the shortcut made another. The App now claims its data
|
||||
folder at start (`Services.SingleInstance`, a named mutex and event keyed on the folder); a later start hands over to
|
||||
the running one, which brings its window forward, and exits. `--diag` still runs beside a running App.
|
||||
- **A Vietnamese (or Japanese) UI showed the safety texts in English** — the consent dialog, the refusal notices, and
|
||||
the whole guard-bypass card in beta.3's screenshot. `FrameLedger.Shared`'s string family was never given the UI
|
||||
culture and fell back to the thread's, which the App's async start does not pass to later dispatcher work.
|
||||
`App.ApplyCulture` sets both families now. (Japanese safety text is still the English by design, until reviewed.)
|
||||
- **Under the guard bypass the game page said "Hooking is disabled for this game: …" beside a hooking switch that was
|
||||
on.** The finding stays on the page and now reads "The guard found: … You chose to bypass it for this game".
|
||||
- **With the bypass on, a game protected by a kernel anti-cheat produced nothing at all** — no session, and a toast
|
||||
reading `InjectFailed: TargetAmbiguous`. Measured on the owner's ELDEN RING (Easy Anti-Cheat): the anti-cheat's
|
||||
driver closes the game's process to other programs, the resolver could read no candidate, and it called that
|
||||
"ambiguous". It is `TargetUnreadable` now, and it reaches the user as a persistent notice that says what happened,
|
||||
that nothing was injected or measured, and that **the bypass does not change this and FrameLedger will not work
|
||||
around another product's protection** (rule 3). The bypass disclosure says the same before it is accepted (its
|
||||
version is `guard-bypass-dialog/2`), and so does `legal/DISCLAIMER.md` §2A (2.3 -> **2.4**, so the Legal Gate opens
|
||||
once). The same reason covers a game running as administrator while the Agent does not.
|
||||
- The refusal notices said "there is no way to override this"; they name the per-game bypass switch and whose risk it is.
|
||||
|
||||
### Changed
|
||||
|
||||
- The Agent's session log line names what the guard said when it was not a plain allow
|
||||
(`…; guard=BlockedService/Easy Anti-Cheat/EasyAntiCheat_EOS`), and `started-under-bypass=` for a bypassed start. A
|
||||
`SafetyUnhook` on the owner's machine left no trace of WHICH finding fired; the pipe event carried it and the log,
|
||||
which is what survives, did not.
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.5] - 2026-09-22
|
||||
|
||||
**The fifth pre-release: the guard override is gone, Tier 2 exists, and a drive that changes its letter is followed.**
|
||||
The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for
|
||||
a user:
|
||||
|
||||
- **The "Bypass the anti-cheat guard" switch is removed.** Where FrameLedger finds anti-cheat in a game — before it
|
||||
injects, when a session starts, or during one — it refuses and **turns hooking off for that game**, says so in the
|
||||
notice and on the game's page, and offers no way to turn it back on for that executable. The terms say so
|
||||
(Disclaimer 2.5, EULA 1.2), so the Legal Gate opens once after the update.
|
||||
- **Sessions that could not be hooked are recorded now.** A refused or hooking-off game gets a T2 row with its
|
||||
duration, hardware telemetry and the reason — the summary says why ("the guard refused — …", "hooking was off for
|
||||
this game", "Windows would not let FrameLedger open the process"). Until now every such session was thrown away
|
||||
within a second.
|
||||
- **A hooking-off entry that runs as administrator (Borderless Gaming, imported from Steam) no longer gets the
|
||||
"anti-cheat driver" notice**, and Steam's tools are no longer imported as games. An entry you already have for one
|
||||
stays until you remove it.
|
||||
- **A drive that changes its letter no longer loses your games.** The Agent finds the same file under the new letter
|
||||
and moves the entry to it with its consent kept — within about 15 s in the background, at once when you launch the
|
||||
game, and when you click the hooking switch. The game's page says when its executable is not where the entry points.
|
||||
|
||||
**Updating from `0.1.0-beta.4`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0008 drops the five columns of the removed switch; the database opens in place, nothing else changes.
|
||||
- Entries whose switch was on lose it; if the guard blocked such a game, its hooking is off and its page says why.
|
||||
|
||||
### Removed
|
||||
|
||||
- **The per-game guard override ("Bypass the anti-cheat guard") is gone** — owner decision 2026-09-22, two pre-releases
|
||||
after it arrived. Its first real use could not reach a process an anti-cheat driver protects, and where it could
|
||||
inject it only exposed the user to the risk its own warning described. Removed entirely: the native entries
|
||||
(`FlGuardedInjectAcknowledged`, its WhenReady twin, `FlGuardIsJudgement`, reason 28), the `SetGuardBypass` message, the
|
||||
App's card and dialog, the session mark and its export line, the `Safety_Bypass_*` strings, and schema 0007's five
|
||||
columns (schema 0008 drops them — the first `DROP COLUMN` in the migration set). Sessions that ran under it keep
|
||||
`guard-bypass=` in their notes. CLAUDE.md rule 2 reads "there is no override" again; Disclaimer 2.5 and EULA 1.2 say
|
||||
so, so the Legal Gate opens once.
|
||||
|
||||
### Added
|
||||
|
||||
- **Tier 2 exists now: a session that could not be hooked is recorded — duration, hardware telemetry and the
|
||||
reason — instead of being thrown away.** Until 2026-09-22 every refusal returned within a second and the 30 s
|
||||
minimum discarded it (`Discarded (tier 2, exit=Normal, frames=0)` for every one in the owner's log), so "the session
|
||||
is still recorded" in the notice was false. The loop now holds a refused session open, ticking the telemetry poller,
|
||||
until the game exits; the row lands as T2 with N/A everywhere a measurement would be, and its summary says why
|
||||
("Why: the guard refused — Easy Anti-Cheat (…)", "Why: hooking was off for this game", "Why: Windows would not let
|
||||
FrameLedger open the process"). The unshipped operator host keeps returning at the refusal.
|
||||
- **A drive that changes its letter no longer loses your games.** When the drive holding a library comes back as
|
||||
another letter (the owner's external drive: `D:` one evening, `H:` the next morning), every game on it read
|
||||
"executable unreadable" and a game launched from the new letter ran as a stranger with no consent. The Agent now
|
||||
finds the same file — same size, same modified time, under exactly one other drive letter — and moves the entry to
|
||||
it with consent, block and detection kept: within about 15 s in the background sweep, at once when such a game is
|
||||
launched, and when you click the hooking switch. The game's page says when its executable is not where the entry
|
||||
points. *Change executable* is still the way to point an entry at a different file.
|
||||
- **Steam's tools are no longer imported as games**: Steamworks Common Redistributables, Borderless Gaming, Wallpaper
|
||||
Engine, SteamVR, the Proton and Steam Linux Runtime entries and Blender are skipped by app id. A row you already have
|
||||
for one of them stays until you remove it.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A hooking-off entry that runs as administrator no longer gets the "anti-cheat driver" notice.** Borderless Gaming,
|
||||
imported from Steam with hooking off, produced a red "hooking refused" notice on every launch: the Agent tried to
|
||||
open its process before it looked at whether hooking was on. Hooking-off is decided first now — no process is
|
||||
opened, no resolver, no gate — and the row gets a quiet Tier-2 session like any other hooking-off game.
|
||||
|
||||
### Changed
|
||||
|
||||
- **A finding turns the game's hooking off, wherever the guard makes it** (`19_SAFETY` §What a finding does to the game). The
|
||||
pre-scan always did this; now a finding at a session's start or at the 30 s re-scan writes the same block — hooking
|
||||
off, the reason on the row, the toggle disabled on the game's page — when it names an anti-cheat *in the game* (its
|
||||
process, its folder, its title lists). A machine-wide driver or service refuses that session only. The notice says
|
||||
"Hooking has been turned off for this game", the session's notes carry `hooking-turned-off=`, and `CaptureRefused` /
|
||||
`SafetyUnhook` carry `hookingTurnedOff`.
|
||||
- **`0.1.0-beta.4`'s notes named a cause they had no evidence for, and are corrected in place** (see its *Updating*
|
||||
section). The owner reported afterwards that the external USB drive holding the Steam library had a loose cable that
|
||||
evening. Windows' System and Application logs for 2026-09-21 agree and re-date the day's symptoms: disk resets and
|
||||
paging errors on that drive from 20:42; `start_protected_game.exe` (20:56) and `GF2_Exilium.exe` (21:45) both
|
||||
ended with `0xc0000006`, an in-page I/O error — the drive, not FrameLedger, and **FrameLedger had injected nothing
|
||||
into ELDEN RING in any run**; the Agent's "executable unreadable" for all 46 titles and the two pipe timeouts at
|
||||
21:12–21:13 sit inside a burst of 30 disk errors. **What the drive does NOT explain, and beta.4's fixes stand on:**
|
||||
Easy Anti-Cheat's own log says "successfully loaded in-game" for ELDEN RING at 21:29:28, the second the resolver
|
||||
found a process it could not open (`TargetUnreadable`); the two App instances started 360 ms apart at 21:07; the
|
||||
English safety texts and the contradictory line are in the screenshot itself.
|
||||
|
||||
@@ -0,0 +1,96 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.6] - 2026-09-23
|
||||
|
||||
**The sixth pre-release: a game is recorded under its own entry, one entry per game after a drive changes its
|
||||
letter, a game that is not measured is shown while it runs, and RE Engine and FromSoftware games are detected.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
|
||||
user:
|
||||
|
||||
- **Another game's `Game.exe` is no longer recorded under your entry.** A process that matches an entry by file name
|
||||
only starts nothing — unless it is that entry's own executable on a drive that changed its letter — so an RPG Maker
|
||||
game can no longer be recorded under another RPG Maker game's name, twice, as *HELLO, HELLO WORLD!* was under
|
||||
*Flower in Us*.
|
||||
- **A game that is not measured is shown while it runs.** Hooking off, refused by the guard, or a process Windows
|
||||
would not open: the Dashboard shows the game, the time and the temperatures, says why nothing is measured, and the
|
||||
tray turns to recording-only — until now it said "Nothing is being captured." for as long as the game ran.
|
||||
- **One entry per game when a drive changes its letter.** Two entries for the same executable under two letters
|
||||
merge on their own (the older one stays, with both histories); a game updated while its drive had another letter is
|
||||
followed with hooking off; the library import no longer adds a game again under the new letter.
|
||||
- **A game removed while it runs keeps its session** (under the entry that holds its executable), and a session file
|
||||
left behind can no longer stop the Agent at every start.
|
||||
- **RE Engine and FromSoftware games are detected**, engines are shown by name, and a game added by hand whose
|
||||
executable is `Game.exe` is named after the game.
|
||||
|
||||
**Updating from `0.1.0-beta.5`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- No schema change; the database opens in place. Every game is re-detected once (rules `2026.09.2`).
|
||||
- Session files in `%LOCALAPPDATA%\FrameLedger\tmp` that beta.5 could not store are stored at the Agent's first start —
|
||||
under the entry that holds their executable — or dropped with a line in `agent-*.log`; the Agent keeps running either
|
||||
way.
|
||||
- An entry that a beta.5 file-name match created for another game keeps its wrong name until you rename it (*Edit…*)
|
||||
or remove it; its executable path says which game it is.
|
||||
- A game whose **folder** moved — not only its drive letter — now records nothing until *Change executable* points its
|
||||
entry at the new file.
|
||||
|
||||
### Added
|
||||
|
||||
- **RE Engine and FromSoftware games are detected.** Capcom's RE Engine titles (RESIDENT EVIL 2/3/4/7/Village, Devil
|
||||
May Cry 5, Monster Hunter Rise/Wilds, Street Fighter 6, Dragon's Dogma 2, Onimusha…) by their `re_chunk_000.pak`
|
||||
archive; FromSoftware's (DARK SOULS II/III, ELDEN RING, Sekiro…) by their `.bhd` + `.bdt` archive pairs. Both are
|
||||
relative signals — a file layout, not a proof — like every engine rule. Every game in the library is re-detected on
|
||||
the next sweep. Engines are now shown by name ("RPG Maker MV/MZ", "Unreal Engine") instead of the rule's id
|
||||
(`rpgmaker_mv`). A game added by hand whose executable says nothing (`Game.exe`) is named after the game — RPG
|
||||
Maker's own title when the folder carries one, else its folder — instead of "Game".
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Another game's `Game.exe` no longer runs under a library entry — no wrong name, no second session.** On
|
||||
2026-09-23 00:16 *HELLO, HELLO WORLD!* (itch) started its RPG Maker runtime, `swiftshader\Game.exe`, and the Agent
|
||||
matched it by FILE NAME to the only entry named `Game.exe`, *Flower in Us*: it recorded the session under that name,
|
||||
which created a new "Flower in Us" entry at HHW's path, and an NW.js child process then matched the new entry and
|
||||
started a second session beside the first (57 s and 56 s). A process that matches an entry by file name only now
|
||||
starts nothing — unless it is that entry's own executable on a drive that changed its letter, in which case the entry
|
||||
follows it as before — and the log says once that it is not in the library. The same match can no longer move an
|
||||
entry onto another game whose `Game.exe` has identical bytes (every RPG Maker MV game ships the same one). One session
|
||||
per executable, whatever id its entry has; a session that could not be hooked is timed by its own executable instead
|
||||
of any process with its file name; the resolver says in the Agent's log why a process could not be read; an
|
||||
unreadable entry is logged once instead of every 15 s. **Changed:** a game whose folder moved records nothing until
|
||||
*Change executable* points its entry at the new file. The "Flower in Us" entry the old match created stays until you
|
||||
rename it (it points at HHW's `swiftshader\Game.exe`, the file to measure HHW by) or remove it.
|
||||
|
||||
- **One entry per game after a drive letter changes — the two side by side become one.** When the owner's USB drive
|
||||
came back as `H:` for a morning, a second entry was made for each game played from it, and once the letter was back
|
||||
neither entry could move onto the other's path: two of each game, and "could not be moved" in the log every 15 s.
|
||||
Now the Agent merges two entries for the same executable (same path on two letters, same size and modification
|
||||
time): the entry made first stays, the other's sessions join it, a block on either is kept, and no consent moves
|
||||
between them — it waits while either game runs. A game whose executable changed on the new letter (it was updated
|
||||
meanwhile) is followed with hooking off, as *Change executable* does; turn hooking on again to measure it. The
|
||||
library import no longer adds a game again when it is already in the library under another drive letter. And a
|
||||
database error during the Agent's 15 s library pass no longer stops the Agent.
|
||||
|
||||
- **A game removed from the library while it runs no longer loses its session — or stops the Agent at the next
|
||||
start.** On 2026-09-22 23:26 and 2026-09-23 00:25 a GIRLS' FRONTLINE 2 session ended `FAULTED` on the database's
|
||||
foreign key: its entry had been removed (and re-imported) while the game ran, and the session was written under the
|
||||
id it started with. Each left a `.partial` file, and the recovery that runs at every start would have failed on it
|
||||
the same way — with no guard, so the Agent's host would have stopped at every start and nothing would have been
|
||||
captured. Now the session is stored under the entry that holds its executable when the one it started with is gone
|
||||
(the re-imported entry); when no entry does — the game was removed with its sessions — it is dropped with a log line
|
||||
that says so. Recovery never throws: a file it cannot finalize is set aside as `<guid>.partial.failed`, kept for a bug
|
||||
report, and the next file is recovered. The `FAULTED` and end-of-session log lines now name the session, the game and
|
||||
its executable, and the Agent's host logs its own warnings and errors into `agent-*.log`.
|
||||
|
||||
- **A game that is recorded without measuring is shown while it runs.** A game with hooking off, one the guard
|
||||
refused, or one whose process could not be read is recorded (duration, sensors, the reason) since beta.5 — but the
|
||||
Agent announced only hooked sessions, so for as long as such a game ran the Dashboard said "Nothing is being
|
||||
captured." and the tray stayed idle. Now the live card shows it with the T2 badge, the elapsed time, the
|
||||
temperatures, "Recording duration and sensors only — nothing is measured." and why, in the sentence its summary will
|
||||
use (no FPS readout: nothing is measured, so nothing is shown); the tray turns to recording-only; the refusal notice
|
||||
appears when the game starts rather than when it exits. A Dashboard opened after a game started shows it at once
|
||||
(it used to wait for the next start), a session running when the App connects is in the tray, the notice after a
|
||||
session names that session's game (it could name the previous one), a session that fails is let go of instead of
|
||||
staying on the card, and an update downloaded after a session ends is ready to install instead of waiting for the
|
||||
App to reconnect. A game whose executable changed since hooking was turned on — after a store update, usually — now
|
||||
says so in its summary instead of `RefusedConsentMissing`.
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.7] - 2026-09-23
|
||||
|
||||
**The seventh pre-release: a program in the library can be left unrecorded, and Steam's own tools already are.** The
|
||||
same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a
|
||||
user:
|
||||
|
||||
- **The game page has a Recording switch.** Off, FrameLedger does not watch for that program at all — no session, no
|
||||
measurement, no injection — and a session of it that is running stops; sessions already recorded stay. The library
|
||||
card says **Not recorded**. Use it for a utility that starts with Windows: until now every program in the library was
|
||||
recorded whenever it ran, at every boot.
|
||||
- **Steam's own tools already in your library start with it off** — Borderless Gaming, Wallpaper Engine, SteamVR,
|
||||
Blender, the Steam runtimes and Proton — so a tool imported before 0.1.0-beta.5 stops being recorded without you
|
||||
doing anything.
|
||||
- **The Privacy Policy (2.3) and the Disclaimer (2.6) are updated**, so the Legal Gate opens once after the update.
|
||||
|
||||
**Updating from `0.1.0-beta.6`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0009 adds one column; the database opens in place, and the Steam tools above are switched off once.
|
||||
- Sessions a tool recorded before stay in its history; to remove them, remove the entry with *Delete sessions too* —
|
||||
the import will not add it again.
|
||||
|
||||
### Added
|
||||
|
||||
- **A library entry can be left unrecorded.** Borderless Gaming starts with Windows, and every program in the library
|
||||
was recorded whenever it ran — so each boot added a session of it, for as long as it ran, to the playtime totals. The
|
||||
game page now has a **Recording** switch: off, FrameLedger does not watch for that program at all — no session, no
|
||||
measurement, no injection — and a session of it that is running stops (sessions already recorded stay). The library
|
||||
card says **Not recorded**. Entries an earlier import made for Steam's own tools (Borderless Gaming, Wallpaper Engine,
|
||||
SteamVR, Blender, the Steam runtimes and Proton) start with it off; the import has skipped them since 0.1.0-beta.5.
|
||||
The Privacy Policy (2.3) says so — a program whose recording is off is not watched — and the Disclaimer (2.6) carries
|
||||
the updated accuracy statement, including the correction made in 0.1.0-beta.6; the Legal Gate shows both once after
|
||||
the update. Schema 0009 adds one column; the database opens in place.
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.8] - 2026-09-25
|
||||
|
||||
**The eighth pre-release: anti-cheat is found before you ask, a session says what the game and the driver were, and
|
||||
a frame-generation session's numbers and charts are the application's.** The same unsigned installer: verify its
|
||||
hash against `SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **Anti-cheat is looked for harder, and before you ask.** Twenty-two families (74 entries), any kernel driver in a
|
||||
game's folder, and per-title lists by Steam app id and executable name. The Agent checks every game in your library
|
||||
on its own, turns hooking off for those with anti-cheat, and their pages show what was found instead of the hooking
|
||||
switch. Their sessions are still recorded, with play time and sensors.
|
||||
- **A game's page says what its files say** — 64-bit or 32-bit, the file and store versions, the DLSS / FSR / XeSS
|
||||
libraries it ships — and a 32-bit game's hooking cannot be turned on.
|
||||
- **NVIDIA App overrides are shown**: each session records the driver profile the game ran under (DLSS preset and
|
||||
mode, frame generation, Smooth Motion), read from the driver and never changed.
|
||||
- **Reasons read as what they are**: End task is not a crash, a refusal says what happened, a launch that could not
|
||||
start says why, a missing executable says whether its drive is disconnected.
|
||||
- **Trend works on first open**, with Native and Presented FPS as two metrics, and FPS can show two decimals
|
||||
(Settings ▸ Window).
|
||||
- **A frame-generation session's lows, median and stutter are over application frames**, a pause no longer counts as
|
||||
one long frame, and the charts draw what they say — including the sensors of a session that was not hooked.
|
||||
- **The Privacy Policy (2.4) is updated**, so the Legal Gate opens once after the update: it now names what the
|
||||
software reads to check every library game for anti-cheat, the version information of the game's files, and the
|
||||
NVIDIA driver's settings for your games — all on your PC, none of it sent anywhere.
|
||||
|
||||
**Updating from `0.1.0-beta.7`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schemas 0010–0013 add columns; the database opens in place.
|
||||
- Shortly after the Agent starts it checks every game in your library for anti-cheat, once; a game where it finds
|
||||
some has its hooking turned off for good, with a notice if hooking was on.
|
||||
- Sessions recorded before keep the numbers they were stored with; the corrected lows and the in-step sensor overlay
|
||||
apply to sessions recorded from now on.
|
||||
|
||||
### Added
|
||||
|
||||
- **FrameLedger finds the anti-cheat games in your library on its own, and hides their hooking switch** (owner decision
|
||||
2026-09-25). The Agent now scans every game in the library for anti-cheat — once, and again whenever the rules or the
|
||||
game's executable change — where until now it scanned only a game someone asked to hook, so most games had never
|
||||
been scanned at all. A game it finds anti-cheat in has its hooking turned off for good, as any finding does, and a
|
||||
notice says so when hooking had been on. The library card says **Anti-cheat**; the game's page says what was found —
|
||||
"BattlEye — its module BEClient_x64.dll was loaded in the game", "Easy Anti-Cheat — its folder EasyAntiCheat ships
|
||||
with the game", in your language — in place of the Hooking switch, which could only be refused. Settings ▸ Capture ▸
|
||||
*Hide hooking on anti-cheat games* (on by default) brings the disabled switch back beside the finding. Sessions of
|
||||
such a game are still recorded, with play time and sensors. The scan reads the game's files only: it opens no process
|
||||
and decides nothing on its own — every session start still runs the full check. Schema 0010 adds three columns; the
|
||||
database opens in place, and the first scan of the library runs when the Agent starts.
|
||||
- **The game page has a Details card: what the game's files say about it.** Whether the executable is 64-bit (x64),
|
||||
32-bit (x86), ARM or .NET "any CPU"; its file and product versions; the store's build ("Steam build 20374416" — the
|
||||
subtitle labels it that way too, instead of a bare number); the engine; and the upscaler and frame-generation files
|
||||
it ships with their versions — "DLSS: nvngx_dlss.dll 3.7.10.0", Streamline, FSR, XeSS. FSR is named by its file: its
|
||||
DLL's version is the SDK's, and FrameLedger does not guess which FSR that is. The capture agent reads every game in
|
||||
the library once after the update. Schema 0011 adds four columns; the database opens in place.
|
||||
- **A session's summary lists the libraries the game had loaded** — recorded since the first beta and shown nowhere
|
||||
until now — and says when one differs from the copy the game ships ("nvngx_dlss.dll 310.2.1.0 (the game ships
|
||||
3.7.10.0: another copy was loaded, for example by the driver or the NVIDIA App)").
|
||||
- **FPS with two decimals** (Settings ▸ Window ▸ *Show FPS with two decimals*, off by default): every FPS figure reads
|
||||
"62.40" instead of "62". Whole numbers now round half up (62.5 is 63); they rounded half to even.
|
||||
- **FrameLedger says when the NVIDIA App overrides a game's DLSS.** Each session now records the NVIDIA driver profile
|
||||
the game ran under — read from the driver's own settings, never from the game — and its summary says what that
|
||||
profile overrides: "NVIDIA profile “…”: DLSS override (preset K, Quality) · Frame Generation override (×4)", Ray
|
||||
Reconstruction, Streamline's override, a forced frame-generation mode, Smooth Motion. It also says what the driver
|
||||
reported applying inside the game ("DLSS DLL chosen by the driver · preset K · Quality"), and the game page's Details
|
||||
card names the overrides from the newest session. These are the driver's settings, not measurements: what FrameLedger
|
||||
measured is shown as before. FrameLedger only reads these settings; it never changes them. Schema 0012 adds one
|
||||
column; the database opens in place.
|
||||
- **A 32-bit game's hooking switch cannot be turned on, and the page says why**: FrameLedger's hook runs in 64-bit
|
||||
games only. Until now the switch turned on and every launch was refused by the guard. A 32-bit game whose hooking
|
||||
was already on has it turned off the first time the capture agent reads it; its sessions are still recorded, with
|
||||
play time and sensors.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The anti-cheat blocklist names twenty-two families, twice as many, most through more than one signal.** New:
|
||||
EA AntiCheat, Activision Ricochet (`randgrid.sys` and its `atvi-randgrid_*` services — the family 19_SAFETY carried
|
||||
as "no data yet" since August), NetEase Anti-Cheat, NetEase Yidun, Nexon Game Security (BlackCipher), TenProtect,
|
||||
AhnLab HackShield, EQU8, Anybrain, FredaikisAntiCheat and Roblox Hyperion. Existing families gained the groups they
|
||||
lacked: BattlEye's driver `BEDaisy.sys` and its services, FACEIT's and ESEA's drivers and services, HoYoverse's
|
||||
`HoYoKProtect.sys` (which the `mhyprot` prefix never matched), Xigncode3's driver and service, Denuvo Anti-Cheat's
|
||||
driver, GameGuard's folder, files and service, EAC's `start_protected_game.exe` launcher and setup files. 19 entries
|
||||
became 74 (rules `2026.09.3`). Every new name is documented — SteamDB's file-detection rules (MIT), the vendors'
|
||||
support pages, LOLDrivers, DRML — and none is measured on a real title yet; each entry's `note` says which. Three
|
||||
services are deliberately left out because they run outside play and would refuse every session on the machine:
|
||||
`EAAntiCheatService`, PunkBuster's `PnkBstrA`, and Denuvo's update service.
|
||||
- **Check 3 is live in both halves, and the per-title lists are seeded** (rules `2026.09.4`, owner decision
|
||||
2026-09-25). The store half reads the store's own files through a seam the guard owns — `appmanifest_*.acf` in the
|
||||
Steam library that holds the game, `goggame-<id>.info` for GOG — so nothing is handed in by a caller and nothing is
|
||||
read from the game. 30 Steam app ids and 33 executable names across nine families are listed: Valve's VAC titles
|
||||
(CS2, Dota 2, TF2, Deadlock and the older ones), VALORANT and League of Legends, Roblox, Blizzard's online titles,
|
||||
Call of Duty, Marvel Rivals, NARAKA, FragPunk, Once Human, Delta Force, Arena Breakout: Infinite, HoYoverse's games,
|
||||
Battlefield 2042/6 and EA SPORTS FC 25/26 — the titles whose anti-cheat leaves nothing of the game's own for the
|
||||
other checks to find. A game no store names is not refused by this half; a Steam library whose manifests cannot be
|
||||
read is. Both lists are floored like the families, so a rules file can add a title and never take one off, and the
|
||||
validator refuses names engines share (`Game.exe`, `Client-Win64-Shipping.exe`…). The AreWeAntiCheatYet bulk list was
|
||||
considered and declined: community data that outlives a game's anti-cheat would turn hooking off for good.
|
||||
- **Any kernel driver in a game's folder counts as anti-cheat** (owner decision 2026-09-25). A `*.sys` file in the
|
||||
install tree that no rule names is reported as "Kernel driver in the game folder" and turns that game's hooking off,
|
||||
like any finding. Every driver found in a game so far was an anti-cheat's; this catches the next one before anyone
|
||||
names it. It is code, so no rules file can remove it — and a game that ships a driver for another reason loses
|
||||
hooking with no way back, which is the trade the owner took.
|
||||
- **FSR 3's and XeSS's DX11 libraries count as "Supports FSR" / "Supports XeSS"** (rules `2026.09.5`):
|
||||
`ffx_fsr3_x64.dll` / `ffx_fsr3upscaler_x64.dll` and `libxess_dx11.dll` matched no rule before.
|
||||
- **The guard holds 256 blocklist entries instead of 64** (2 × 74 no longer fitted the worst case of the compiled-in
|
||||
floor plus a drifted file). The parsed rules are ~530 KB, so they are now reset in place instead of being copied from
|
||||
a temporary: the Vulkan layer parses them on whichever of a game's threads creates its Vulkan instance, and a
|
||||
temporary that size on a small thread stack would crash the game. The native tests hold them on the heap.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A frame-generation session's lows, median, min / max, σ and stutter count are over application frames**, as
|
||||
`03_METRICS` always said they were: they were computed over every present, generated ones included, so a ×2
|
||||
session's 1% low could sit above its native average, and a game that submits its generated frames in a burst —
|
||||
the owner's Onimusha demo capture, DLSS frame generation ×3 — read a median of 2,073 FPS at a native 60. Sessions
|
||||
recorded before this release keep the numbers they were stored with; their charts use the corrected rule.
|
||||
- **Pausing capture no longer puts a pause-long frame and the paused minutes into the session.** The first frame
|
||||
after a resume was measured from the last one before the pause; it follows a gap now, and every average is over
|
||||
the time that was measured. Records lost when the capture agent fell behind are left out of that time the same way,
|
||||
so an average reads the rate the game ran at rather than the survivors spread over the lost time.
|
||||
- **The charts are honest about what they draw.** The frametime chart's default line is application frame to
|
||||
application frame (it was each frame's interval to the generated frame before it), of the one swapchain the
|
||||
statistics are over (two swapchains' intervals were drawn interleaved); the every-present line no longer draws
|
||||
0 ms frames after gaps and says that presents are timed at submission; segments are labelled with their settings;
|
||||
the sensor overlay is in step with the frames (it was drawn from the session's start, tens of seconds early —
|
||||
schema 0013 records where the first frame sits, so sessions recorded before keep the overlay off). The histogram
|
||||
is binned over the 0.5th–99.5th percentile with its bars centred on their bins; the percentile curve and its
|
||||
1% / 0.1% low markers are drawn only where the session has the frames for them, the rule the stat cards follow.
|
||||
The Sensors charts put power on a watt axis, call the memory plot *Memory*, leave out VRAM readings of 0, give
|
||||
every line its own colour in the light theme too, and chart **sessions that were not hooked** — their sensors
|
||||
were recorded and shown nowhere.
|
||||
- **A game's page updates when one of its sessions finishes** — its sessions, trend and header kept what the page
|
||||
opened with until it was left and reopened.
|
||||
- **The Trend tab was blank the first time a game's page opened.** It is drawn at once, on a date axis that keeps its
|
||||
label and the theme's colours. "Average" is two metrics now — Native FPS and Presented FPS — so a line never mixes
|
||||
the two, and never shows a presented rate that includes generated frames. Temperatures, loads, power and memory
|
||||
include sessions recorded without hooking; points that describe only part of their session are drawn hollow; several
|
||||
hardware changes on one day are one marker.
|
||||
- **A steady-state frame-generation factor always shows the share of the session it covers** — the average card,
|
||||
Compare and the Sessions grid's FG× column dropped it. The game header's "Lifetime average" was the last measured
|
||||
session and is labelled so.
|
||||
- **Compare**: the best value is highlighted in the accent colour (it was only bold), two values that read the same are
|
||||
both best, CPU and GPU load are not ranked, the percentile chart spans 0–100 again, and exported PNGs have a solid
|
||||
background.
|
||||
- **Ending a game with End task is no longer a "crash".** Every non-zero exit code was one, and Task Manager leaves 1.
|
||||
A crash is now an exception's exit code or Windows' own crash record, and the session summary says how each session
|
||||
ended: "crashed (0xC0000005 access violation)", "ended with exit code 1 — what End task and taskkill leave". The
|
||||
crash safety still counts an early abnormal exit of either kind, so hooking still turns itself off after two in a row.
|
||||
- **Reasons read as what they are.** Every way a session can end has its own sentence, a refusal that names no
|
||||
anti-cheat says what happened ("the game is 32-bit…", "the game's process could not be opened") instead of calling
|
||||
its detail "detected in this game", a launch that could not start says why (for example "the game requires
|
||||
administrator rights"), and a missing executable says whether its drive is disconnected or the file is gone. A
|
||||
refusal's details were stored so that a detail could be read as an anti-cheat's name; they are stored in three fixed
|
||||
places now, and older sessions are read correctly.
|
||||
- **The NVIDIA bridge's native test could not fail on a machine with an NVIDIA GPU.** It was registered to pass on
|
||||
its "which branch" line alone, which makes ctest ignore the exit code; its reference-counting check had been failing
|
||||
on every GPU machine unseen. The check is corrected and a failed assertion now fails the test.
|
||||
- **Turning hooking on for an Unreal game now sees its `EasyAntiCheat` folder.** The scan that runs when hooking is
|
||||
enabled was given the executable's own folder — `<game>\<Project>\Binaries\Win64\` for Unreal titles — and scanned
|
||||
exactly that, while `EasyAntiCheat\` sits at the game's root. The session-time scan always looked at the root, so no
|
||||
injection was ever allowed by the gap, but the toggle could be switched on and the refusal came only at launch. The
|
||||
guard now takes the executable and finds the root itself, and also checks the executable's name and its store id.
|
||||
- **A game blocked for anti-cheat no longer offers "Turn hooking back on" after a crash auto-disable.** The button
|
||||
could only be refused.
|
||||
- **19_SAFETY's fixture rule is enforced for every family, not eleven.** A generated test walks every value of the
|
||||
shipped seed and requires it to match its own family in its own group — which also catches a later row that an
|
||||
earlier prefix shadows. The rules file's note that called XIGNCODE3's `x3.xem` "not a loadable module" is corrected:
|
||||
XIGNCODE3 loads it as its loader, so the modules group names it too.
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66). CHANGELOG.md lists every release. -->
|
||||
|
||||
## [0.1.0-beta.9] - 2026-09-26
|
||||
|
||||
**The ninth pre-release: one narrow exception you can make yourself for a game whose only anti-cheat runs in user
|
||||
mode and that FrameLedger has measured before.** The same unsigned installer: verify its hash against
|
||||
`SHA256SUMS.txt`, then *More info → Run anyway*. What changed for a user:
|
||||
|
||||
- **A user-mode anti-cheat exception, per game, off by default** (Settings ▸ Capture). It is offered only where the
|
||||
only anti-cheat found runs entirely in user mode — no driver or service, no driver file in the game's folder — the
|
||||
game is on no title list, and FrameLedger has measured it hooked successfully at least twice. You make it one game
|
||||
at a time, after a disclosure that states the ban risk; the guard still runs every check under it and ends it on
|
||||
anything new, a crash or safety stop under it, or a game update. Sessions under it are marked.
|
||||
- **The Disclaimer (2.7) and the EULA (1.3) say so**, so the Legal Gate opens once after the update. The Privacy
|
||||
Policy is unchanged.
|
||||
|
||||
**Updating from `0.1.0-beta.8`:**
|
||||
|
||||
- Quit the App (tray icon → Exit) and end `FrameLedger.Agent.exe` before running the installer.
|
||||
- Schema 0014 adds columns; the database opens in place. Nothing changes for any game until you turn the option on.
|
||||
- With the option on, the Agent looks at each game whose hooking it turned off within a minute and lists the ones
|
||||
that qualify; a game shipping a kernel driver (Aniimo's `NEPKernel.sys`, for one) never does.
|
||||
|
||||
### Added
|
||||
|
||||
- **A user-mode anti-cheat exception you can make yourself, per game** (owner decision D33). Settings ▸ Capture ▸
|
||||
*Allow hooking in games with user-mode anti-cheat that were measured before* — off by default. On, it lists the games
|
||||
FrameLedger found eligible: the only anti-cheat in the game runs entirely in user mode (no driver or service, no
|
||||
driver file anywhere in the game's folder), the game is on no title list, and FrameLedger has measured it hooked
|
||||
successfully at least twice. **Make exception…** shows a disclosure — the ban risk, possibly days later and invisible
|
||||
to FrameLedger; what is still refused; how the exception ends — and asks you to accept the risk for that game. The
|
||||
exception turns nothing on: you then turn hooking on for the game on its page, through the usual consent dialog, and
|
||||
the guard still runs every check and refuses anything else it finds. The game's page shows the exception's state
|
||||
(eligible; not eligible and why; in force; suspended; ended and why), the library card says **Exception**, and a
|
||||
session hooked under it is marked in the Sessions tab and its summary. It ends by itself on a new finding, a crash or
|
||||
safety stop under it, FrameLedger stopping because another anti-cheat loaded, or a game update; turning the option
|
||||
off suspends every exception. Aniimo stays blocked: it ships a kernel driver (`NEPKernel.sys`).
|
||||
|
||||
- **Groundwork for the user-mode anti-cheat exception** (owner decision D33, 2026-09-26; the option, the list and the
|
||||
disclosure arrive later in this train). The guard can now be asked to let ONE named anti-cheat family through, and
|
||||
grants it only for a family whose every signal — in the built-in floor and in the rules file — is user-mode: no
|
||||
driver, no service, no `.sys` (on today's rules NetEase Yidun, AhnLab HackShield, Anybrain and FredaikisAntiCheat).
|
||||
It still runs every check and keeps scanning past what it let through, so a second anti-cheat, a kernel driver in
|
||||
the game's folder, a title list, a driver or service on the machine, or a scan that could not finish still refuses;
|
||||
a pass that let something through says so and names it. The injected Overlay learns the same family before it
|
||||
starts watching the game's module loads, so a late-loading module of that family does not stop it and any other
|
||||
anti-cheat still does. Nothing asks for any of this yet: every game is judged exactly as in beta.8.
|
||||
- **The Agent can grant, keep and end a user-mode anti-cheat exception** (D33; the Settings option, the list and the
|
||||
disclosure arrive in the next PR, so nothing in the App asks for one yet). With the option on
|
||||
(`hooking.usermode_ac_exceptions`, off by default), the Agent's library scan asks each blocked game one question —
|
||||
would the guard let exactly its blocking family through, with no kernel driver and nothing else found — and counts
|
||||
its successful hooked sessions; a game with both and at least two sessions is eligible. A grant rests on facts the
|
||||
Agent gathers itself when asked, is bound to the executable's bytes and turns nothing on: hooking is the usual
|
||||
consent dialog afterwards. Under it the Agent tells the Overlay the family before injecting, names it to the guard at
|
||||
the start and at every 30 s re-scan, and marks the session with it. It ends — hooking off, the block standing, the
|
||||
reason kept — on a new finding, a safety unhook, the Overlay stopping for another anti-cheat, a crash while hooked, a
|
||||
game update, or when the user withdraws it; turning the option off suspends every exception without deleting any.
|
||||
Schema 0014 adds the columns; the database opens in place.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Legal: Disclaimer 2.7 and EULA 1.3.** Disclaimer §2A describes the user-mode exception and its risk; the EULA's
|
||||
code-injection clause names it and what making one means. The accuracy block and SECURITY.md say it too. The Legal
|
||||
Gate shows the two changed documents once more; the Privacy Policy is unchanged (2.4).
|
||||
|
||||
@@ -0,0 +1,457 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66): part 1 of 5 of the ledger kept before the first tag, newest first. CHANGELOG.md lists every part. -->
|
||||
|
||||
## Ledger before 0.1.0-beta.1 (2026-08-04 → 2026-09-16)
|
||||
|
||||
_The `[Unreleased]` entries as they stood when the first tag was cut; `release-notes.ps1` stops before this
|
||||
heading. Newest first._
|
||||
|
||||
### Added
|
||||
|
||||
- **P5 prep: a release rehearsal, `SECURITY.md`, and an honest hygiene checklist (2026-09-16).** `release.yml` gains
|
||||
`workflow_dispatch` with a `version` input: the identical job — the gate, publish, runtime licences, the
|
||||
published-tree assertion, `vpk pack`, checksums, the artifact — with no tag and no Release, so the steps that had
|
||||
only ever run by hand on one machine run on the hosted runner before the first tag; a missing `## [x.y.z]` section
|
||||
is a warning with placeholder notes in a rehearsal and stays a stop on a tag. `SECURITY.md`: the private route for
|
||||
a vulnerability (GitHub's private reporting when enabled, else e-mail), the public *Safety gap* form for an
|
||||
undetected anti-cheat, what not to include, and the response *intent* stated as an intent; `ISSUE_TEMPLATE/config.yml`
|
||||
points a vulnerability at the private route; README's safety-gap paragraph links both. `13_CI_CD` §Repo hygiene
|
||||
checklist rewritten: the in-tree items were done and unticked, the first box asked for caller stubs the file's own
|
||||
opening paragraph rejects, and the rest are GitHub settings only the owner can set — listed as such. `14_TESTING`'s
|
||||
Velopack-delta row says it is reachable from the second release.
|
||||
- **The "factor not counted" tooltip says which bucket, and by how much — `sessions.fg_refusal_detail`, schema
|
||||
0005 (2026-09-16).** The owner's Dashboard showed "DLSS-G active — factor not counted" on Hell Is Us, Black Myth:
|
||||
Wukong, Cronos and Onimusha; three refused `non_uniform` (one of eight equal-sample buckets departed more than
|
||||
25 % from the whole, or held no tokens — a menu, a loading screen, an alt-tab inside a whole play session) and
|
||||
one `multiple_streams` (a second swapchain), and the tooltip could only repeat the kind. `FgWindow` had computed
|
||||
the bucket, its ratio and the window's all along; `SessionAggregator` kept only the kind. Now
|
||||
`Application.Recording.FgRefusalDetail` — kind, subject, count, bucket index/count, the bucket's ratio (null when it
|
||||
held no tokens) and the window's — is stored as JSON beside `fg_refusal`, and `FpsPresentation.IdentifiedTooltip`
|
||||
appends its sentence: "Bucket 3 of 8 measured 2.25 against 3.65 for the whole session, over 53 samples." /
|
||||
"2 swapchains presented during the session." / "40 samples; at least 64 are needed to check." A kind with no
|
||||
numbers worth a sentence adds nothing; an unparsable column is the old tooltip. The producer is unchanged and
|
||||
no number is decided by it (owner's decision 2026-09-16: store and show the reason; no steady-state factor, no
|
||||
change to `multiple_streams`). Six strings (en/vi/ja). Tests: `SessionAggregatorTests`, `LedgerDatabaseTests`
|
||||
(script five), `FpsPresentationTests`. Docs: `06_DATA_MODEL` §Migrations, `03_METRICS` §FG factor, `08_UI` §FPS
|
||||
display rule.
|
||||
- **RPG Maker is detected — MV/MZ and XP/VX/VX Ace — and `rulesVersion` is `2026.09.1` (2026-09-16).** Two engine
|
||||
rows `05_DETECTION` marked ⛔ "cannot be expressed in schemaVersion 2": the MV/MZ reasoning wanted a nested group
|
||||
for `nw.dll` **and** (`www/` **or** `package.json`), but MV and MZ both ship `package.json` beside `nw.dll`
|
||||
unconditionally, so `all: [nw.dll, package.json]` is the signal — measured on the owner's *Flower in Us* and a
|
||||
hand-extracted MV title, both `engine=none` until now. The RGSS family is one rule over the three DLL prefixes and
|
||||
the three archive extensions, no version (which DLL matched is not a value any extractor produces). Both sit
|
||||
after `unity`/`unreal` and before `godot`. Fixtures `engines/rpgmaker_mv`, `engines/rpgmaker_rgss`; the
|
||||
`every_engine_marker` canary carries both engines' markers and still expects `unity`. The version bump changes the
|
||||
sweep's cache key, so every game is re-detected on the Agent's next pass. Docs: `05_DETECTION` §Engine signatures.
|
||||
- **The bug report's last optional item: the last session's summary, when ticked (2026-09-15).** `10_LOGGING` §Bug
|
||||
report flow step 2 listed "last session metadata + aggregates JSON (never raw blobs by default)" beside the crash
|
||||
dump, and `legal/PRIVACY_POLICY.md` §3 promises both only when ticked. The Optional items dialog PR-9 added now shows
|
||||
a box for each item that exists: the crash dump, and the newest session in the ledger (`LastSessionSummary`) labelled
|
||||
with its game and start time. Ticked, the zip gains `session.json`, File ▸ Export's own JSON (metadata, aggregates,
|
||||
segments, hardware) without the user's notes and tags, passed through `LogRedactor` because it names the executable;
|
||||
no frame or sensor series. With neither item there is no question. `CrashDumpChoice` became `BugBundleOptions`, and
|
||||
`IBugReportPreview.AskCrashDumpAsync` became `AskOptionsAsync(BugBundleOffer)`. Two strings (en/vi/ja). Tests:
|
||||
`LastSessionSummaryTests`, `BugReportFlowTests`, `BugBundleOptionsViewModelTests`, `PagesLoadTests`. Docs:
|
||||
`10_LOGGING` §Bug report flow step 2.
|
||||
- **P4 PR-9 — the crash dialog, the minidump in both processes, and the crash dump as the bug report's opt-in
|
||||
(2026-09-15).** `10_LOGGING` §Crash handling specified Fatal → `MiniDumpWriteDump` → a dialog offering the bug report
|
||||
→ exit code 1; only the Fatal line existed, and `Crash_Title` / `Crash_Body` were translated for a dialog nothing
|
||||
showed. `Infrastructure/Diagnostics/CrashDumpWriter` writes `crashdumps\<ui|agent>-<UTC time>-<pid>.dmp` through
|
||||
CsWin32 with `MiniDumpWithIndirectlyReferencedMemory | MiniDumpWithThreadInfo`, keeps the five newest and never
|
||||
throws. **The App** marks a dispatcher exception handled; `CrashReporter` logs it, writes the dump and shows
|
||||
`CrashDialog` — a Win32 message box, because a crash cannot vouch for the shell's dialog host — whose Yes reveals the
|
||||
shell window (one hidden in the tray would hold the report's dialogs unseen) and runs `BugReportFlow`; the host then stops and `RunAsync` exits with code 1 after the normal teardown. One dialog per
|
||||
process: a further exception while it is up is logged once and counted, since a layout fault repeats on every pass
|
||||
the dialog's message loop runs. An exception on any other thread is Fatal + dump only. **The Agent** logs and dumps
|
||||
from `AppDomain.UnhandledException` and from `Main`'s own catch (whose `finally` would otherwise close the logger
|
||||
first), once, and leaves the exception unhandled. **The bug report** offers the newest dump of the last seven days
|
||||
before the save dialog, as a checkbox that starts clear, labelled with its time and size, with a line saying a dump
|
||||
can hold file paths, game names and settings (`Dialogs/BugBundleOptionsContent`) — what `legal/PRIVACY_POLICY.md` §3
|
||||
already promised; Cancel writes nothing, and `BugBundleBuilder.WriteAsync` refuses a dump from anywhere but
|
||||
`crashdumps\`. `Crash_Body` becomes `Crash_Body_Format` and keeps its one fact (the capture agent keeps running);
|
||||
seven more strings (en/vi/ja). Tests: `CrashDumpWriterTests` (a real dump of the test process starts `MDMP`; the
|
||||
prune keeps five and touches nothing else; an unusable directory is null and a line), `CrashReporterTests` (the order,
|
||||
no report on No, three further exceptions show nothing, a failed dump still asks, a failed report is not a second
|
||||
crash), `BugBundleBuilderTests`, `BugReportFlowTests` (no dump no question; left clear, ticked, cancelled),
|
||||
`BugBundleOptionsViewModelTests`, `PagesLoadTests`. Docs: `10_LOGGING` §Crash handling and §Bug report flow,
|
||||
`15_ROADMAP`, HANDOFF §P4.
|
||||
- **P4 PR-8 — the accessibility pass, with the section it passes against written first (NFR-9, 2026-09-15).**
|
||||
NFR-9 was one sentence and `08_UI` one bullet ("Ctrl+1…5; grids fully navigable; Esc closes flyouts/dialogs"), none
|
||||
of it built. `08_UI` §Accessibility now says what each clause means here and names the check: **Ctrl+1 … Ctrl+5**
|
||||
and the keypad open Dashboard / Games / Compare / Logs / Settings (`MainWindow` `InputBindings` →
|
||||
`MainWindowViewModel.NavigateToCommand` → `ShellShortcuts`), and `AccessibilityTests` holds the bindings, the map and
|
||||
the NavigationView's order together; **Esc closes the open `ContentDialog` or `MessageBox` with no result**, through
|
||||
its own Close path, and never a dialog that offers no Close button (`Services/DialogKeyboard`, one class handler on
|
||||
`Window` registered in `App.OnStartup`, bubbling so a dropdown's Esc wins) — WPF UI 4.3.0 handles no key in either
|
||||
dialog, measured in its source; **every input that shows no text of its own has an `AutomationProperties.Name`** —
|
||||
thirty controls had none (every Settings toggle, number box and choice box, the hooking switch, the trend metric,
|
||||
the Games and Logs filters and search boxes, the log tail, the edit-game and consent text boxes, the Legal Gate's
|
||||
document, the summary window's tags and notes, and the icon-only close button in the `InfoBar` template), a scan of
|
||||
the App's XAML goes red on the next one (proven by removing one name), and four new strings name the controls that
|
||||
had no label to borrow (en/vi/ja); **no XAML hard-codes a colour** (a second scan), so contrast is the Fluent
|
||||
themes'; the manifest is Per-Monitor V2 (a third). Known gaps are stated there: ScottPlot plots are not
|
||||
keyboard-operable, and no Narrator pass has been done. Docs: `08_UI` §Accessibility and §UX rules, `02_SPEC` NFR-9,
|
||||
`16_WPFUI_SYNTAX` §Gotchas (no Esc in 4.3.0, `CloseButtonText` defaults to "Close", the obsolete `MessageBox.Close`),
|
||||
`15_ROADMAP`, HANDOFF §P4. The Database maintenance dialog's status line is `LiveSetting="Polite"`, so a result is read out.
|
||||
- **P4 PR-7 — Tools ▸ Database maintenance: integrity check, backup, the retention sweep on demand, compaction
|
||||
(2026-09-15).** `06_DATA_MODEL` §Retention promised the four since P0; the menu item said "not built yet". **The
|
||||
sweep is the Agent's**, because `frame_blobs` and `sensor_blobs` are (§Writer ownership): the App sends the new
|
||||
`SweepRetention` command (no payload; `07_IPC` row), and the Agent's `RetentionSweep` reads its own
|
||||
`retention.raw_sessions_per_game` and runs `ISessionRepository.SweepRetentionAllAsync` — the finalize's per-game
|
||||
rule for every game in one transaction (`ROW_NUMBER() OVER (PARTITION BY game_id …)`, a removed game's kept sessions
|
||||
included), answering `SweepRetentionAck { keep, games, sessions }`; unlimited (0) never reaches the repository, which
|
||||
refuses a keep below 1. The other three run in the App through `LedgerMaintenance` and change no row:
|
||||
`PRAGMA integrity_check`; a backup through `VACUUM INTO`, which is consistent while the Agent writes and **refuses
|
||||
the ledger, its WAL and its shared-memory file as a destination** — the save dialog's "replace?" would otherwise have
|
||||
let "delete the existing file first" delete the live database; and compaction (`VACUUM` + `wal_checkpoint(TRUNCATE)`)
|
||||
refused while a fresh `GetStatus` reports a session, with SQLite's busy error a status line rather than a crash.
|
||||
`LedgerDatabase.MaintainAsync` runs a statement outside a transaction, for these only. The dialog
|
||||
(`DatabaseMaintenanceContent` / `DatabaseMaintenanceViewModel`, `DatabaseMaintenancePrompts`) confirms the sweep with a
|
||||
Danger button and shows one status line; the menu's last `NotYetCommand` and the `NotYet_*` strings are gone.
|
||||
Strings en/vi/ja. Tests: `LedgerMaintenanceTests` (healthy, a backup that opens at the same schema with the same rows,
|
||||
never over a file or onto the ledger in any spelling, compaction that returns the space of ten swept series),
|
||||
`SqliteSessionRepositoryTests` (every game keeps its own newest N, a sensors-only session counted once, a second
|
||||
sweep finds nothing, a keep of 0 refused), `RetentionSweepTests`, `AgentCommandHandlerTests` (the composed sweep
|
||||
answers; none composed is not a command), `DatabaseMaintenanceViewModelTests` (twelve cases, the ledger-as-backup
|
||||
refusal among them), `PagesLoadTests` (the dialog loads under the real dictionaries). Docs: `07_IPC`,
|
||||
`06_DATA_MODEL` §Retention and §Writer ownership, `08_UI`, `15_ROADMAP`, HANDOFF §P4.
|
||||
- **P4 PR-6 — every NuGet package the App and the Agent ship has its licence text, and the gate keeps it true
|
||||
(2026-09-15).** `tools/license-gather.ps1` reads the two publish roots' restore output (`obj/project.assets.json`,
|
||||
win-x64, every package with a runtime or native asset that is not a suppressed build-time dependency) and writes
|
||||
one text per package into `legal/licenses/nuget/`: the package's own licence file verbatim when it has one; for a
|
||||
URL-only package a reviewed override (`tools/license-overrides/`: Mono.Posix.NETStandard → the Mono LICENSE file
|
||||
its link resolves to, OpenTK.GLWpfControl → its LICENSE.md, both fetched 2026-09-15 with provenance); for an SPDX
|
||||
expression with no file, MIT's text under the package's own `<copyright>` field (never an invented holder —
|
||||
"not stated" when the package states none) or a pointer to the shared Apache-2.0 / MPL-2.0 text with the MPL
|
||||
Source Code Form link. Distinct third-party notice files are copied once (twenty-seven Microsoft.Extensions
|
||||
packages carry the same 78 KB file). An MPL-2.0 package that *applies* Exhibit B is red — the MPL text itself,
|
||||
which carries the sentence as a template, is excluded, as `spike-notes` §M4 learned. **77 packages ship; the
|
||||
notices table named about fifteen** — LibreHardwareMonitorLib's three MPL-2.0 dependencies (BlackSharp.Core,
|
||||
DiskInfoToolkit, RAMSPDToolkit-NDD), HidSharp, Mono.Posix, the OpenTK/GLFW and SkiaSharp/HarfBuzz families under
|
||||
ScottPlot and the Microsoft.Extensions stack were in every build without a row. The three MPL packages were
|
||||
searched upstream the §M4 way (the sentence once per repository, in LICENSE; no source file carries an MPL
|
||||
notice) and are recorded clear in `legal/THIRD_PARTY_NOTICES.md`. `license-check` §3 runs `-Check` (regenerate,
|
||||
compare both directions — a bump, a removal or a hand edit is red) and asserts the shared texts the generated ones
|
||||
point at exist; `build.ps1` runs the gatherer's fourteen-case self-test first. **The output is culture-invariant, and that
|
||||
was measured rather than assumed:** under tr-TR `-Check` went red on an unchanged tree, because PowerShell's `-match`
|
||||
ignores case in the current culture and "LICENSE" lower-cases to "lıcense" there; file names now match with
|
||||
`CultureInvariant`, ordering is ordinal, and a self-test case runs the gatherer under tr-TR in a child process (in-process
|
||||
it proved nothing — the Regex cache kept the first culture — and a culture-sensitive mutant passed until the case
|
||||
moved out). The App's publish now carries
|
||||
`legal/licenses/` as `licenses/` (plus `THIRD_PARTY_NOTICES.md` and the GPL text), and `release.yml` adds the .NET
|
||||
runtime's licence and notices from the runtime packs the publish used (their version follows the SDK, so they
|
||||
are not committed) and asserts all of it in the published tree — verified on a local publish (runtime 10.0.12,
|
||||
84 generated files). The hand copies `wpfui-MIT.txt` and `velopack-MIT.txt` are folded into the generated
|
||||
`nuget/WPF-UI.txt` and `nuget/Velopack.txt`. The generated directory is `nuget/`, not `packages/`: the
|
||||
repository's `.gitignore` ignores every `packages/` (a NuGet-era rule), which would have left CI comparing
|
||||
against nothing. Docs: `THIRD_PARTY_NOTICES` (intro, four transitive rows, two checklist items ticked),
|
||||
`legal/licenses/README.md` (rewritten: what is generated, what is hand-committed, the stale M3/M4 paragraph),
|
||||
`12_BUILD` gate 13, `13_CI_CD` licence guard, `16_WPFUI_SYNTAX` checklist, HANDOFF §P4.
|
||||
- **P4 PR-5 — Velopack, the updater, `release.yml`, and one version source (`11_UPDATER`, 2026-09-14).**
|
||||
`FrameLedger.App/Update/`: `VelopackUpdateClient` behind the `IUpdateClient` port (Velopack's `UpdateManager` over
|
||||
its GitHub source for this repository; the `stable` channel is the releases GitHub does not mark pre-release, `beta`
|
||||
adds the ones it does), `UpdateFailureMapper` (the §Error mapping rows from the exception: 404 / 403+429 / 5xx /
|
||||
transport / checksum / unknown; an HttpClient timeout is Offline, not a cancel), `FrameLedgerFileDownloader` (Velopack's
|
||||
downloader with `User-Agent: FrameLedger/<version>`), `UpdateService` — the startup silent check 5 s after start when the copy is
|
||||
installed and the new `update.auto_check` setting (default on) says so, every failure a log line; Help ▸ Check for
|
||||
updates with the dialogs (`UpdatePrompts` over WPF-UI's `MessageBox`: the offer with the release notes and the
|
||||
unsigned-release footer, up to date, not an installed copy, the six error rows — a 404 offers the releases page, an
|
||||
unknown failure offers the bug report); the background download, retried once on a checksum failure; and **FR-12 as the shape of the whole thing**: a
|
||||
downloaded package is `Ready` only while the Agent reports no session, otherwise `Deferred` until the last
|
||||
`SessionCompleted`, and the apply itself is refused with a session running. The apply (`Restart to update`, the
|
||||
shell's new persistent InfoBar) sends `Shutdown` to the Agent, holds the connection's relaunch (`IAgentLink.SetLaunchHold`),
|
||||
waits for the pipe to drop (an Agent that does not stop in 10 s leaves everything as it was), hands Velopack the
|
||||
package (`WaitExitThenApplyUpdates`) and ends the host; the restarted App starts the Agent beside itself as always,
|
||||
and — when Velopack reports the restart — re-validates the logon task's action path (`--install-task` on `Stale`).
|
||||
`Program.Main` is now hand-written so `VelopackApp.Run()` precedes any window: the uninstall hook (`UninstallHook`,
|
||||
delegates for the test) asks a running Agent to stop, unregisters the Vulkan layer, removes the logon task and
|
||||
**asks** about the data folder (deleted on Yes only; unanswered inside Velopack's 30 s budget keeps it); install
|
||||
registers nothing. The tray raises "update available" as a balloon only while the window is off screen. Settings ▸
|
||||
Updates gained the startup-check toggle and the channel row's real text. **One version source:** `VERSION` at the
|
||||
repository root, read by `Directory.Build.props` (`<Version>`, SourceLink's `+sha` suffix off) and by
|
||||
`src/native/CMakeLists.txt`, with `versioninfo-check` comparing every built binary's `FileVersion` against it.
|
||||
**`release.yml`** on a `v*` tag: the tag's numeric core must equal `VERSION` and `CHANGELOG.md` must carry a
|
||||
non-empty `## [x.y.z]` section (`tools/release-notes.ps1`, self-tested in `build.ps1`), `{{RELEASE_DATE}}`
|
||||
substituted before the build, the identical gate, publish App + Agent self-contained + ReadyToRun with
|
||||
`-p:Version=<tag>`, the published tree asserted by name (both entry points, the four shipped natives, the rules
|
||||
seed, no capture host), `vpk pack`, `SHA256SUMS.txt` printed into the release body, `gh release create`
|
||||
(`--prerelease` for a `-beta.N` tag). **The package id is `FrameLedger.App`**: Velopack installs into and, on
|
||||
uninstall, deletes `%LOCALAPPDATA%\<packId>`, and `%LOCALAPPDATA%\FrameLedger` is the data folder — the id the docs
|
||||
named would have removed every user's ledger without asking (`UninstallHook.AreSeparate` now refuses the data delete
|
||||
if the two ever overlap). Published locally before the PR: 250 MB in 362 files, every assertion of the workflow's
|
||||
tree step green; `vpk pack` 1.2.0 over it produced `FrameLedger.App-win-Setup.exe` (104 MB) and verified `VelopackApp.Run()` in `Program.Main`. The GitHub release itself is unexercised until a tag. `legal/PRIVACY_POLICY.md` is now **2.1-draft**: the update check and download
|
||||
rows describe requests the software makes, which is a material change the policy's own rule says re-shows the Legal
|
||||
Gate. `legal/licenses/velopack-MIT.txt`. Tests: `UpdateServiceTests` (the skips, the channels, Deferred ↔ Ready,
|
||||
the dialogs and rows, the apply's three endings), `UpdateFailureMapperTests`, `UninstallHookTests`, the
|
||||
connection's hold, the tray's balloon, the settings toggle. Docs: `11_UPDATER` built note, `12_BUILD` §Version and
|
||||
§Publish & package, `13_CI_CD` §release.yml, `08_UI`, `06_DATA_MODEL`, HANDOFF §P4, `15_ROADMAP`, README §Privacy.
|
||||
- **P4 PR-4 — the library import: Steam, GOG Galaxy, Epic and itch.io through a review checklist, hooking off for
|
||||
every row (FR-1.2, 2026-09-14).** `Application.Import.LibraryImporter` over four `IStoreLibrarySource` adapters in
|
||||
`Infrastructure.Import`: `SteamLibrarySource` (`libraryfolders.vdf` + `appmanifest_*.acf` through a new
|
||||
`ValveKeyValues` reader, the root from `HKCU\Software\Valve\Steam\SteamPath`), `GogLibrarySource` (the
|
||||
`HKLM\SOFTWARE\WOW6432Node\GOG.com\Games` keys, read-only, whichever hive and key a caller names so a test uses
|
||||
its own), `EpicLibrarySource` (`Manifests\*.item`: `DisplayName`, `InstallLocation`, `LaunchExecutable`,
|
||||
`AppName`, `AppVersionString`), `ItchLibrarySource` (`apps\*\.itch\receipt.json.gz`). Steam and itch do not name
|
||||
the game's executable: `ExecutableLocator` walks the install three levels deep, drops helpers by name fragment
|
||||
(crash handlers, installers, redistributables, anti-cheat services, updaters) and takes the largest — a guess the
|
||||
review marks "guessed — check it". Discovery joins every title to the ledger: the store's executable or the
|
||||
guess, "already in the library", "no executable found" (a store record that outlived the install). File ▸ Import
|
||||
library… (`ImportLibraryFlow`) shows the checklist (`ImportReviewPrompt` / `Dialogs/ImportReviewContent`, a
|
||||
`DataGrid` with a tick column, select all / none, the count), adds what was ticked exactly as File ▸ Add game…
|
||||
would — **hooking off** — writes the store's platform, id and version through the new
|
||||
`IGameRepository.ApplyStoreMetadataAsync` under the same provenance rule as a detection write (the user's
|
||||
value is never overwritten), and shows the Games page. Nothing is launched, nothing is fetched. The first-run
|
||||
step 4 now points at the menu rather than saying "later build". Tests: `ValveKeyValuesTests`,
|
||||
`StoreLibrarySourcesTests` (fixtures the tests write: two Steam library folders, GOG under a test HKCU key,
|
||||
Epic `.item`, an itch receipt gzipped in the test, the locator), `LibraryImporterTests` (the join, the ticked
|
||||
subset, a store that throws, one executable under two stores), `ImportLibraryFlowTests` (end to end over real
|
||||
files and a scratch ledger; nothing found; cancel; the review's counting), `SqliteGameRepositoryTests` (the
|
||||
store write's provenance). 15 App strings en/vi/ja. Docs: `05_DETECTION` §Platform signatures built note (with
|
||||
the privacy line), `06_DATA_MODEL` §Writer ownership, `08_UI` §Shell menu note + §First-run step 4,
|
||||
`14_TESTING`, HANDOFF §P4, `15_ROADMAP` §P4.
|
||||
- **P4 PR-3 — the bug report's steps 3–4, Help ▸ Documentation, and File ▸ Export as the submenu it was specified
|
||||
as (2026-09-14).** `App/Services/BugReportFlow` is the one flow behind Help ▸ Report a bug… and the Logs page's
|
||||
button: step 2's zip where the user says, then step 3's `ContentDialog` (`BugReportPreviewPrompt` /
|
||||
`Dialogs/BugReportPreviewContent`) listing every entry the builder wrote, with "Show the zip in Explorer" and the
|
||||
drag instruction, then step 4 as its two buttons — **Open GitHub issue** (`IssueLink.NewIssue`:
|
||||
`issues/new?template=bug_report.yml&title=[Bug]%20&labels=bug&app-version=…&os=…`, the form's real hyphenated
|
||||
field ids, the OS in the form's own spelling `Windows 11 26100.2314`) and **Copy summary as Markdown**
|
||||
(`sysinfo.json`'s twelve keys as a table). Nothing is ever sent by itself. Three ports keep it testable without a
|
||||
desktop: `IBugReportPreview`, `IUrlOpener` (`ShellUrlOpener`), `IClipboard` (`WpfClipboard`). Help ▸
|
||||
Documentation opens the README (`docs/` is developer-facing). File ▸ Export is now the submenu `08_UI` §Menu bar
|
||||
specifies: Session CSV / Session JSON for the session last selected on a Sessions tab or opened in a summary
|
||||
window (`SessionSelection`, written by the game page and the summary opener; `SessionExportService` over the
|
||||
summary window's own `SessionExporter` writers), Chart PNG opening that session's summary window where the
|
||||
plot lives; no selection says so in the strip. `BugBundleBuilder.SysInfoOf` is public for the link and the
|
||||
Markdown. Tests: `BugReportFlowTests` (the zip, the preview's entries against the archive, the exact URL, the
|
||||
Markdown, close, cancel), `SessionExportServiceTests` (CSV and JSON where the user says, unknown session,
|
||||
cancelled save, the selection), `LogsViewModelTests` over the flow. 14 App strings en/vi/ja. Docs: `10_LOGGING`
|
||||
§Bug report flow built note (the crash dialog and minidump stay open), `08_UI` §Shell menu note, HANDOFF §P4.
|
||||
- **P4 PR-2 — the "is Vulkan" fact, and the layer's registration following the ledger (2026-09-14).** The rule
|
||||
`12_BUILD` §The Vulkan layer is not registered at install time states — registered only while at least one
|
||||
Vulkan game has hooking enabled, unregistered when the last is disabled — had no way to know which game was
|
||||
Vulkan; the check was "any enabled game". Now the fact is static: `GameFileProbe` reads the executable's import
|
||||
and delay-load tables (`Infrastructure.Detection.PeImports`, bounded, read-only, no exception for a malformed
|
||||
file) and looks for `vulkan-1.dll` as an ASCII or UTF-16 string in the bounded scan (a `LoadLibraryW` loader —
|
||||
`hook-harness --vulkan`'s shape); `StaticDetectionResult.UsesVulkan` is true / false / null, and the sweep
|
||||
stores a true as the id `vulkan` in `capability_flags` beside the rule ids ("Supports Vulkan" on the game page).
|
||||
`Application.Vulkan.VkLayerReconciler` over the new `IVkLayerRegistrar` port (`Infrastructure.Vulkan.VkLayerRegistrar`,
|
||||
the same manifest and HKCU value `--register-vklayer` writes) computes the desired registration from the consent
|
||||
store's enabled games joined to their flags and moves the registration to it — after the pipe handler's stamp,
|
||||
revoke and guard block, after the console `consent grant` / `revoke`, and after every detection sweep, so the
|
||||
crash policy's auto-disable and a fact that arrives after the consent converge within one interval; not staged
|
||||
= nothing to do. `--register-vklayer` runs the reconciler and refuses when no hook-enabled game references the
|
||||
loader; Settings' Register button follows the same rule (`HookedGameViewModel.UsesVulkan`). An Agent off the
|
||||
profile ledger (`--data-dir`) gets an inert registrar: a test or developer ledger never touches HKCU. Tests:
|
||||
`VkLayerReconcilerTests` (first Vulkan game registers, last disables, a D3D game does not, idempotent, not
|
||||
staged), `PeImportsTests` (a synthetic PE32+: both directories, the wide literal through the probe, a malformed
|
||||
file, a non-PE reads as unknown), `DetectionSweepTests` and `StaticGameDetectorTests` (the three-valued fact).
|
||||
`Settings_VkLayer_Note` reworded en/vi/ja. Docs: `17_HOOK_ENGINE` §Vulkan built note gap (1) closed,
|
||||
`12_BUILD` §The Vulkan layer…, `05_DETECTION` §Capability hints, `08_UI` §Settings, HANDOFF §P4.
|
||||
- **P4 PR-1 — the detection rules engine wired into the Agent, and the Supports row (2026-09-14).** The engine,
|
||||
schema, validator and fixture corpus existed since P0 with no production caller and no writer. Now:
|
||||
`Application.Detection.DetectionSweep` runs `StaticGameDetector` over the real `GameFileProbe` for every game in
|
||||
the library whose `DetectionCacheKey` is stale — never scanned, the exe changed, the rules moved on — and
|
||||
persists through the new `IGameRepository.ApplyDetectionAsync`; `Agent.Hosting.DetectionHostedService` hosts it
|
||||
under `--serve` on its own task (the probe blocks on file I/O; the 1 Hz poll never waits on it), every 15 s and
|
||||
at once when `UpdateRules` re-seeds the rules file. **Schema 0004** `games.detection_exe_size_bytes` /
|
||||
`detection_exe_mtime_ms`: the key's exe half apart from `exe_size_bytes` / `exe_mtime_ms`, which are the consent
|
||||
fingerprint the gate reads and which a background scan must never refresh. The repository applies
|
||||
`05_DETECTION` §Caching's provenance rule per field — a `user` field is never touched, a `detected` one is
|
||||
refreshed, an empty field with no entry is filled and badged (without that clause a fresh game could never
|
||||
receive an engine), a null detected value erases nothing — and writes `capability_flags` whole as a JSON array of
|
||||
the rule ids (`dlss`, `dlss_g`, `dlss_rr`, `streamline`, `fsr`, `xess`, `xefg`; the App's `CapabilityNames` reads
|
||||
both spellings). App: Tools ▸ Update detection rules is a real command (`UpdateRules` over the pipe, the seeder's
|
||||
outcome in a snackbar); the game page's Supports row shows what the sweep wrote and says "not scanned yet" only
|
||||
until the Agent's next tick. Tests: `DetectionSweepTests` (5: scanned once then current, exe change and rules
|
||||
change re-scan, unreadable exe and unusable rules, the wake, the key field by field),
|
||||
`SqliteGameRepositoryTests` (the provenance rule end to end, the consent fingerprint untouched),
|
||||
`LedgerDatabaseTests` (0004), `GameDetailViewModelTests` (the Supports row from a detection write, the rule
|
||||
ids). 4 App strings en/vi/ja + the Supports empty-state reworded. Docs: `05_DETECTION` §Caching built note,
|
||||
`06_DATA_MODEL` §Writer ownership / §games / §Migrations, `04_CAPTURE` §Threading model, `08_UI` §Games,
|
||||
HANDOFF §P4 and `15_ROADMAP` §P4 struck.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The legal documents say what the software does, in release form (2026-09-16).** EULA 1.0, Disclaimer 2.2,
|
||||
Privacy Policy 2.2 — the `-draft` suffix (which `legal_acceptance.version` recorded) and the "Draft for review"
|
||||
banners are gone, so the Legal Gate shows all three again. **Privacy Policy §2** listed three requests the software
|
||||
has never made — a weekly safety-list update, a weekly detection-rules update, an opt-in Steam store lookup —
|
||||
under an audit note saying so since 2026-08-04; version 2.2 keeps the two real rows (Velopack's update check and
|
||||
download) and says there is no other request, with the removal recorded as history in the document itself. §1 no
|
||||
longer mentions cover art (no such feature) and states the log retention the code has (7 days App, 14 Agent).
|
||||
**Disclaimer:** the 25-line accuracy-audit block that sat inside the accepted text moved, unchanged, to
|
||||
`docs/legal-drift-history.md`; a five-line pointer explains how §4 is kept true (`legal/ACCURACY.md` +
|
||||
`accuracy-check`); the contact footer the other two documents carry is added. **Third-party notices:** the IGCL/ADLX
|
||||
box is ticked with its check named (`license-check` §1, in the gate since P0); the About-tab box says it is not
|
||||
built and not a gate for the first pre-release; the trademarks pointer reads §6. **README** §Privacy collapsed to
|
||||
one accurate paragraph. **Settings:** the `privacy.online_metadata` toggle is no longer shown — a switch for a request
|
||||
that has no code is the same over-disclosure — and the setting stays reserved (`06_DATA_MODEL` §Settings registry,
|
||||
`08_UI`). `20_OPEN_QUESTIONS` §S20: the feed lands as a new policy version, not as rows kept in advance. The
|
||||
accuracy block's "unreleased" sentence is deliberately untouched: it becomes false with the tag and is rewritten in
|
||||
the tag commit.
|
||||
- **itch.io import reads butler's database, so an install location outside `%APPDATA%` is found (2026-09-16).**
|
||||
`ItchLibrarySource` scanned `%APPDATA%\itch\apps\*\.itch\receipt.json.gz` and nothing else; on the owner's machine
|
||||
the itch app's one install location is `D:\another\it`, `apps\` is empty, and the import logged `itch — 0 title(s)`
|
||||
with no reason — every itch title had to be added by hand. The app records its installs in
|
||||
`%APPDATA%\itch\db\butler.db`: `install_locations` (the folders the user chose), `caves` (one per install, with the
|
||||
folder name or a custom folder) and its own `verdict` JSON naming the executable butler launches. The adapter now
|
||||
copies that database to a temporary directory (the running app holds it in WAL mode), opens the copy read-only,
|
||||
joins the three tables, takes the first Windows candidate of the verdict as the executable (an HTML or Love2D game
|
||||
leaves the locator's guess), and still scans `apps\` receipts for anything the database does not list; an install
|
||||
found both ways is one row, the database's. It logs one line per run — what was consulted and what each source
|
||||
yielded — through the importer's sink, so `0 title(s)` has a reason beside it. `ItchLibrarySource`'s constructor
|
||||
now takes the itch directory (`%APPDATA%\itch`), not `apps\`. Tests: `StoreLibrarySourcesTests` (a butler.db built
|
||||
in the test with a location elsewhere, a custom folder, a verdict path with forward slashes, an HTML-only verdict,
|
||||
a verdict that will not parse, a receipt beside a cave and a receipt-only install; no database and a garbage
|
||||
database both fall back to receipts and say so). Docs: `05_DETECTION` §Platform signatures.
|
||||
- **The Games card's hooking chip reads at 2.6:1 no more, and the Dashboard's FG qualifier no longer clips
|
||||
(2026-09-16).** "Hooking on/off" was `ui:Badge Appearance="Info"`: WPF UI paints that with `PaletteLightBlueBrush`,
|
||||
a fixed Material colour outside both theme dictionaries, under the theme's white text — `#03A9F4` in dark, below
|
||||
AA-large — and no `#` in our XAML for `NoXamlHardCodesAColour` to catch. It is a `Border` in the new `HookStatePill`
|
||||
style now (ON: the accent pair the ×FG chip uses; OFF: the Pill's muted fill with secondary text), the edit
|
||||
dialog's "Detected" badge is `Secondary`, and `ContrastTests` holds it: no App XAML uses the four palette
|
||||
appearances, and every pill's (text, fill) pair composited over the card and window backgrounds is ≥ 4.5:1 in both
|
||||
theme dictionaries, with the old pair asserted below it so the check is known to bite. The FG qualifier chip on the
|
||||
Dashboard's recent-sessions row was reported with it and had a different defect — a sentence-length qualifier in a
|
||||
star column with no trimming overflowed the row — so 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. Docs: `08_UI` §Contrast, `16_WPFUI_SYNTAX` §Theming.
|
||||
- **A print verb no longer migrates the ledger it prints, and a close checkpoints the WAL it wrote (2026-09-16).**
|
||||
`FrameLedger.Agent --console sessions`, run against the owner's own ledger while its on-disk file was at schema 2,
|
||||
applied scripts 0003 and 0004 to it: every verb opened through the one migrating `LedgerDatabase.OpenAsync`. Found
|
||||
while investigating a ledger whose day of rows lived only in a 4 MB WAL whose 1006 frames carried a salt one
|
||||
generation older than the WAL header, over a main file no checkpoint had reached — a fresh connection (the console,
|
||||
a next launch) saw the 14 September state, while the running App and Agent saw the day through the shared WAL
|
||||
index. The mechanism is unrecorded (`06_DATA_MODEL` §Migrations carries what was observed and what is not known);
|
||||
the data was rebuilt from the old-salt chain by hand. What changed: `LedgerDatabase.OpenReadOnlyAsync` — an
|
||||
existing file, `query_only`, no pragma that writes, no `MigrationRunner`; a schema newer OR older than the build is
|
||||
refused with the reason, and `WriteAsync`/`MaintainAsync` throw. The Agent's `sessions`, `consent list`,
|
||||
`killswitch status` use it (`Program.PrintsOnly`), `db path` opens nothing at all, and a refusal is a console line
|
||||
with exit 7, never a crash dump; the App's `--diag` uses it too. `OpenAsync` now runs a passive checkpoint after
|
||||
migrating and reports it (`LedgerDatabase.OpenDiagnostics`, one `ledger: wal at open` log line), and
|
||||
`DisposeAsync` runs `wal_checkpoint(TRUNCATE)` and reports that, so a clean close leaves the main file complete
|
||||
whether or not SQLite's own close-time checkpoint runs. Tests: `LedgerDatabaseTests` (an older schema is refused
|
||||
byte-for-byte unchanged; a read-only open reads and refuses to write; a missing file creates nothing; a close leaves
|
||||
the row readable through `immutable=1`), `AgentReadOnlyVerbsTests` (the print-verb set, the refusal's exit code and
|
||||
the untouched file, `db path` without a ledger). Docs: `06_DATA_MODEL` §Migrations, `12_BUILD` §Debugging,
|
||||
`10_LOGGING` §Diagnostics, HANDOFF §Traps.
|
||||
- **A start that fails says so on screen (2026-09-15).** When `App.RunAsync` caught its own exception — a ledger
|
||||
that would not open (a newer schema, a locked file), a host that would not start — FrameLedger wrote a Fatal line to
|
||||
`ui-*.log` and exited with code 1 with nothing on screen, so a user saw a click do nothing. It now shows
|
||||
`StartupFailureDialog`, a Win32 message box like the crash dialog (the shell is what failed): the exception's message,
|
||||
the log folder, and Yes to open that folder; the exit code is still 1, and a crash the dispatcher already reported
|
||||
shows no second dialog. Two strings (en/vi/ja). Tests: `StartupFailureDialogTests`. Docs: `10_LOGGING` §Crash
|
||||
handling.
|
||||
- **Bug bundles no longer carry the user's name in log paths, which the privacy policy already promised
|
||||
(2026-09-15).** `legal/PRIVACY_POLICY.md` §3 says "logs are redacted (user directory paths removed) before
|
||||
bundling" and `10_LOGGING` named a `RedactingEnricher`; neither existed, and `BugBundleBuilder` copied `ui-*.log`,
|
||||
`agent-*.log` and `overlay-*.log` verbatim on the stated ground that they carry no paths beyond the data directory,
|
||||
which is itself under the user's profile. On the dev box the profile path appeared 8 times in the UI log, 7 in the
|
||||
Agent's and in 175 overlay headers. `App/Services/LogRedactor` now rewrites every log copy in the zip: the name in
|
||||
each `X:\Users\<name>` path becomes `<user>`, and so does a profile directory's last segment elsewhere, in
|
||||
backslash, doubled-backslash (Serilog's JSON), forward-slash, any-case and ANSI-`?` spellings, byte for byte
|
||||
otherwise (Latin-1 round trip, so UTF-8 and ANSI logs both survive). The files on disk keep their paths; the policy's
|
||||
sentence is now true without a word of it changing. Tests: `LogRedactorTests`, `BugBundleBuilderTests`. Docs:
|
||||
`10_LOGGING` §Serilog configuration (the enricher claim struck, with where the rule is enforced) and §Bug report
|
||||
flow step 2.
|
||||
- **Two unmeasured facts were stored as values (2026-09-15).** The quality byte's `0xFF`, the Overlay's "a hook ran
|
||||
and could not tell" (`fl_shm.h` `upscalerQuality`), was aggregated as a number, so a session and the live card
|
||||
carried the text `255`, which the game page and the Dashboard append to the upscaler's name: every AMD dispatch
|
||||
carries `0xFF`, so an FSR title would read "FSR 255". `SessionAggregator` (row and segments) and
|
||||
`SessionProgressCalculator` now leave those frames out, and a quality nobody told is null (`FrameSample.QualityNotTold`).
|
||||
And `reflex_active` was written `false` on every hooked row with no latency sample, although nothing measures Reflex
|
||||
today; it is null there now, so an export no longer says "off" for a thing never measured. Tests:
|
||||
`SessionAggregatorTests` (not told is null, told frames still count; Reflex null), `SessionProgressCalculatorTests`.
|
||||
Found while checking `legal/ACCURACY.md` against the code. Not done: naming a preset the hook did read, which
|
||||
`03_METRICS` assigns to a `Domain.UpscalerNames` that does not exist; no measured title has produced one.
|
||||
- **Test runs stop filling the real data folder with hook-harness logs (2026-09-15).** The injection tests inject the
|
||||
shipped Overlay, whose log goes to `%LOCALAPPDATA%\FrameLedger\logs` by design (§S21: not the environment, and no
|
||||
switch in the injected DLL), so the owner's folder held 2506 overlay logs, 2492 of them hook-harness's from test
|
||||
runs since 2026-09-06, beside 14 from real titles. Each test binary now removes, when its run ends, exactly the logs
|
||||
it caused: an `overlay-*.log` created after the run started whose first line names a hook-harness image it owns. A
|
||||
Catch2 listener in `guard_test.cpp` does it natively (`src/native/tests/overlay_log_sweep.h`, the image must be this build's
|
||||
`FL_HARNESS_EXE`), and `tests/Shared/HarnessOverlayLogSweep.cs`, an xUnit assembly fixture that
|
||||
`FrameLedger.DrainFixtures.targets` compiles into every test project staging the harness, does it for the managed
|
||||
suites (the copy beside the test binary, plus the renamed copy `PipeEndToEndTests` registers). Assemblies run in
|
||||
parallel with their own copies, so none removes a log another is about to read, and a game's log is never touched.
|
||||
The new `test-artifacts` gate (`tools/test-artifacts-check.ps1`, seven self-test cases) fails for a harness log
|
||||
created during the gate and still there, which is red on the unswept tree. Tests: `[sweep]` in `fl_guard_test`,
|
||||
`HarnessOverlayLogSweepTests`. The logs from before this change are left for the owner. Docs: `17_HOOK_ENGINE`
|
||||
§Native logging, `12_BUILD` gate list, `14_TESTING`, HANDOFF §Traps. No Overlay change, so no hook-path overhead.
|
||||
- **The accuracy block says what the code measures on 2026-09-15 (`legal/ACCURACY.md`, embedded in `README.md` and
|
||||
`legal/DISCLAIMER.md`).** Dated 2026-09-06, it still said there was no Agent loop, storage, charts, library import
|
||||
or UI, that OpenGL intercepted nothing, that no shipped component drove the 30 s re-scan and that video memory was
|
||||
not measured — all false since. Every sentence was re-checked against the code: OpenGL is measured; Vulkan only
|
||||
when FrameLedger starts the game (a running Vulkan title gets the Direct3D component, unverified); FSR is named FSR 3
|
||||
or unversioned, never FSR 2 or 4; the preset is not reported anywhere; frame generation is Direct3D-only and falls
|
||||
back to a qualified Presented FPS; whole-card video memory is recorded while per-game VRAM, shader-stutter
|
||||
attribution, Reflex, HDR and CPU temperature are not; the shipped Agent runs the re-scan and the kill switch can
|
||||
only refuse. Nothing has been released. `README.md` outside the block: the safety row's "re-scan does not run at
|
||||
all", the XeSS and "always shown" promises, the Vulkan requirement, CPU temperature, NVAPI's Reflex, and a note that
|
||||
no release exists. `legal/DISCLAIMER.md` is 2.1-draft (the first-run gate shows it again): two history bullets the
|
||||
software caught up with are struck, and the path-tracing "confidence-scored suggestion" it never computes is
|
||||
corrected. Docs that contradicted the code: `04_CAPTURE` (attach mode on a running Vulkan title is not Tier 2 — an
|
||||
open decision for the owner), `05_DETECTION` (four runtime facts have no writer), `17_HOOK_ENGINE` (`wglSwapBuffers`
|
||||
is built), `15_ROADMAP` and HANDOFF (`StaticGameDetector` runs in `DetectionSweep`). Stale comments in `dllmain.cpp`
|
||||
(OpenGL "NOT HERE"), `layer.cpp` (`vkQueuePresentKHR` "NOT hooked") and `fl_guard.cpp` (the signer lookup "not wired
|
||||
yet") now say what the code does; comments only, no behaviour change.
|
||||
- **The native log test read another process's log, and was filed as a flake four times (2026-09-14).**
|
||||
`guard_test.cpp`'s `FindOverlayLog` took the first `overlay-<pid>-*.log` by name in the real
|
||||
`%LOCALAPPDATA%\FrameLedger\logs`, which keeps every run's log — 2130 on the dev box. A harness that drew a
|
||||
reused pid (6840) read a finished log from 2026-09-06 and failed on its STOP line; a re-run drew a fresh pid and
|
||||
passed. The failure output had printed the stale path every time. It now takes the newest log created at or after
|
||||
the child process started (`GetProcessTimes`), and the test now plants a 1999-dated log under the child's pid
|
||||
before injecting, so the old lookup is red on every run instead of on pid reuse — measured: with the lookup
|
||||
reverted, 9 of 18 assertions failed reading the planted file; with the fix, 18 of 18 pass and the file is removed
|
||||
either way. Test-only: no shipped binary changes.
|
||||
- **A DXGI present counter that went backwards read as four billion unseen presents (2026-09-14).** The Present
|
||||
hook reads `IDXGISwapChain::GetLastPresentCount` before forwarding and took `now − previous` on the chain's slot
|
||||
as unsigned arithmetic. A chain released and re-created at the same address inherits the slot and its old count
|
||||
while DXGI's count for the new chain starts near zero, so the difference wrapped to ~4e9: the owner's ledger
|
||||
held `dxgi_unseen_total = 4294967243` (−53 as `uint32`) on a title whose pacer never presented past the hook, the
|
||||
record byte saturated at 255, and that saturation is the `DxgiSaturated` refusal that took the frame-generation
|
||||
factor with it. `fl_dxgi_count.h` now owns the arithmetic: a regression is a reset — the present claims no delta
|
||||
(as a chain's first hooked present does), nothing is added, the slot re-arms on the new reading — and the
|
||||
session total saturates at `UINT32_MAX` rather than wrapping, the same direction the record byte already took
|
||||
(a numerator must read high and be refused, never low and be believed). Compile-time `static_assert`s pin the
|
||||
algebra; ctest `fl_dxgi_count` (`hook-harness --probe-dxgi-count`) drives the two behaviours. Hook-path cost: one
|
||||
compare on the virtual call the hook already made (`--probe-cost` in the PR). Docs: `fl_shm.h` @48/@52,
|
||||
`17_HOOK_ENGINE` §Hook inventory.
|
||||
- **A safety notice was a red bar with no way to close it (2026-09-14).** WPF UI 4.3.0's `InfoBar` template has no
|
||||
`ContentPresenter`, so the action button every persistent banner carries as the InfoBar's Content — "Record this
|
||||
session without measuring it" on a refusal, Dismiss on an unhook or a degrade, the only dismissal once
|
||||
`IsClosable="False"` removed the X per `08_UI` §Notifications policy — compiled, bound and was never drawn. The
|
||||
Agent-offline banner's Retry and the game page's Re-enable were dropped the same way. `Styles/FrameLedger.xaml`
|
||||
now re-templates `ui:InfoBar` with the upstream template verbatim plus one presenter column, collapsed without
|
||||
content; no view model changed. `PagesLoadTests.TheInfoBarTemplateRendersItsContent` renders the app's template
|
||||
and the library's and asserts the button appears under one and not the other, so it turns red when upstream
|
||||
gains a presenter and the copy should go. `legal/licenses/wpfui-MIT.txt` added (the template is MIT text).
|
||||
Docs: `08_UI` §Notifications policy correction, `16_WPFUI_SYNTAX` §Gotchas, HANDOFF §Traps.
|
||||
- **Frame generation read N/A beside a detection that had succeeded (2026-09-14).** Two of the owner's hooked rows
|
||||
carried `fg_mode = 'dlssg'`, `fg_source = 'api'` and `fg_factor` NULL — the Streamline tags named DLSS-G, the
|
||||
census had `sl.dlss_g.dll`, and the token count refused — and every FG surface in the App said N/A: the readout
|
||||
fell into the "detected" shape and printed `N/A → N/A FPS (×0.0 FG)` (a factor nobody counted, from `factor ?? 0`),
|
||||
the game page said `DLSS-G ` with a trailing space, the grid's Displayed and FG× said N/A with no reason, and the
|
||||
reason existed nowhere — `FgWindow.Refusal` was computed and dropped. Now: **schema 0003** adds `sessions.fg_refusal`
|
||||
(`Vocabulary.FgRefusal`: `not_counted`, `no_evaluations`, `non_uniform`, `dxgi_saturated`, …), written by
|
||||
`SessionAggregator.ApplyFg` whenever no factor is published; `SessionProgress` gains optional `fgRefusal` and
|
||||
`fgRuntimeCensus`; and the UI gains a fourth shape, `FpsReadoutKind.IdentifiedUncounted` — Presented FPS with a
|
||||
warning chip "DLSS-G active — factor not counted", the refusal in plain words as its tooltip ("read it as Displayed,
|
||||
not Native"), `DLSS-G · factor not counted` on the game page, N/A in Displayed and FG× (no factor exists; it is not
|
||||
a measured none). `GeneratedLine` no longer accepts a missing factor. The `fg_runtime_loaded` chip now names the
|
||||
module from the census (`08_UI` §FPS display rule asked for it from the start): `FG runtime loaded (sl.dlss_g.dll)
|
||||
— may include generated frames`. 15 App strings en/vi/ja (`Fg_Refusal_*`, `Fps_Fg_Identified_*`,
|
||||
`Fps_Census_RuntimeLoaded_Named_Format`, `Fg_Factor_NotCounted`). Tests: `FpsPresentationTests` (the shape, the
|
||||
live wire, the module name, the counted label), `GameDetailViewModelTests` (the page and the grid),
|
||||
`SessionAggregatorTests` (identity without a count records the refusal, the owner's zero-token shape, a counted
|
||||
factor carries none), `SessionProgressCalculatorTests`, `LedgerDatabaseTests` (the column). Docs: `03_METRICS`
|
||||
§Metrics FG factor row, `08_UI` §FPS display rule, `06_DATA_MODEL` §sessions + §Migrations, `07_IPC` §Messages.
|
||||
What this does NOT do: decide the count. Why the count refused on those two rows is what the new column will
|
||||
say on the next capture — the `dxgi_unseen_total` of 4294967243 on one of them (a `uint32` gone negative in the
|
||||
Overlay's DXGI delta) is a separate, native fix.
|
||||
- **Two Settings descriptions were centred once they wrapped (2026-09-14).** A `TextBlock` with a `MaxWidth`
|
||||
inside a stretched `StackPanel` is centred by WPF as soon as its text wraps, so the descriptions under
|
||||
*Record games launched outside FrameLedger* and *Fetch store metadata online* showed their second line offset
|
||||
(owner screenshots, en and vi). Both carry `HorizontalAlignment="Left"` now, like the Vulkan layer and logon
|
||||
task rows already did. XAML only.
|
||||
|
||||
@@ -0,0 +1,809 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66): part 2 of 5 of the ledger kept before the first tag, newest first. CHANGELOG.md lists every part. -->
|
||||
|
||||
## Ledger before 0.1.0-beta.1 (continued, part 2 of 5)
|
||||
|
||||
### Added
|
||||
|
||||
- **P3 PR-9 — first run, the Legal Gate (FR-11), the closing sweep (2026-09-14).** `FirstRunWindow` /
|
||||
`FirstRunContent` / `FirstRunViewModel`, shown before the shell whenever `LegalGate` says a document has no
|
||||
acceptance at this build's version: the four documents embedded at build (`legal/EULA.md`, `LICENSE`,
|
||||
`legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md` — the text this build was reviewed with, authoring comments
|
||||
stripped, `{{RELEASE_DATE}}` left for release), one Accept writing four `legal_acceptance` rows with each
|
||||
document's own `**Version:**` line, Decline ending the host, a closed window counting as a decline; the
|
||||
Agent-setup step (unelevated by default, elevation optional and required by no tier, the `HelloAck` facts as
|
||||
they arrive); the hooking explainer reusing the consent dialog's reviewed Tier 1 / Tier 2 paragraphs and
|
||||
saying hooking stays off until enabled per game; the import placeholder. Settings ▸ "Reopen the legal
|
||||
documents" shows them read-only. D8 unchanged: the gate is not a consent precondition. NFR-4: the first
|
||||
window's time from process start is logged every run (1.3–1.5 s on the dev box), the 100-session query is
|
||||
asserted under 500 ms, charts draw ≤ 2 × 2000 points per series. Tests (App, 120): `LegalDocumentsTests`,
|
||||
`FirstRunViewModelTests` (6), the Settings reopen, both first-run steps in `PagesLoadTests`. 29 App strings
|
||||
en/vi/ja. Docs: `08_UI` §First-run flow built note with the NFR-4 numbers, `06_DATA_MODEL` §legal_acceptance,
|
||||
`20_OPEN_QUESTIONS` §G legal-versioning row answered, `15_ROADMAP` §P3 code-complete, `09_I18N` scope line,
|
||||
CLAUDE.md's App line, HANDOFF row 9 struck and the one START HERE moved to a P4 pointer.
|
||||
- **P3 PR-8b — the tray, the Agent's maintenance flags, the Settings buttons over them (2026-09-14).** The tray
|
||||
(H.NotifyIcon.Wpf, `TrayHost` over a WPF-free `TrayViewModel`): four drawn icons — ● a Tier-1 session runs,
|
||||
◐ sessions run and none is measured, ⏸ the Agent reports paused, a ring otherwise — the tooltip naming the
|
||||
game; menu Open / Pause–Resume capture (`PauseCapture`/`ResumeCapture`, the state shown is the `PauseAck`'s) /
|
||||
Agent status / Exit; a left click opens the window; **minimize to tray on close** honoured through
|
||||
`WindowClosePolicy` while a tray icon exists; **FR-3.8's balloon** "Session saved — game — click to view" only
|
||||
while the window is off screen (the Dashboard's snackbar otherwise — one event, one channel), its click opening
|
||||
the summary; a safety event is never a balloon. Tools ▸ Agent status… / Vulkan layer registration… navigate.
|
||||
The Agent's `--install-task` / `--uninstall-task` (`Infrastructure.Startup.LogonTask`: `\FrameLedger\FrameLedger.Agent`
|
||||
through the Task Scheduler COM API — `schtasks /Create /SC ONLOGON` is "Access is denied" unelevated, measured —
|
||||
this user's logon trigger, interactive token, lowest run level, `--serve`) and `--register-vklayer` /
|
||||
`--unregister-vklayer` (`Infrastructure.Vulkan.VkLayerRegistration`: the HKCU `ImplicitLayers` DWORD named by
|
||||
the manifest; register refuses while no game has hooking on; unregister also removes a stale value naming our
|
||||
manifest elsewhere); `HelloAck.vulkanLayerRegistered` now reads the key; `--diag` is the one flag the Agent
|
||||
still answers "not this binary's". Settings: Register / Unregister the layer and Register / Repair / Remove the
|
||||
task run the flag as a child process and re-read the machine. Tests: `TrayViewModelTests` (7), the Settings
|
||||
additions (3), `VkLayerRegistrationTests` (under a test's own key), `LogonTaskTests` (Integration: a real task
|
||||
under a test's own name), `AgentCommandLineSurfaceTests` (the flags are verbs), the e2e flags case now `--diag`.
|
||||
27 App strings en/vi/ja. Docs: `08_UI` §Shell tray note and §Settings 8b note, `17_HOOK_ENGINE` §Vulkan built
|
||||
note with its two stated gaps, `12_BUILD` §Agent flags, HANDOFF row 8 struck.
|
||||
- **P3 PR-8a — Settings, the safety notices, the Logs page, `--diag` (2026-09-14).** The Settings page over the
|
||||
registry (`RegisteredSettings`, D16): Capture first — the global kill switch (`hooking.kill_switch`, the gate's
|
||||
fourth input, so a running measured session stops at its next 30 s re-scan) with its state line, the
|
||||
hook-enabled games with a per-row "Turn off" that is `SetHookEnabled { enabled: false }` over the pipe (the
|
||||
App still writes no hook-state column, D15), the Vulkan layer state from `HelloAck`, the safety-document link;
|
||||
then minimum session length / sensor interval / raw-series retention as bounded `NumberBox`es that refuse an
|
||||
out-of-range value in place, background capture, the Agent's elevation state with the "not required by any
|
||||
tier" paragraph, "Start FrameLedger with Windows" as this user's `HKCU\…\Run` value
|
||||
(`Infrastructure.Startup.RunAtLogon`), minimize-to-tray (stored; honoured by PR-8b), online metadata (off),
|
||||
the update channel (stored), debug logging (moves the App's Serilog `LoggingLevelSwitch` at once), and Legal
|
||||
reopen as a "not yet" line until PR-9. **Safety notices** (`Services/SafetyNotices`, `08_UI` §Notifications
|
||||
policy): `CaptureRefused`, `SafetyUnhook` and `CaptureDegraded` become persistent `InfoBar`s above every page
|
||||
with the family and signal named from the `Safety_*` strings, never a toast, never a timeout; the one button
|
||||
on a refusal is "Record this session without measuring it" — the acknowledgement, since the Agent already
|
||||
records Tier 2; `CaptureError` goes to the 4 s strip. **Logs** (`LogTail`, `LogsViewModel`): the newest
|
||||
`ui-*.log` / `agent-*.log` with shared read and a 2 MB cap, level filter over the template's prefix, search,
|
||||
pause, a 2 s refresh only while the page is shown, Open logs folder, and Export bug bundle = `10_LOGGING` step
|
||||
2 (`BugBundleBuilder`: our logs of the last seven days verbatim, the five newest overlay logs, `sysinfo.json`,
|
||||
`settings.json`; nothing is sent, steps 3–5 are P4's). **`FrameLedger.exe --diag`** writes the environment and
|
||||
capability report to `logs/diag-<ts>.txt` and stdout without starting the host. Tests (App, 100; Infrastructure
|
||||
+2): `SettingsViewModelTests`, `SafetyNoticesTests`, `LogTailTests`, `LogsViewModelTests`,
|
||||
`BugBundleBuilderTests`, `DiagReportTests`, `RunAtLogonTests`, and both pages rendered in `PagesLoadTests`. 69
|
||||
new App strings in en/vi/ja. Docs: `08_UI` §Notifications policy/§Logs/§Settings built notes, `10_LOGGING`
|
||||
built notes, HANDOFF row 8 amended (8b: tray, layer and task verbs), CLAUDE.md's App line.
|
||||
- **P3 PR-7 — Trend, Sensors, Latency, and Compare with the mixed-tier guard (2026-09-14).** The game page's tabs
|
||||
2–6: Frametime and Distribution of the selected session (the summary window's own charts); **Trend** through
|
||||
`Charts/TrendSeriesBuilder` — one point per hooked session oldest first (Average = Native where frame generation
|
||||
was measured, Presented where not; Displayed only where measured; the lows; max GPU °C), FR-6.4's exclusion of
|
||||
mid-session-change sessions by default with the toggle and the excluded count, FR-6.3's markers wherever two
|
||||
consecutive sessions' hardware snapshots differ (GPU driver, GPU, CPU, display mode, OS) as labelled lines on
|
||||
a date axis; **Sensors** (core / hotspot °C, load %, power W on one plot; the game's own per-present VRAM and
|
||||
the adapter-wide sensor as two differently-labelled series on another); **Latency** (the `latency_us` blob with
|
||||
the stored avg / p95 lines, only when Reflex reported). **Compare** (`CompareViewModel`): the last 200 sessions
|
||||
across games in a checkbox picker (2–5), `IMixedTierPrompt` — a blocking `ContentDialog` that compares nothing on
|
||||
a decline (FR-6.2), the tier legend on the chart and an `InfoBar` when it proceeds — one percentile curve per
|
||||
hooked session (`Charts/PercentileCurve`, shared with the distribution), the stat table with Native / Displayed /
|
||||
Presented FPS as three separate rows, the best value of each row highlighted (higher wins for FPS, lower for
|
||||
temperature and stutter, N/A never), Tier-2 cells at N/A, PNG export. Tests (App, 74): `TrendSeriesBuilderTests`
|
||||
(order, the exclusion, Average/Displayed per shape, the markers' text), `CompareViewModelTests` (the picker's
|
||||
bounds, a declined guard, an acknowledged mixed comparison with its legend and N/A cells, the best-of-row
|
||||
rule), the selected-session series and the trend toggles on the game page, and all four new charts rendered
|
||||
through Skia in `PagesLoadTests`. 65 new App strings in en/vi/ja. Docs: `08_UI` §Games tabs and §Compare built
|
||||
notes, HANDOFF row 7 struck.
|
||||
- **P3 PR-6 — the session summary window and the charts: `ChartTheme` over two palettes, min/max decimation,
|
||||
the frametime timeline with stutter markers, segment ribbon and sensor overlay, the distribution, FR-8.3's
|
||||
override, tags/notes, and CSV/JSON/PNG export (2026-09-14).** `Charts/SessionSeriesLoader` decodes a session's
|
||||
blobs once (cumulative time, the generated and gap bits, the application-frame view with
|
||||
`Domain.Metrics.StutterDetector` over it, segments from frame index to seconds, sensors aligned to `t_ms`);
|
||||
`Charts/Decimator` is FR-5.3 (every bucket's min and max in order, ≤ 4000 points per draw — a 500k-point
|
||||
series keeps its spike and its dip); `FrametimeChart` (native by default, the every-present series behind the
|
||||
FR-5.4 toggle only when generated frames exist, PSO-compile stutter coloured apart per FR-5.5, alternating
|
||||
segment spans, GPU temperature / load on the right axis) and `DistributionChart` (FPS histogram, the percentile
|
||||
curve through `Domain.Metrics.Percentile`) draw ScottPlot 5.1.59 plots under `ChartTheme` — one subscription to
|
||||
`ApplicationThemeManager.Changed` re-colours every live plot from `Styles/ChartPalette.{Dark,Light}.xaml`, the
|
||||
one place hex colours are allowed, with `ChartPaletteTests` pinning the two files' key parity.
|
||||
`Windows/SessionSummaryWindow` (a secondary `FluentWindow` with its own dialog host) shows the stored
|
||||
aggregates as stat cards — never recomputed, the lows labelled *(presented)* when frame generation was not
|
||||
measured — the chips resolved through `TriStateResolution` with FR-8.3's dialog writing the override to
|
||||
`session_annotations` beside the measurement (and the game default on request), the crash and safety-unhook
|
||||
bars, the tags/notes editor, and FR-9: `SessionExporter` writes the CSV with `03_METRICS` §Export schema's
|
||||
column line verbatim and its `#` header block, InvariantCulture throughout, no rows for Tier 2; the JSON
|
||||
(`frameledger-session/1`); PNG via `Plot.SavePng`. Opened from a Sessions-tab row and from the Dashboard's
|
||||
recent list; FR-3.8 is an in-app notice on `SessionCompleted` until the tray exists. Tests (App, 67):
|
||||
`DecimatorTests`, `ChartPaletteTests`, `SessionSeriesLoaderTests` (the bits, the views, the segment mapping,
|
||||
−1 sensor ticks dropped, a 2000-frame round trip with stutter flags), `SessionExporterTests` (the schema line,
|
||||
the header, invariance under vi-VN, a Tier-2 export with no rows, the JSON with N/A omitted),
|
||||
`SessionSummaryViewModelTests` (cards from the row, the override beside the measurement and its clearing,
|
||||
tags de-duplicated, exports through a scripted saver). 57 new App strings in en/vi/ja. Docs: `08_UI` §Session
|
||||
summary and `16_WPFUI` §ScottPlot theme sync built notes, HANDOFF row 6 struck with the two deliberate
|
||||
deviations (a dialog rather than a flyout; the toast waits for the tray).
|
||||
- **P3 PR-5 — Games and Dashboard: the grid, the game page, the hooking control, the Sessions tab, the live
|
||||
card, `FpsReadout` and `TriStateChip` (2026-09-14).** `Services.FpsPresentation` decides CLAUDE.md rule 6 in ONE
|
||||
place for rows and for 1 Hz progress events — generated (`62 → 118 FPS (×1.9 FG)`, Native first, the factor a
|
||||
chip), measured none (`144 FPS` alone), not measured (Presented FPS with the census qualifier chip, muted or a
|
||||
warning) — and the table's two negatives, `—` (measured none) and `N/A` (not measured), that must not collapse;
|
||||
`FpsPresentationTests` pins all three shapes and both negatives. `Controls/FpsReadout` and `Controls/TriStateChip`
|
||||
render a model and decide nothing. Games: `GamesViewModel` (cards from `GameLibrary.ListCardsAsync`, search and
|
||||
sort in memory), FR-1.1 by pick, menu or a dropped `.exe` (`AddGameFlow`, one flow), FR-1.4 with
|
||||
**Keep sessions / Delete sessions too** revoking consent over the pipe first; `GameDetailViewModel` (header,
|
||||
**Supports** beside **Last session measured**, FR-1.3's edit dialog badging detected fields, the hooking toggle
|
||||
through `HookingConsent` with a refusal / mismatch / failure as a persistent `InfoBar` and FR-2.2's disabled
|
||||
switch with the reason inline, FR-2.5's InfoBar with re-enable, the Sessions `DataGrid` of FR-6.1 with the
|
||||
chips resolved through `TriStateResolution`). Dashboard: `LiveCaptureViewModel` over `SessionStarted` /
|
||||
`SessionProgress` / `SessionCompleted`, the recent list with game names, the totals strip
|
||||
(`ISessionRepository.CountSinceAsync` is new). Pages are navigated by type; `GameSelection` carries the game;
|
||||
`IPageNavigator`, `IGamePicker`, `IConfirmations`, `IEditGamePrompt`, `IMessageStrip`, `IAgentLink` are the
|
||||
seams the tests use. Tests (App, 54): the presentation rule, formats, `GameLibrary` over a scratch ledger, the
|
||||
game page end to end with a scripted Agent (toggle on → dialog → `SetHookEnabled` → reload; refusal → notice
|
||||
and a blocked row disables the switch; remove revokes first), the Dashboard's events, and **`PagesLoadTests`
|
||||
— every page and both templates load under the real theme dictionaries on an STA thread**, so a binding typo
|
||||
is red in CI. 130 new App strings in en/vi/ja. Docs: `08_UI` §Dashboard and §Games built notes, `16_WPFUI`
|
||||
§Custom controls as built, HANDOFF row 5 struck. **Deferred on purpose:** the card sparkline and the chip
|
||||
override flyout (PR-6), the Agent card's capability badges and Repair (PR-8), a dropped `.lnk`.
|
||||
- **P3 PR-4 — FR-2.1's consent dialog: the reviewed `Safety_*` family in `Shared`, `ConsentProvenance.ConsentDialog`,
|
||||
and the Agent's stamp (2026-09-13).** `src/FrameLedger.Shared/Strings.resx` + `.vi` + `.ja` — 20 `Safety_*` keys:
|
||||
the dialog (intro that recommends neither choice, what is injected and why, **Tier 1 and Tier 2 as two
|
||||
paragraphs of the same shape**, the anti-cheat statement with the 30 s unhook, the terms statement, the typed
|
||||
phrase, the two buttons, the version-mismatch and agent-unavailable sentences) and the safety notices PR-5
|
||||
and PR-8 will render (`Safety_Refused_*`, `Safety_Blocked_Toggle_Format`, `Safety_AutoDisabled_Format`,
|
||||
`Safety_Unhooked_Format`, `Safety_RecordWithoutMeasuring`). `en` and `vi` written; **`ja` is the English
|
||||
verbatim under `safety: human review required`**, which `resx-audit` enforces. `Shared.Safety.SafetyDisclosure.Version`
|
||||
= `consent-dialog/1` (D14): `HelloAck.disclosureVersion` names what the Agent stamps against; the App's
|
||||
`HookingConsent` does not open the dialog on a mismatch (and says "restart both"), shows `ConsentPrompt`
|
||||
(WPF UI `ContentDialog`, primary button bound to the typed phrase, Enter keeps hooking off), and sends
|
||||
`SetHookEnabled { enabled: true, disclosureVersion }` — the version it showed, never a timestamp. The Agent's
|
||||
handler re-runs the pre-scan, compares the version to its own, and **stamps `ConsentProvenance.ConsentDialog`
|
||||
from its own clock** (`HookEnabledAck { enabled, outcome, prescan: "clean" }`) or answers the new
|
||||
`Error DisclosureVersionMismatch` with nothing written; `DisclosureUnavailable` remains for a composition
|
||||
that wired no version. `PipeClient.RequestEnvelopeAsync` lets the App tell a `Refused` from a
|
||||
`HookEnabledAck` (both are answers, neither is an error). `ConsentProvenance` has four names and
|
||||
`GameConsentRecordTests` pins them with the number. Tests: `HookingConsentTests` (App: the handshake gates the
|
||||
dialog, a declined dialog sends nothing, the request carries our version, stamped / refused / error each come
|
||||
back as what they are, the phrase is exact), `SafetyStringsTests` (every key in three languages through the
|
||||
satellites, vi translated, ja the English, no recommending word in any consent string), the handler's
|
||||
mismatch and stamp cases with a fake clock, and the real pipe end to end: wrong version → mismatch, our
|
||||
version → `ConsentDialog` on the row with the Agent's clock. Docs: `19_SAFETY` §User-facing consent (built;
|
||||
the console verb is the developer path), `09_I18N` (four members; the family arrived), `07_IPC` (`HelloAck`,
|
||||
`SetHookEnabled` as built), `06_DATA_MODEL` (the fourth name), HANDOFF item 2 and row 4 struck, D14 as built,
|
||||
CLAUDE.md. **Not in this PR:** the toggle that opens the dialog, FR-2.2's disabled state and FR-2.5's InfoBar
|
||||
are the game page's (PR-5); the `ja` review is a human's.
|
||||
- **P3 PR-3 — the ports the UI reads and writes, the settings registry (D16), schema 0002, and the display
|
||||
producer (2026-09-13).** `ISessionRepository` gains `FindByIdAsync`, `ListByGameAsync` (newest first, bounded),
|
||||
`SummariseByGameAsync` (count, hooked count, playtime, last played per game — one query), `FindSegmentsAsync`,
|
||||
`FindSensorsAsync`; `ISessionAnnotationRepository` (new) writes the UI-owned row beside a session — tags as a
|
||||
JSON array, notes, and **FR-8.3's per-session overrides, which live on `session_annotations` and never on
|
||||
`sessions`** (`06_DATA_MODEL` §Writer ownership), beside the measurement rather than over it, so clearing one
|
||||
restores what was measured; `Application.TriState.TriStateResolution` is the precedence (manual → measured →
|
||||
inherited from `games.*_default` → N/A). `IGameRepository` gains `FindByIdAsync`, `UpdateMetadataAsync` (FR-1.3,
|
||||
wholesale; every field that changed is marked `user` in `field_provenance` so detection cannot overwrite it),
|
||||
`SetTriStateDefaultAsync`, and `RemoveAsync(keepSessions)` (FR-1.4: keep = `games.removed_at`, the row leaves
|
||||
the library and a later launch restores it; delete = the cascade). `ILegalAcceptanceStore.RecordAsync` /
|
||||
`ListAsync` (the writer FR-11's gate calls in PR-9). `GameRow` now carries the metadata, the tri-state defaults,
|
||||
`hook_consent_at`, `hook_prescan_state` and `removed_at`. **The settings registry**: `SettingsRegistry` (12 keys,
|
||||
kind, default, range or choices, who reads) and `RegisteredSettings` over `ISettingsStore` — validating writes,
|
||||
tolerant reads, nothing cached; `SettingsRecorderPolicy` resolves `capture.min_session_s`,
|
||||
`retention.raw_sessions_per_game` (0 = unlimited) and `telemetry.interval_ms` at each session start through
|
||||
the new `IRecorderPolicy` on `SessionRecorder`, whose poller factory now takes the session's options; the
|
||||
App's appearance keys are the registry's. `0002_annotation_overrides_and_removal.sql`, the first append
|
||||
(`LatestVersion` = 2). `Infrastructure.Recording.PrimaryDisplay` fills `hardware_snapshots.display_res` /
|
||||
`display_hz` from `EnumDisplaySettingsW` — they were "null until P3" since PR-B. Tests: the four PR-B adapters
|
||||
that had none (`SqliteGameRepositoryTests`, `SqliteHardwareSnapshotRepositoryTests`, `SqliteSettingsStoreTests`,
|
||||
`SqliteLegalAcceptanceStoreTests`), the annotation repository incl. the resolution over stored rows, the
|
||||
session queries incl. **NFR-4 measured: a 100-session game lists in a few ms against the 500 ms ceiling**,
|
||||
the registry both directions, the policy, the resolution, the display producer. `20_OPEN_QUESTIONS` §G's
|
||||
"Settings registry" row is closed; `06_DATA_MODEL` gains §Settings registry and the 0002 note; HANDOFF §P3
|
||||
row 3 is struck with the one deviation (no `IRtOverrideRepository` — see above).
|
||||
- **P3 PR-2 — the first `.resx` family, its generator and its gate, and the App shell (2026-09-13).**
|
||||
`src/FrameLedger.App/Strings.resx` + `.vi` + `.ja` (65 keys, `ja` machine-drafted and marked `review`),
|
||||
`tools/resx-gen.ps1` writing the committed `Strings.Designer.cs` (the SDK-style WPF project runs no
|
||||
`ResXFileCodeGenerator`), and `tools/resx-audit.ps1` as `build.ps1` step 15 — self-test (11 fixture
|
||||
cases, both directions) then live: identifier keys, exact key sets across the three files, `Safety_*`
|
||||
in `ja` marked `safety: human review required` with the English verbatim or `safety: reviewed by <name>`,
|
||||
the accessor current; a tree with no family is red. `09_I18N` §Translation workflow and §Safety-critical
|
||||
strings, `12_BUILD` line 15, `13_CI_CD` and `CLAUDE.md` stop saying the tool does not exist. The App is a
|
||||
Generic Host under `16_WPFUI_SYNTAX` §App bootstrap: `FluentWindow`, TitleBar with the Agent pill, the
|
||||
Menu row (unbuilt items say so in a snackbar), NavigationView (Dashboard · Games · Compare · Logs, Settings
|
||||
in the footer), the offline `InfoBar` with Retry, `SnackbarPresenter`, `ContentDialogHost`; theme
|
||||
(Light/Dark/System with `SystemThemeWatcher`) and language (rebuilds the shell in the new culture) both
|
||||
persisted in `settings` under D16's `ui.theme`/`ui.language` through `SqliteSettingsStore` — the App opens
|
||||
`ledger.db` directly per `06_DATA_MODEL` §Writer ownership (D15). `Services.AgentConnection` is `07_IPC`
|
||||
§Client behavior as a state machine over `PipeClient`: 8 × 250 ms connect, start `FrameLedger.Agent.exe
|
||||
--serve` beside the App when absent, `Hello`/`GetStatus`, keepalive pings, the event stream, retry every
|
||||
5 s; the Dashboard's Agent card shows `HelloAck`/`StatusAck` with `N/A` until answered. Serilog
|
||||
`logs/ui-.log` per `10_LOGGING`. `tests/FrameLedger.App.Tests` (16): every key resolves in en/vi/ja and
|
||||
the satellites really load, the accessor's keys are the resx's, appearance settings round-trip, and the
|
||||
connection against an in-process `PipeServer` — Missing with nothing to start, Connected on `Hello`,
|
||||
Starting → Connected through a launcher that brings the server up, Offline then Connected again when it
|
||||
returns. Measured: first window at 1.3 s. Three things `16_WPFUI` now records: `MainWindow` is transient
|
||||
with `ShutdownMode=OnExplicitShutdown` and the host lifetime ending the process; the run is one task from
|
||||
a synchronous `OnStartup`; and `ApplicationThemeManager.Apply(…, updateAccent: true)` must precede the
|
||||
first window's XAML or the accent resources are missing at first Measure (`XamlParseException`).
|
||||
- **P3 PR-1b — the command pipe, command half: `SetWatchlist`, `LaunchGame`, `SetHookEnabled` (pre-scan, no stamp
|
||||
yet), pause/resume, `StopSession`, `UpdateRules`, `Shutdown` (2026-09-13).** `Application.Ipc.AgentCommandHandler`
|
||||
answers every UI → Agent row of `07_IPC` §Messages under the one rule of §The pipe is not a trust boundary — the
|
||||
Agent establishes each fact itself. `SetHookEnabled false` revokes through the store; `SetHookEnabled true` runs
|
||||
the static pre-scan of the executable's directory, records a block or a "could not verify" through
|
||||
`RecordGuardBlockAsync` and answers `Refused { reason, family?, signal? }`, and answers a clean scan **`Error
|
||||
DisclosureUnavailable` with nothing stamped** — FR-2.1's reviewed text does not exist (PR-4), and a client's
|
||||
`disclosureVersion` is a claim, not a disclosure shown. `SetWatchlist` ensures identity rows (hooking off when
|
||||
new) and removes nothing; `UpdateRules` is the seeder's outcome and ignores any payload; `Shutdown` asks
|
||||
`IAgentLifetime` (the host's under `--serve`, a logged no-op under `--console`). `PauseCapture`/`ResumeCapture`
|
||||
flip `CapturePause`, one in-memory flag every session loop reads at its tick and tells the ring once per
|
||||
transition — supervision never pauses — and `StatusAck` gains `paused`. `StopSession` cancels the session's own
|
||||
stop token (`RecordRequest.StopToken`; the orchestrator now names every session it starts, `RecordRequest.SessionGuid`),
|
||||
which the loop reads at its next tick and ends as the new `SessionEndReason.StoppedByUser`: drained once more,
|
||||
finalized, `exit_status = normal`, the target left running. `LaunchGame` is `CaptureOrchestrator.LaunchAsync`
|
||||
over the new `ILaunchRecorderFactory` (the Agent's `AgentLaunches`: the Vulkan layer's environment unless the
|
||||
kill switch is on, the console's `launch` shape), one session per game, the launcher election after. The
|
||||
orchestrator's running-session table has one lock now that the pipe's tasks reach it (HANDOFF §P3 D12 as built:
|
||||
no `Channel`). `IExecutableIdentitySource` gains `Normalise`, so a client's spelling is never a key. In the gate:
|
||||
`AgentCommandHandlerTests` (over the real SQLite consent store: the block recorded, nothing stamped, a path in
|
||||
an `UpdateRules` payload ignored), `CaptureSessionTests` (a stop token ends as `StoppedByUser` with the last drain
|
||||
run; the pause told once per transition while the guard keeps scanning), `CaptureOrchestratorTests` (stop
|
||||
cancels the request's own token; launch once per game, refused for what it cannot name, the environment
|
||||
released with the session), and `PipeEndToEndTests` grows two scenarios over the real Agent composition and a
|
||||
real ring: the watched harness narrated → paused (status says so, state stays `capturing`) → resumed → stopped
|
||||
by guid (`StoppedByUser`, `normal`, harness still alive) → the session-less commands, including a real pre-scan
|
||||
answered `DisclosureUnavailable`; and `LaunchGame` starting the harness in launch mode and narrating it to
|
||||
`TargetExited`. **Measured on the way:** wiring the command handler into the request handler eagerly is a DI
|
||||
cycle (server → handler → commands → orchestrator → recorder → observer → publisher → server) that the
|
||||
container did not refuse and the first e2e run HUNG on (`--blame-hang` dump, 2026-09-13); the command handler is
|
||||
resolved lazily on the first command, and the e2e now writes the composition's Serilog lines to its scratch
|
||||
directory so the next hang leaves evidence. **Not in this PR:** the consent stamp (PR-4) and the App (PR-2).
|
||||
|
||||
- **P3 PR-1 — the command pipe, read half: `Shared.Ipc`, the Agent's pipe server, the session narration and the
|
||||
1 Hz live progress (2026-09-13).** `FrameLedger.Shared.Ipc` holds channel C's contract (`07_IPC` §C): the
|
||||
envelope, the read-half message set (`Hello`/`HelloAck`, `GetStatus`/`StatusAck`, `Ping`/`Pong`, `Error`, and
|
||||
the seven Agent → UI events), `IpcJsonContext` (source-generated, camelCase, nulls omitted, unknown members
|
||||
skipped both ways — pinned) and `IpcFraming` (4-byte LE length + UTF-8 JSON ≤ 1 MB, one write per frame, every
|
||||
refusal driven). `Infrastructure.Ipc.PipeServer` creates `\\.\pipe\FrameLedger.v2` through `CreateNamedPipe`
|
||||
with the DACL stated as SDDL (`D:P(A;;GA;;;<user>)(A;;GA;;;BA)`, `PipeAccessControl` — what §G asked for),
|
||||
`PIPE_REJECT_REMOTE_CLIENTS`, two instances with a slot each so a third client waits, and the client's token
|
||||
user compared by impersonation on its first frame; a stranger is disconnected without an answer and counted.
|
||||
`PipeClient` is the UI's end (`CurrentUserOnly`, acks correlated by id, events on a channel). `Application.Ipc`:
|
||||
`AgentRequestHandler` answers the three requests (`ProtocolMismatch` / `UnknownType` / `Malformed` /
|
||||
`HandlerFaulted` as `Error`, connection kept), `SessionEventPublisher` is the recorder's new second observer
|
||||
(`ISessionObserver`, decision D13) — `SessionStarted` at the attach, `SessionProgress` once a second and only
|
||||
while a client listens, the finished session's events through `RecordedSessionEvents` (the reason → event
|
||||
table, pinned per reason) — and `AgentStatus` is the snapshot `GetStatus` reads. `SessionProgressCalculator`
|
||||
computes the live window through the SAME Domain calculators as the row, and rule 6 holds at the wire:
|
||||
Native / Displayed / factor only when frame generation was measured, else the presented rate with the census
|
||||
qualifier — now `FgLadder.PresentedQualifier`, one function for the row and the pipe. The Agent hosts it under
|
||||
`--serve` only (`PipeServerHostedService`); `--console` composes it inert. `HelloAck` drops `etwAvailable`
|
||||
(the tier is gone) and gains `pid`; `vulkanLayerRegistered` and `cpuTempAvailable` are honest falses.
|
||||
`CaptureOutcome.Verdict` now carries the verdict that FIRED on a safety unhook, so `SafetyUnhook` names its
|
||||
family and signal. `Vocabulary.ExitStatusText` is the one spelling of `exit_status` for the column and the
|
||||
event. In the gate: `IpcFramingTests`, `IpcCodecTests`, `PipeServerClientTests` (a real pipe, in-process, incl.
|
||||
the refused stranger and the waiting third client), the calculator / events / publisher suites, and
|
||||
`PipeEndToEndTests` (Integration, `agent-harness`): the Agent's own composition in-process on a test-named pipe,
|
||||
the watcher finding `hook-harness`, and a client hearing `SessionStarted` → ≥ 3 `SessionProgress` a second apart
|
||||
→ `SessionCompleted` for the same guid. **One thing that test measured on the way (2026-09-13):** the watcher's
|
||||
file-name fallback (`ProcessWatcher`, `StalePath`) adopted a sibling test assembly's `hook-harness.exe` running
|
||||
from another directory, started a session for it, and refused it for want of consent on THAT path — so the
|
||||
test's target is now a byte-identical copy of the harness under a run-unique name, and the story is keyed on
|
||||
the pid and the guid. Recorded because the same fallback would adopt a second install of a tracked game on a
|
||||
real machine; whether that is the wanted behaviour is `04_CAPTURE` §Process watcher's question, not this PR's.
|
||||
**Not in this PR:** the command half (PR-1b), the App that connects (PR-2), and any keepalive the Agent
|
||||
initiates — `Ping` is the client's.
|
||||
|
||||
- **P2 PR-G — kill-and-recover end to end, the FPS-impact runbook, and P2's closing sweep (2026-09-10).**
|
||||
`PartialRecoveryEndToEndTests` (Integration, in the merge gate) is `14_TESTING`'s long-standing
|
||||
`.partial` line, built: the shipped `FrameLedger.Agent.exe` captures `hook-harness` with the new
|
||||
`--console … --partial-flush-seconds <n>`, the test polls until a flush has actually landed, kills the
|
||||
Agent, and `--console recover` turns the valid prefix into an `interrupted` row whose `frame_count` is
|
||||
that prefix, deletes the file, and finds nothing on a second pass. The new option is under `--console`
|
||||
only and pinned by `AgentCommandLineSurfaceTests` beside the others: it bounds how often a running
|
||||
session writes its own crash-recovery file and names nothing about injection.
|
||||
`tools/fps-impact-runbook.ps1` (dev-only, never in `build.ps1 check`) sequences item 2's six launches —
|
||||
consent granted for the ON leg, revoked for the OFF leg, the same launch path both times so the only
|
||||
difference is the injection — reads the Agent's CPU and RSS, prompts for the game's own benchmark
|
||||
average, and prints the `spike-notes` §14 block. **It does not measure FPS and says so first:**
|
||||
FrameLedger's frame times exist only in the hooked leg. `spike-notes` §14 holds the three empty slots
|
||||
(the milestone row against a title's menus, §S1's launcher-fronted election, the FPS table) with the
|
||||
exact commands; `14_TESTING` item 2 now says *unmeasured* rather than nothing. **P2's code is complete;
|
||||
what remains are two measurements only the owner can take.**
|
||||
|
||||
- **P2 PR-F — the Agent host: `--serve` (watcher → orchestrator → recorder), `--console` verbs, the consent
|
||||
grant (decision D4) and the kill switch as the gate's fourth input (decision D7) (2026-09-10).**
|
||||
`FrameLedger.Agent` is a Generic Host now: `Composition.AgentServices` registers every `Application` port
|
||||
to its one shipped adapter, `WatcherHostedService` runs `PartialRecovery` first and then
|
||||
`Application.Watch.CaptureOrchestrator` — one process snapshot per second (`ToolhelpProcessSnapshotSource`),
|
||||
`ProcessWatcher` (exact normalised path, or the file name when exactly one `games` row carries it →
|
||||
`StalePath`, keyed on the real path), `ProcessTree` (a child that started before its parent is a reused
|
||||
pid), `DescendantElection` (the newest tracked descendant; a launcher's consent does not extend to what it
|
||||
spawns), ONE session per game at a time through the new `ISessionRecorder` port. `--console` carries
|
||||
`consent list|grant|revoke`, `capture`, `launch` (with the election after `LaunchTargetExited` /
|
||||
`LaunchNoPresentationRuntime`), `recover`, `sessions`, `db path`, `games add`, `killswitch on|off|status`,
|
||||
and `--data-dir` under `--console` only (decision D6); `--diag`, `--install-task`, `--uninstall-task`,
|
||||
`--register-vklayer`, `--unregister-vklayer` answer "not implemented in P2", exit 2. **D4:** `Agent
|
||||
--console consent grant` shows `OperatorDisclosure` (moved to `Application.Consent`, one text, an
|
||||
`OperatorSurface` for the first line and the stamp), refuses redirected stdin, and records the new
|
||||
`ConsentProvenance.AgentConsoleOperator` with the Agent's clock; `OperatorAcknowledgement` carries its
|
||||
provenance and `SqliteGameConsentStore` writes that name and refuses `NotRecorded`. **D7:** FR-2.4 is
|
||||
`HookRequest.FromConsent`'s fourth input — `AntiCheatRefusalReason.KillSwitchEngaged` (27, added to the
|
||||
native reason table so the mirror holds), checked before consent is read; `IKillSwitch`
|
||||
(`Infrastructure.Settings.SettingsKillSwitch` over `settings.hooking.kill_switch`) is read by
|
||||
`CaptureSession` before the request and at every guard-scan boundary, where an engaged switch publishes
|
||||
`unhookRequested` and ends the session as `KillSwitchEngaged` (`RefusedKillSwitch` when refused up front);
|
||||
`ProcessLauncher(enableVulkanLayer: false)` keeps the layer off by never setting
|
||||
`FRAMELEDGER_ENABLE_VK_LAYER`. A bounded `--console capture --seconds N` lowers the discard threshold to N.
|
||||
Tests: `AgentEndToEndTests` (Integration, in the gate) runs the shipped `FrameLedger.Agent.exe` against
|
||||
`hook-harness` with a scratch ledger and reads back ONE hooked `sessions` row — the milestone's technical
|
||||
half — plus the kill-switch refusal with no ring in the target, `consent grant` refusing redirected stdin,
|
||||
and the unbuilt flags' exit 2; `AgentCommandLineSurfaceTests` pins the surface (no pid, payload, force,
|
||||
yes, override); `ProcessWatcherTests`, `ProcessTreeAndElectionTests`, `CaptureOrchestratorTests`,
|
||||
`ToolhelpProcessSnapshotSourceTests` (this process and a child it starts), `SettingsKillSwitchTests`, the
|
||||
gate's `TheKillSwitchIsTheFourthInputAndOutranksAValidConsent`, the loop's
|
||||
`AnEngagedKillSwitchRefusesBeforeTheGuardAndStopsARunningSessionAtTheNextScan`, and the store's
|
||||
provenance round-trip. The capture host uses the moved disclosure unchanged.
|
||||
|
||||
- **P2 PR-E2 — the NVAPI bridge: `FrameLedger.NvapiBridge.dll`, L3 `NvapiTelemetrySource`, and the NGX probe
|
||||
in-process (2026-09-10).** A new native target, `src/native/FrameLedger.NvapiBridge/` — a C ABI
|
||||
(`fl_nvapi_bridge.h`: refcounted `FlNvInit`/`FlNvShutdown`, `FlNvReadSample` into a fixed struct with a
|
||||
`present` bit per field, `FlNvNgxState` for one pid, `FlNvDriverVersion`, and size / ABI-version / build-id
|
||||
queries so a drifted mirror is refused rather than read) — is the **only shipped binary that links
|
||||
`nvapi64.lib`**, read-only by construction, loaded by the Agent into its own process by absolute path
|
||||
(`/FrameLedger.NvapiBridge.targets`, imported by the Agent, the capture host and `Infrastructure.Tests`)
|
||||
and **never into a game**. `Infrastructure.Telemetry`: `NativeNvapiBridge` (the second P/Invoke facade after
|
||||
the guard's, same absolute-path rule), `NvapiTelemetrySource` (L3 — a clear bit is `null`, never 0; an `Init`
|
||||
that does not answer 0 disables the layer with zero faults, two throws disable it for the session; VRAM is
|
||||
**not** read, because the vendored `nvapi.h` declares neither a non-deprecated memory-info call — L1's PDH
|
||||
counter keeps it), and `NvapiNgxStateProbe`, the `INgxDriverProbe` in-process. The capture host composes
|
||||
L1 + L2 + L3 under the composite (`telemetry_source` can now read `l1+lhm+nvapi`) and **no longer spawns
|
||||
`fl-probe-nvapi.exe`**; the probe is no longer staged beside it. `Infrastructure.Native.BesideThisAssembly`
|
||||
is the assembly's one `DllImport` resolver — the runtime allows one per assembly, and the guard's static
|
||||
constructor already set it, which the first real-hardware test run found. ctest `fl_nvapi_bridge`
|
||||
(`src/native/tests/nvapi_bridge_test.cpp`) exercises every export and requires the `BRANCH:` line;
|
||||
`NvapiBridgeMirrorTests` checks both mirrors' sizes against the DLL's answers and **fails rather than skips**
|
||||
when the DLL is not staged; `NvapiTelemetrySourceTests` and `NvapiNgxStateProbeTests` script the bridge.
|
||||
`tools/versioninfo-check.ps1` requires the new DLL's version block. Measured on the dev box (RTX 5080,
|
||||
driver 616.64 r616_41) and written into `18_GPU_VENDOR_APIS` §L3: core 35 °C, GPU domain 0 %, 2670 / 15001
|
||||
MHz, throttle mask 0, PCIe ×16, memory-temperature and fan bits clear at an idle desktop.
|
||||
|
||||
- **P2 PR-D — the session recorder: `.partial`, five-step finalize, exit classification, crash auto-disable,
|
||||
recovery; the first hooked session stored in SQLite (2026-09-10).** `Application.Recording`:
|
||||
`SessionRecorder` owns a session end to end — identity and QPC time base, the `games` and
|
||||
`hardware_snapshots` rows, one telemetry poller per session, the `.partial` from before the first record
|
||||
to after the last, the loop, the classification, the finalize, the crash policy — on the loop's own task
|
||||
through the new `ICaptureObserver` seam on `CaptureSession` (after every drain: the poller's queue drained,
|
||||
the file flushed on its interval; the loop stays the ring's only reader). `SessionAggregator` fills every
|
||||
measured column of `sessions` and `session_segments` over Domain's calculators; `FgLadder` is the identity
|
||||
and withhold logic MOVED out of the capture host's report so the row and the report read ONE
|
||||
implementation (the report's strings and fixtures unchanged); `Vocabulary` is the tokens the schema stores.
|
||||
`SessionFinalizer`: the discard rule, then the FULL `frame_blobs` set through the new `ISeriesCodec` port —
|
||||
every column any record claimed, `latency_us` included, pinned by a reflection sweep of the DTO —
|
||||
per-stream frame times with the gap bit where an interval is not a frame time (torn slot, overwrite skip,
|
||||
first of a stream), `swapchain_ids` only past one stream, sensor series aligned to `t_ms` with −1 where a
|
||||
tick had no reading; then one transaction and the retention sweep. `ExitStatusMapper` is `04_CAPTURE`'s
|
||||
table as one function (safety stop → `unhooked_safety`; the capture side stopping on its own →
|
||||
`degraded`; non-zero exit code or an Application Error/WER event naming the exe in `[start, end+30 s]` →
|
||||
`crashed`); `CrashAutoDisablePolicy` counts only crashes within 60 s of the attach and disables on the
|
||||
second. The `.partial` (`06_DATA_MODEL` §The `.partial` file): CRC-framed append-only chunks, the valid
|
||||
prefix wins, `PartialSessionFileTests` kills a fixture at every byte offset. `PartialRecovery` turns every
|
||||
pending file into an `interrupted` row or drops it for a stated reason. `Infrastructure.Recording`:
|
||||
`PartialSessionFile`/`Store`, `EventLogCrashSource` (Application log 1000/1001, read-only), `HardwareSnapshotSource`
|
||||
(DXGI identity + registry CPU name + runtime memory + OS build; display fields null until P3);
|
||||
`DrainResult` gained `FirstSlot` so a torn slot is recorded at the RECORD it preceded; `ITargetLiveness`
|
||||
gained `ExitCode`; `TelemetryPoller` can own its source. **The unshipped host records through all of it**
|
||||
(`capture`/`launch` print `ledger: session … SAVED as sessions.id=N`, a 5 s discard threshold for bounded
|
||||
operator captures, a `recover` verb), and `CaptureHostEndToEndTests` now asserts the row, the blobs and the
|
||||
deleted `.partial` after a real launch — the first hooked session in a `ledger.db`. **One native change,
|
||||
measured on the way:** `fl_guard`'s launch-mode classification read the harness's `--vulkan` mode as
|
||||
OpenGL once the warmer host reached the first poll 20 ms sooner (opengl32 is a static import of the
|
||||
binary, vulkan-1 is mapped milliseconds later), injected the Overlay and left the layer's ring unowned;
|
||||
the guard now polls once more before committing to the injecting branch, pinned in both directions in
|
||||
`guard_test`. Hook-path overhead: none (the guard change is pre-injection; the Overlay is untouched).
|
||||
`04_CAPTURE` §Session recorder/§Crash & exit/§Launch mode, `06_DATA_MODEL` §The `.partial` file/§Blob
|
||||
encoding, `20_OPEN_QUESTIONS` §G "Session identity", `CLAUDE.md` §Solution layout.
|
||||
- **P2 PR-C — the capture path promoted into the shipped assemblies; the CaptureHost is a thin shell
|
||||
(2026-09-09).** A pure move: `CaptureLoop` — every hooked session's driver since 2026-08-06 — is now
|
||||
`Application.Capture.CaptureSession`, over ports instead of delegates so the Agent's composition root
|
||||
can supply the adapters (`IRingAttacher`, `ITargetLivenessSource`, `ITargetResolver`, `IProcessLauncher`,
|
||||
`IRuntimeModuleSnapshot`, `INgxDriverProbe`, `IExecutableMarkerScan`), with `ICaptureSink`,
|
||||
`CaptureOptions`, `CaptureOutcome` (was `CaptureResult`), `SessionEndReason`, `SessionEndClassifier`,
|
||||
`FocusTally`, `RuntimeModuleSet`/`Info`, `CensusNames`, `SlTagCensusNames`, `ExecutableMarkers`/`Marker`,
|
||||
`NgxDriverState`/`NgxOverrideFlags`/`NgxProbeOutcome` beside it. `Infrastructure.Capture` holds the OS
|
||||
adapters: `ShmRingAttacher` + `ShmCaptureSink` over `ShmRingReader` (which gains no interface and no
|
||||
second consumer), `HeldProcessLivenessSource` + `ProcessTargetLiveness` (§S29(e)), `TargetResolver`
|
||||
(path only, never a pid; its one report line goes through a callback now, not the host's console) +
|
||||
`ChromiumGpuProcess`, `ProcessLauncher` (an instance over the Vulkan layer's environment, the
|
||||
duplicated enable-variable constant gone), `RuntimeModuleSnapshot`, `ExecutableMarkerScan`.
|
||||
`DrainResult` moved to `Shared` so Application can read it. The report's text for NGX state and
|
||||
markers stays with the report (`NgxDriverStateText`, `ExecutableMarkersText`); `NgxDriverProbe`
|
||||
(spawns `fl-probe-nvapi.exe`) stays in the host until PR-E2 puts it in-process. The loop's tests moved
|
||||
with it — `CaptureSessionTests` / `CaptureSessionLaunchTests` in `Application.Tests`, driven through the
|
||||
real SQLite consent adapter (a test project on Domain's `InternalsVisibleTo` would be a second mint) —
|
||||
and the report fixtures are byte-identical. Two new pins: `HookRequestSoleProducerTests` (no public
|
||||
constructor, no setter, exactly one factory) and `NoSecondRingReaderTests` (nothing but `ShmRingReader`
|
||||
opens the ring). `04_CAPTURE` §Frame source abstraction now describes what exists (`IFrameSource` never
|
||||
did) and gains §Threading model; §S27 restated a second time (the loop ships; the entry point is PR-F's);
|
||||
`CLAUDE.md` §Solution layout. Hook-path overhead: none (managed only).
|
||||
- **P2 PR-E1 — telemetry L1, the composite and the 1 Hz thread (2026-09-09).** `IGpuTelemetrySource`
|
||||
had one adapter; it now has the ladder `18_GPU_VENDOR_APIS` §Abstraction describes.
|
||||
`BaselineTelemetrySource` (L1) reads the adapter's identity from DXGI once — name, LUID, ids, memory
|
||||
sizes, the user-mode driver version via `CheckInterfaceSupport(IDXGIDevice)` — as `GpuAdapterIdentity`,
|
||||
selects the first hardware adapter until the Overlay's handshake LUID names another, and carries one
|
||||
live field: adapter-wide dedicated memory in use from the PDH `GPU Adapter Memory … Dedicated Usage`
|
||||
counter bound by LUID (never a wildcard summed). **Measured on the way:** `IDXGIAdapter3::
|
||||
QueryVideoMemoryInfo`, which the doc listed as L1's adapter-wide usage, reports the *calling process's*
|
||||
usage — 0 bytes from the Agent beside a 16 GB adapter — which is exactly why the Overlay reads it
|
||||
in-process; the doc is corrected, not the number. The engine-utilisation counters are deliberately not
|
||||
read (`20_OPEN_QUESTIONS` §M10 decided: `LoadPct` is L2's vendor-reported load, labelled). `DxgiAdapters`
|
||||
and `PdhAdapterMemoryCounter` are the tree's first CsWin32 consumers (marshaling off: raw vtables, no
|
||||
apartment). `CompositeTelemetrySource` merges L3 > L2 > L1 per field, records which layer supplied
|
||||
each (`LayerOf`), applies the two-fault rule one level up to a layer whose `TryRead` throws, and
|
||||
produces the `l1+lhm+nvapi` descriptor from the layers still standing — the port gained `IsDisabled`
|
||||
so "nothing yet" and "never again" stop reading alike. `TelemetryPoller` is the `fl-telemetry` thread:
|
||||
one read per interval (≥ 500 ms), stamped with QPC (`TelemetrySample`), queued for the session loop,
|
||||
oldest dropped and counted when nobody drains. `QpcClock` names the counter the ring is in, and
|
||||
`QpcClockTests` pins `Stopwatch` / `TimeProvider.GetTimestamp` to it rather than trusting the
|
||||
documentation. §M7 and §M8 closed by the code taking the shape they asked for. Hook-path overhead:
|
||||
none (managed only, nothing in the game). `18_GPU_VENDOR_APIS` §Abstraction/§L1/matrix, `CLAUDE.md`
|
||||
pinned-stack row corrected in place.
|
||||
- **P2 PR-B — the SQLite ledger: `0001_init.sql`, migrations, the consent adapter, the repositories, the
|
||||
blob codecs (2026-09-09).** `Microsoft.Data.Sqlite` and `Dapper` were referenced by zero lines; they now
|
||||
back `Infrastructure.Persistence`: `LedgerDatabase` (WAL, `synchronous=NORMAL`, `foreign_keys=ON`,
|
||||
`busy_timeout=5000`; one connection per process behind a gate; every write an explicit transaction),
|
||||
`MigrationRunner` (scripts embedded in the assembly, one transaction each, under a session-local mutex;
|
||||
a ledger NEWER than the build's scripts is refused — `LedgerSchemaException` — not read on a guess),
|
||||
and `0001_init.sql`, the `06_DATA_MODEL` v2 schema plus the columns it had no home for: `session_guid`,
|
||||
`qpc_epoch` / `qpc_frequency`, `capture_mode`, the drain's own accounting, the 2026-09 metric additions
|
||||
(Presented FPS + qualifier, DXGI-COUNTED, tag census, the driver-reported rungs, the withheld `none`),
|
||||
`fg_source` with `none` in its domain and NULL = not measured, `games.hook_prescan_state` (the third
|
||||
pre-scan state one nullable reason could not carry; nothing clears `hook_blocked_reason`), the consent
|
||||
provenance and disclosure version, and the fingerprint. Every `*_at` is unix-ms UTC, stated in the
|
||||
script. **`SqliteGameConsentStore` replaces the capture host's file store** — same semantics, every case
|
||||
of `FileGameConsentStoreTests` re-targeted (`SqliteGameConsentStoreTests`): a grant cannot clear a
|
||||
block, a block preserves the stamp, a revoke withdraws it, a default verdict is `unverified` and never
|
||||
a block, a re-grant against a different binary cannot inherit a block, an unreadable ledger answers
|
||||
`Failed` and consents to nothing. **It ships**, and `20_OPEN_QUESTIONS` §S27 is restated on that basis
|
||||
(`Domain.csproj`'s `InternalsVisibleTo` names Infrastructure now, not the CaptureHost). The unshipped
|
||||
host opens its OWN `ledger.db` beside its binary (HANDOFF §P2 decision D5) — the Agent stays the sole
|
||||
owner of `%LOCALAPPDATA%\FrameLedger` — and its e2e cases run through that ledger. Also new:
|
||||
`SqliteGameRepository` (the non-consent face of `games`: crash count, auto-disable, last injection),
|
||||
`SqliteSessionRepository` (row + segments + `frame_blobs` + `sensor_blobs` in ONE transaction — a failing
|
||||
blob insert leaves no row behind — `ExistsAsync` by guid for recovery, retention keeps the last N
|
||||
sessions' raw series and every aggregate), `SqliteHardwareSnapshotRepository` (hash-deduplicated),
|
||||
`SqliteSettingsStore`, `SqliteLegalAcceptanceStore` (read-only; FR-11 stays the UI's — decision D8),
|
||||
the Application ports and DTOs behind them (`SessionRow` column for column, generated with the SQL from
|
||||
one table so the INSERT, the parameters and the reader cannot drift), `Domain.Sessions` (`ExitStatus`,
|
||||
`CaptureTier`, `CaptureMode`), and `Infrastructure.Blobs.SeriesCodec` / `RenderResCodec`
|
||||
(`deflate-le-v1`, little-endian arrays through Deflate, NaN refused at encode time, two pairs per frame
|
||||
for `render_res`, all three RT bits preserved; 360k frame times round-trip under half their raw size).
|
||||
Hook-path overhead: none (managed only). `06_DATA_MODEL`, `04_CAPTURE` §The guard, `20_OPEN_QUESTIONS`
|
||||
§S27 and §G "Session identity", `CLAUDE.md` §Solution layout corrected in place. Also fixed in passing:
|
||||
`ShmDrainIntegrationTests.TheReaderReportsRecordsItLostWhileItWasNotDraining` read `INIT` instead of `READY`
|
||||
about one run in four (on unmodified `main` too) — the handshake is published before the present hooks and
|
||||
the present hook records before the READY store, so a case that laps the ring in ~50 ms could assert inside
|
||||
that window; it now polls, bounded, for the writer to leave `INIT` first.
|
||||
- **P2 PR-A — `FrameLedger.Domain.Metrics`, and the capture host's consumer re-pointed at it (2026-09-09).**
|
||||
The calculators `03_METRICS` says to implement in Domain now exist there, under `tools/coverage-gate.ps1`'s
|
||||
95 % per-class floor, which had never evaluated anything: `FrameTimeSeries` (QPC → ms, the interval
|
||||
spanning a gap EXCLUDED rather than counted as a long frame), `Percentile` (linear interpolation, NumPy
|
||||
`linear`), `FrameStatistics` (median / 1 % / 0.1 % lows as `1000 / p`, min / max, population σ, the
|
||||
FR-4.8 guards at exactly 1,000 and 10,000 frames, the `(presented)` label carried not decided),
|
||||
`RollingMedian` (19 frames, truncated symmetric at both edges) + `StutterDetector` (`> 2 × median`, stutter
|
||||
time %, `pso_stutter_pct`), `VramAggregates` / `LatencyAggregates` / `SeriesAggregates` (N/A, never 0).
|
||||
Ported out of `FrameLedger.CaptureHost` with their tests: `FgWindow` (the factor and every refusal —
|
||||
now a `FgRefusalKind` + numbers, the English staying with the report as `FgRefusalText`, byte-identical),
|
||||
`UpscaleExtent`, `StreamSegmenter` → `SegmentBuilder`, `RecordWindow` (generic), `Tri`, and the three
|
||||
tri-states as `RtVerdict` (`RtSummary` carries `rt_frame_pct` over presents and `rays_per_pixel` over
|
||||
RT-active presents, the ×4 falsifier pinned) and `HdrVerdict`. Domain references nothing, so the
|
||||
calculators consume `FrameSample` / `WriterFacts` with Domain's own enums; `FrameLedger.Application`
|
||||
gains a reference to `FrameLedger.Shared` (HANDOFF §P2 decision D1) and
|
||||
`Application.Metrics.FrameSampleMapper` is the one place a record becomes a sample, with the two
|
||||
writer-state sentinels (`VramBudgetMb = 0`, `DxgiPresentsBeforeHook = 0xFFFFFFFF`) resolved to null
|
||||
there. `MetricEnumMirrorTests` pins every Domain enum to its Shared twin in both directions — a member
|
||||
added on one side alone fails. `MeasuredFacts` keeps the prose (which N/A, which qualifier, the withheld
|
||||
`none`) and calls Domain for the numbers; every report fixture in `CaptureHost.Tests` passes unchanged.
|
||||
Not in this PR: the FG ladder as a Domain verdict (`fg_mode` / the withheld `none` are still
|
||||
`MeasuredFacts` strings) — it lands with the recorder that stores it (PR-D). Hook-path overhead: none
|
||||
(managed only). `03_METRICS` §header, `14_TESTING` §Golden metric tests (the FG-ladder row named two
|
||||
retired rungs and an "ambiguous → `none`") and `CLAUDE.md` §Solution layout are corrected in place.
|
||||
- **P1 item 4 — the unhook path, the native log, OpenGL (2026-09-06).** `StopObserving` no longer calls
|
||||
`MH_DisableHook(MH_ALL_HOOKS)`: every patch the Overlay made is in a registry, and each is restored
|
||||
**only while the bytes at its target are still our jump** (`fl_patch_check.h`; §H7 in its inline form —
|
||||
an overlay that patched after us chains through our jump and the blanket restore would have removed it
|
||||
silently). A fixed ring of structured events (`FAULT` with the exception code and the hook's name,
|
||||
`STOP`, `UNHOOK_RESTORED` / `UNHOOK_DECLINED` per patch, `HOOK_INSTALLED`, `SYMBOL_MISSING`,
|
||||
`SUPERVISION_LOST`…) is flushed to `%LOCALAPPDATA%\FrameLedger\logs\overlay-<pid>-*.log` at init, when
|
||||
the Agent bumps the new `FlControlBlock.logFlushRequested` counter at session end, and on the stop —
|
||||
never mid-frame; the CaptureHost prints the file and its notable lines. `opengl32!wglSwapBuffers` is
|
||||
hooked (`api` = OpenGL, output size from the DC's window, no `PRESENT_ARGS`), installed at init or lazily
|
||||
with the `LoadLibrary` detour waking the watchdog for `opengl32.dll`; `hook-harness --opengl
|
||||
--hold-presenting N` exercises it through gdi32's `SwapBuffers`. ctests `fl_unhook_inline`, `fl_guard`
|
||||
`[opengl]` / `[log]`. D3D9 is struck from the P1 line per `20_OPEN_QUESTIONS` §Scope decisions.
|
||||
- **P1 item 3 — the Vulkan layer intercepts `vkQueuePresentKHR` (2026-09-06; `20_OPEN_QUESTIONS` §S2 ✅).**
|
||||
In a process both gates admitted, the layer creates the same ring the Overlay would (`fl_shm_host.h`,
|
||||
now the one home of the DACL / name / handshake for both capture sides; one ring per process, first
|
||||
creator owns it) at the first `vkCreateDevice`, writes one record per present (`api` = Vulkan, output
|
||||
size from `vkCreateSwapchainKHR`'s `imageExtent`, no `PRESENT_ARGS` because the call has none), and
|
||||
forwards everything — including when the ring is not its own, which the first fixture run proved
|
||||
necessary. §S2 part three lands with it: `unhookRequested` and the 07_IPC tick deadline both stop the
|
||||
layer on the present path (passthrough with the reason on the mapping), proven by a fake loader chain
|
||||
(ctest `fl_vklayer`) and a 1.5 s test-only flavour of the DLL (`fl_vklayer_supervision`). The harness
|
||||
gains `--vulkan --hold-presenting N` (real loader via `LoadLibraryW`, hidden window, exit 77 = cannot
|
||||
run here) and ctest `fl_vklayer_real` drives it through the real loader with `VK_ADD_IMPLICIT_LAYER_PATH`
|
||||
— measured honoured by loader 1.4.357 with no registry — skipping on CI. Launch mode classifies a
|
||||
Vulkan-only target as the layer's (`TargetIsVulkanLayered` = 26: full guard, nothing injected, attach to
|
||||
the layer's ring) and the CaptureHost hands the launched process the layer's environment
|
||||
(`VkLayerLaunchEnvironment`: manifest, enable variable, enable-list line for the session).
|
||||
- **P1 item 2 — launch mode, built as "inject late" (2026-09-06; `20_OPEN_QUESTIONS` §S1 ◐, §S13(c) ✅).**
|
||||
The guard gains `FlGuardedInjectWhenReady(pid, dll, timeoutMs)`: it polls the launched target through
|
||||
the module seam — matching no blocklist — until a presentation runtime is mapped, then runs every
|
||||
check and injects exactly as `FlGuardedInject` does; a target that exits first or maps no runtime in
|
||||
the budget answers the new `LaunchTargetExited` / `LaunchNoPresentationRuntime` with nothing injected
|
||||
(ctest `fl_guard` `[launch]`, five cases incl. the real seam against `hook-harness`). The CaptureHost
|
||||
gains `launch --exe <path> [--args "…"] [--seconds n]` (`ProcessLauncher`: handle held from birth,
|
||||
`FRAMELEDGER_ENABLE_VK_LAYER=1`; the host never terminates what it launched), routed through the same
|
||||
gate by `HookRequest.WaitForPresentationRuntimeMs`, with `IAntiCheatGuard.GuardedInjectWhenReadyAsync`
|
||||
as the port's fourth method. The Overlay publishes `FlWriterState.dxgiPresentsBeforeHook` @60 — DXGI's
|
||||
count of presents before the first hooked one, the early-init cost §S1 deferred on — from the last
|
||||
reserved word (no layout bump; the writer state now has no slack), and the report prints it beside the
|
||||
measured wait. `04_CAPTURE` §Launch mode carries the shape and why it is not `CREATE_SUSPENDED`.
|
||||
- **P1 item 1 — the `LoadLibrary` detour, both jobs (2026-09-06).** The Overlay patches
|
||||
`kernelbase.dll!LoadLibraryExW` after its present hooks (`17_HOOK_ENGINE` §DLL entry step 3): a module
|
||||
the hook inventory or runtime census names **wakes the watchdog** through an auto-reset event, so the
|
||||
lazy installers run within milliseconds of the module instead of on the next 1 Hz tick (94 ms measured
|
||||
against a 500 ms bound); a module matching the compiled anti-cheat floor's MODULE families **stops the
|
||||
Overlay from inside** with the new `FL_STATUS_STOPPED_BLOCKLISTED`, on the next present or watchdog
|
||||
iteration — `20_OPEN_QUESTIONS` §S6 ✅, `19_SAFETY` §During a session's in-process half (exact names
|
||||
only; fragment and signer stay the host's 30 s scan, so the Disclaimer's window is unchanged). The
|
||||
detour installs nothing inline (§H2), calls the original first, and skips data-file / resource loads.
|
||||
Two `FlWriterState` words from `reserved[]` (`loaderSignals` @56, `earlyStopFamily` @58; no layout
|
||||
bump), `hook-harness --load-after-ms N PATH`, two real-Overlay ctest cases (`[loader]`, `[S6]`), and
|
||||
the CaptureHost's `loader detour:` / `EARLY STOP` report lines, `SessionEndReason.WriterStoppedBlocklisted`
|
||||
(exit 5) with the family named from the staged rules file.
|
||||
- **P0 closed — the closing sweep (owner: "theo bảng", 2026-09-06).** Exit criterion 1 is met with
|
||||
the quality preset amended to an honest `N/A` by measurement; criterion 2 is met with §S24 counting
|
||||
zero S-items against it. Three items closed by a gate each: **§S19(c)** — `rules-validate` gains a
|
||||
third canary proving the schema rejects `action: "allow"` and `signerField: "CN"`, so the policy is
|
||||
code and the data cannot say otherwise; **§S23-6** — the accuracy blocks are one text,
|
||||
`legal/ACCURACY.md`, embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4 and gated by
|
||||
`tools/accuracy-check.ps1` (self-tested both directions), and rewritten to 2026-09-06 truth (the old
|
||||
§4 still said frame generation and ray tracing had no hook); **§S29(d)** — `ci.yml` prints a Vulkan
|
||||
runtime census, and the blast-radius script runs as a CI step the day a runner has a loader, deferred
|
||||
on that measurement until then. Six items deferred with their rationale written and their phase named:
|
||||
S6 and S2 part three (P1), S23-3 (P3), S4 signing, S20 feed half and S14's store-id half (P4).
|
||||
`15_ROADMAP` and `HANDOFF` now say P1 starts.
|
||||
|
||||
- **The guard's signer half — the other conjunct of "name fragment AND not signed by a known vendor" —
|
||||
and the nine integration cases in the merge gate (§S19(b) row G1; owner's bound decision 2026-09-06).**
|
||||
Since 2026-08-05 the guard refused FrameLedger's own test host on CI because a .NET host loads
|
||||
`System.Security.Cryptography.ProtectedData.dll` and `protect` is a heuristic fragment, and CI skipped
|
||||
the drain, pause, drop and capture-host end-to-end cases. `fl-probe-signer`'s three legs (dev box, CI,
|
||||
the owner's adapters-disabled run) all read the same: the embedded signature verifies offline with
|
||||
`O=Microsoft Corporation`, ~2–4 ms, no verdict changing without a network. So `Sources` gained
|
||||
`ModuleSignerOrganisation` — `WinVerifyTrust` under `WTD_REVOKE_NONE | WTD_CACHE_ONLY_URL_RETRIEVAL`,
|
||||
then the certificate's `O=` — and the module sink trusts a fragment-matching module only when that
|
||||
organisation is on the rules file's `trustedSigners` AND on the list compiled into the binary
|
||||
(`IsCompiledTrustedSigner`: the data may narrow, never widen). A trusted module keeps the scan
|
||||
looking; the target is judged like its ancestors; no signature, an invalid one, an unreadable `O=`, a
|
||||
null path or seam, a failing seam, one list without the other — all refuse. The catalog half stays
|
||||
deferred with its rationale. `hook-harness --load` proves both directions against the real seams
|
||||
(the NuGet blocker allowed; our own unsigned Overlay under a `protect` name refused, by name); nine
|
||||
fake-seam cases pin the decision. `ci.yml` runs `./build.ps1 check` with no switches; the switch stays
|
||||
in `build.ps1`, loud. `19_SAFETY`, §S19(b), §S29(a), `13_CI_CD`, `12_BUILD`, `HANDOFF` and the rules
|
||||
file's own comment carry it.
|
||||
|
||||
- **Rung 3 by elimination, and the executable file as the census's second witness (HANDOFF 7b / §H11,
|
||||
owner's choice 2026-09-06).** `frame generation: Active (technology not identified)` now prints every
|
||||
exclusion the session can make beside it — not DLSS-G when the NVIDIA driver's FG word reports no feature
|
||||
created and no HUD-less / UI tag was sent (or "not excluded" when the driver did not answer), no FSR
|
||||
frame-generation dispatch reached a hooked module, the frame-generation runtime modules the census names
|
||||
or that none is loaded, and the SDK strings the executable carries — never a vendor named as measured, and
|
||||
it says a frame generator compiled into the executable would read the same. The capture host scans the
|
||||
executable FILE on disk once after the session (`ExecutableMarkerScan`: `ffxFsr3`, `ffxFrameInterpolation`,
|
||||
`xefgSwapChain` and the non-FG strings for the reader; chunked with overlap, hits capped) and prints
|
||||
`executable markers:`; when a frame-generation-capable string is in the file and no module was loaded, the
|
||||
Presented qualifier reads *MAY include generated frames* instead of *cannot* — the sentence that was wrong
|
||||
in the dangerous direction on Rune Factory and Wukong. A marker is never identity. Intel's licence was
|
||||
re-checked the same day and is unchanged; XeSS-FG runs on non-Intel GPUs, so an XeFG session measures this.
|
||||
|
||||
- **The super-resolution identity from the NVIDIA driver, where no hook can see it — the driver-reported
|
||||
rung (owner decision 2026-09-06).** Three NGX-direct titles printed `upscaler: N/A` on every capture
|
||||
while the driver's per-process NGX word (`NvAPI_NGX_GetNGXOverrideState`, R570+, MIT NVAPI) reads
|
||||
`CREATED | EVALUATE` for them — measured 2026-09-06 without an NVIDIA-app override. The capture host now
|
||||
spawns `fl-probe-nvapi --ngx-state <pid>` beside every module snapshot (the probe gained one machine line,
|
||||
`NGXSTATE status=… sr=0x… …`, and is staged beside the host), merges the readings (`NgxDriverState`: the
|
||||
last answered word is the state, a change between readings is printed), prints `NVIDIA driver NGX state:`
|
||||
in the runtime block, and the `upscaler:` line reads `Dlss (driver-reported: … not counted by this hook)`
|
||||
when no hook named one. Identity only, each limit measured: no quality or preset (override fields), no
|
||||
ratio (`scalingRatio` is 0 even under an override), no frame-generation multiplier (`FG_MODE` /
|
||||
`FG_MULTI_FRAME` stay clear at ×4). **The FG word follows DLSS-G too, corrected on the first run's own
|
||||
readings:** `CREATED | EVALUATE` on every ×4 session, changing between readings as the feature came up, so
|
||||
it is printed beside `frame generation:` as agreement or a printed disagreement, and promoted to
|
||||
`DlssG (driver-reported …)` only where the count is active and no tag named the technology — the count is
|
||||
never the driver's. Owner's run (§H5 rows N1–N4): the negative held (`CREATED` clear with upscaling off),
|
||||
four NGX-direct titles now print `Dlss (driver-reported …)`, two hooked titles print agreement, and an
|
||||
FSR + DLSS-G session read `SR 0x205` (created, not evaluated) and correctly claimed nothing. Beside a hook's `Dlss` the driver's word prints as agreement or as a
|
||||
disagreement printed rather than resolved; beside an `N/A` with the bit clear it prints the driver's
|
||||
negative. `20_OPEN_QUESTIONS` §H5 pre-commits rows N1–N4, and N3 — DLSS switched off — withdraws the rung
|
||||
if the bit stays set. `03_METRICS` §Upscaling, `05_DETECTION`, `18_GPU_VENDOR_APIS` carry it.
|
||||
|
||||
### Changed
|
||||
|
||||
- **P3 PR-0 — the P2 sweep: what PR-G's closing sweep left stale, corrected in place (2026-09-13).**
|
||||
Docs and tools only, no `src/`. `tools/coverage-gate.ps1` said Domain and Application were "empty
|
||||
today" and the metric calculators "do not exist yet" four days after both had armed it; `13_CI_CD`
|
||||
counted nine `Category=Integration` cases (20 across six classes) and claimed the signer probe ran
|
||||
after the gate with `if: always()` "a one-line change nobody has made" — the step has carried it since
|
||||
#137, before the failure the bullet describes, so *why* the probe was not read on 2026-09-10 is now
|
||||
recorded as unmeasured rather than as a workflow defect; `09_I18N` said `ConsentProvenance` had two
|
||||
members (three since PR-F); `17_HOOK_ENGINE` cited `20_OPEN_QUESTIONS` §H9, answered and removed in the
|
||||
P0 spike; `ci.yml`'s census comment still promised "the next PR wires the script" after the census had
|
||||
read `vulkaninfo.exe` absent twice. HANDOFF: P2's START HERE struck, **§P3 is the head** with the
|
||||
slice table (0, 1, 1b, 2, 2b, 3–9) and decisions D11–D17; D1/D5/D6/D10 labelled where they were
|
||||
cited by number and defined unlabelled, and D2/D3 recorded as never assigned. `15_ROADMAP` §P3 takes
|
||||
the pipe, i18n, the Legal Gate, Settings, Logs and the tray from §P4 (owner, 2026-09-13). §G's
|
||||
threading-model row struck with its pointer; the settings-registry and pipe-security rows carry the
|
||||
decisions that close them. What P2 still owes is unchanged and is measurement: `spike-notes` §14's
|
||||
four slots, all empty, all the owner's.
|
||||
|
||||
- **The FG `N/A` and the upscaler `N/A` carry their witnesses.** Hell Is Us at XeSS + XeSS-FG (2026-09-06):
|
||||
no Streamline token on that plugin at XeSS, so nothing counted, and the report printed a bare *N/A (a hook
|
||||
ran …)* while the driver's FG word, the tags, the ffx census, the module census and the executable's own
|
||||
strings all had something to say. The N/A now prints the same exclusion clauses as rung 3 (*what this
|
||||
session can still say: not DLSS-G (…); …; the frame-generation runtime(s) loaded: …; the executable itself
|
||||
carries xefgSwapChain*), and the upscaler N/A says *libxess.dll is loaded, and XeSS cannot be hooked or
|
||||
declared under Intel's licence … by policy, not by ignorance* — HANDOFF 7c item 4's string change. Rune
|
||||
Factory at FSR + FSR FG printed the pre-committed 7b line verbatim on the same run.
|
||||
|
||||
- **A counted session whose factor was refused no longer reads "no evaluation was observed".** DL:TB at FSR
|
||||
upscaling + DLSS Frame Generation (2026-09-06): 4,415 tokens, 8,174 DXGI-counted presents, `DlssG` from
|
||||
the tags, factor refused because bucket 8 of 8 read 1.96 against 2.85 — and the Presented qualifier said
|
||||
a runtime was loaded and nothing was seen. It now says frame generation was counted and its factor
|
||||
refused, that DXGI counted presents this hook never saw so the Displayed rate is above the printed
|
||||
number, and that the number is neither Native nor Displayed.
|
||||
|
||||
- **The withheld `none` is narrowed to sessions where DXGI's counter was not read (§H5 Leg 0 landed).**
|
||||
The owner's morning run on the DXGI-counted build printed the rule-6 trio on Dying Light: The Beast
|
||||
(`Native 70.52 -> Displayed 282.08 (x4 FG)`, 12,387 presents DXGI-counted, `DlssG`) and then ran the
|
||||
title twice with frame generation OFF: census unchanged (`sl.dlss_g.dll` is a startup-time load),
|
||||
presents = tokens, `unseen=0` over thousands of samples, and the report withheld `none` exactly as the
|
||||
gate's cost paragraph pre-committed. The counter is the discriminator the gate lacked — on that shape
|
||||
the pacer's presents are DXGI presents on the hooked chain — so a counted `none` beside a READ counter
|
||||
with zero unseen now prints as `none`, with *"DXGI's own present counter agrees: 0 unseen over N hooked
|
||||
present(s)"* on the line; it is withheld only when the counter was not read, with the reason saying so.
|
||||
A writer state that counted unseen presents the records do not carry is refused as a contradiction.
|
||||
On every other title the counter is printed beside `none` as a second witness. CLAUDE.md rule 6 carries
|
||||
the amendment; three cases changed sides and four are new.
|
||||
|
||||
### Added
|
||||
|
||||
- **Displayed FPS counted by DXGI where the hook cannot count it — the 2.8.0 pacer's presents.** The
|
||||
owner's run on the DXGI counter landed `20_OPEN_QUESTIONS` §H5 row P1-DXGI twice: Dying Light: The
|
||||
Beast at DLSS Frame Generation ×4 on Streamline 2.8.0 reads 2.90 and 2.95 presents per hooked present
|
||||
that DXGI counted on the same chain and the inline patches never saw, while Streamline 2.7.3 (Hell Is
|
||||
Us, ×3.86) and 2.10.3 (the Onimusha: Way of the Sword demo, ×3.67) read 0.00 — their generated frames
|
||||
come through the patched bodies. So the record now carries `dxgiUnseen` (@52, from the reserved word,
|
||||
under `FL_MEASURED_DXGI_PRESENTS`, no layout bump; mirror and `fl-layout-dump` follow), and the
|
||||
consumer's window counts `Displayed = hooked + Σ dxgiUnseen` — in the rule-6 trio, in `presents/batch`
|
||||
and in the uniformity buckets, never in a frame-time distribution — printing *"Displayed is
|
||||
DXGI-COUNTED"* on its own line whenever the sum is above zero, because that number is a count DXGI
|
||||
made rather than this hook. `none` withdraws on that title by count; a saturated byte is refused like
|
||||
a saturated `fgEvaluations`; a byte under a clear bit is an honesty violation. A present the hook SAW and
|
||||
declined — a paused session — is not an unseen present: every declined present bumps an epoch that
|
||||
invalidates the chain's last reading, which the paused-session integration case caught (the first record
|
||||
after a resume claimed the whole pause, 0x55, before the guard). On every other title
|
||||
the window is byte-identical (five cases pin it; the injected `[fg]` case checks the byte is claimed
|
||||
and zero on the harness). `03_METRICS` §Displayed may be DXGI-COUNTED carries the rule.
|
||||
|
||||
- **DXGI's own present counter against the hook's, in the writer state and the report.** On the one shape
|
||||
where `none` is withheld (Streamline ≥ 2.8 with `sl.dlss_g.dll` loaded, Dying Light: The Beast), the
|
||||
open question was whether the closed pacer's generated presents reach DXGI through a body the inline
|
||||
patches miss or are displayed below DXGI. The Overlay now reads `IDXGISwapChain::GetLastPresentCount`
|
||||
on every hooked present of the chain it just saw (rule 4: the same object `GetDesc` is already read
|
||||
from) and publishes `dxgiPresentSamples` and `dxgiPresentsUnseen` (`FlWriterState @48/@52`, from
|
||||
`reserved[]`, no layout bump; mirror, `fl-layout-dump` and the offset asserts updated). The report prints
|
||||
`DXGI present counter: unseen=M over samples=N (r unseen per hooked present)` with the reading, and the
|
||||
withheld qualifier says which side of DXGI the generated presents fall on. `20_OPEN_QUESTIONS` §H5
|
||||
carries the rows written before the run: r ≈ 3 at ×4 means the generated presents ARE DXGI presents
|
||||
and the next PR labels a DXGI-counted Displayed rate; r ≈ 0 means below DXGI and only the kernel and
|
||||
vendor reads remain. The harness's presents are the negative control (`fl_guard` `[fg]`: zero unseen);
|
||||
the positive cannot be fixtured. `hook-harness --probe-frames` now prints the call's cost.
|
||||
|
||||
- **A stall diagnostic in the report, placed against FrameLedger's own touches on the target.** The
|
||||
owner saw Cyberpunk 2077 fall to 1 FPS for about a second under capture (2026-09-05) and the report
|
||||
could say nothing about whose it was. The capture host now records the QPC moment of every guard scan
|
||||
and module snapshot (`CaptureResult.TouchQpc`, the records' own clock), and `StallReport` prints the
|
||||
three longest present-to-present intervals with their session time and the nearest host touch: a
|
||||
touch inside or within 1 s names FrameLedger a SUSPECT and asks for a longer run on the 30 s cadence;
|
||||
a far one says *not ours*. It counts intervals at or over 100 ms and calls itself a diagnostic — it is
|
||||
not `03_METRICS`' stutter, which P2's calculators own. Four cases pin the placement.
|
||||
|
||||
- **DLSS Frame Generation is NAMED, from the tags the title already sends.** On every NVIDIA title measured
|
||||
the count was right and the technology unnamed — `Active (technology not identified)` on Cyberpunk at
|
||||
MFG ×3 and on the three UE titles at ×4 — because `kFeatureDLSS_G` is never evaluated through the export
|
||||
the identity hook owns. Streamline's DLSS-G programming guide §5.0 requires a title running frame
|
||||
generation to tag the HUD-less colour and UI buffers every frame through `slSetTag` /
|
||||
`slSetTagForFrame` / `slEvaluateFeature`'s inputs — the three tag routes this build already hooks and
|
||||
read one tag type from. The detours now record every tag's TYPE (rule 4: the same argument), a
|
||||
HUD-less or UI tag drained by a present marks it `FL_FG_DLSS_G`, and `FlWriterState.slTagCensus` (took
|
||||
`reserved[0]`, no layout bump) says which types arrived on which route for the session; the report
|
||||
prints it as `Streamline tag census: global=[…] frame=[…] local=[…]`. **Identity only:** the consumer's
|
||||
rule is the count decides `none`, identity decides the name — an active count beside the mark prints
|
||||
`frame generation: DlssG`; a counted 1.0 beside it prints `none` with the inputs noted; the withheld
|
||||
shape (§H5) keeps its N/A and says the title is feeding frame generation. Two injected cases send the
|
||||
DLSS-G list through each global export with no `kFeatureDLSS_G` evaluation and assert the mark on every
|
||||
record and the census on the right route; the existing tag cases assert its absence. `slDLSSGGetState`
|
||||
— the API the guide names for the presented count — is refused and the reason recorded in `03_METRICS`:
|
||||
the call resets the plugin's counter a title may read for its own FPS display, and the header marks it
|
||||
not thread safe.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The tag route is measured on real titles** (docs): the owner's evening run on #121 read `frame generation:
|
||||
DlssG` on Hell Is Us, Expedition 33, Wukong, Rune Factory and Cyberpunk — every Streamline title tags the
|
||||
DLSS-G inputs through a route this build hooks — and Dying Light: The Beast's census shows the title tags its
|
||||
scaling input through `slSetTagForFrame` with no size, which closes HANDOFF 7a's last question without a
|
||||
layout bump. `spike-notes` §9 carries the table; §H5 records the pre-commitment as landed.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`render -> output` prints under frame generation.** `UpscaleExtent` keyed its window on the
|
||||
params bit, which the writer publishes only on the present that drained a dispatch or tag — one
|
||||
in N under frame generation — so `ClaimedSuffixStart`'s clean-suffix rule found no window and every
|
||||
FG-on capture since 2026-08-16 read `N/A` two lines under its own raw `render WxH` block
|
||||
(Cyberpunk at FSR 3 + FG, 2026-09-05, was the one that made it visible; the earlier "not computed
|
||||
yet" wording had hidden it). The window is now the identity suffix, which is per-record once the
|
||||
family is live, and every record inside it carrying both sizes counts. Two cases pin the FG shape
|
||||
and the refused intermittent-identity shape; the Cyberpunk FSR 3 consumer case now asserts the line.
|
||||
|
||||
### Added
|
||||
|
||||
- **`fl-probe-nvapi --ngx-state <pid>`: what the NVIDIA driver says about one process's DLSS
|
||||
features.** The owner's eleven-capture run on 2026-09-05 (`spike-notes` §9) left one NVIDIA gap in
|
||||
one sentence — the count is right on every title and the identity is what this build cannot say:
|
||||
DLSS on the four NGX-direct UE titles, DLSS-G everywhere, and the hidden presents on Streamline
|
||||
2.8. The NGX SDK is licence-blocked; `NvAPI_NGX_GetNGXOverrideState` (NVAPI, MIT, vendored, R570+)
|
||||
takes a process id and returns the driver's own feedback bits for SR / RR / FG plus the scaling
|
||||
ratio, quality mode and frame-generation count, out of process. The probe prints the raw words and
|
||||
every decoded bit so the owner's run against a running title measures whether the bits are
|
||||
populated without an NVIDIA-app override, before any report line is built on it. §H5 carries the
|
||||
decision that answer opens (a *driver-reported* rung in `03_METRICS`, the owner's call).
|
||||
|
||||
- **The FSR 3.0 host route: a fifth AMD target, `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale`.**
|
||||
Cyberpunk 2077 at FSR 3 upscales through the FSR 3.0 **host** DLL's named export while its frame
|
||||
generation goes through the 1.1.x monolith's `ffxDispatch`, so the leaf-only build printed
|
||||
`upscaler: N/A` beside `FsrFg` (§H11, 2026-09-04). The host is hooked at its own export with its own
|
||||
trampoline and latch, keyed by module in the installer, under the same family and publish point as
|
||||
the four ffx-api rows (`PublishFfxFamilyIfWhole` waits for a loaded host as it waits for a loaded
|
||||
leaf); its UPSCALE feeds the same drain word — identity `FSR3` as a fact, `renderSize` as the
|
||||
extent, the count when neither Streamline nor a PREPARE has spoken. Rule 4: `renderSize` of the
|
||||
descriptor the title passed and nothing else; the offset is pinned to a literal (1256).
|
||||
`ffxFsr3DispatchFrameGeneration` is deliberately not a row, with the reversal condition
|
||||
pre-committed in §H11. **The headers are vendored from tag `fsr3-v3.0.4`, not the `v1.1.4` three
|
||||
documents named**: the shipped module's twelve `ffxFsr3*` exports match 3.0.4 exactly, 1.1.4
|
||||
declares fifteen and appends fields after `renderSize`, and at 3.0.4 `ffx_types.h` reaches no
|
||||
`<mutex>` at all (ten files, no `ffx_message.h`; `src/native/third_party/fidelityfx-fsr3/`, root
|
||||
`LICENSE.txt` MIT verbatim, `license-check.ps1` §2e per file, blob shas checked against upstream).
|
||||
The two FidelityFX trees share one struct name, so the 3.0.4 header is included inside a
|
||||
namespace. Fixtures: the `ffx_fsr3_x64.dll` stub (Pass C's second positive control), harness
|
||||
topologies `fsr3host` / `fsr3host+mono`, an `[ffx]` injected case at K = 1 (the row's double-count
|
||||
control) and K ∈ {1, 4} beside the monolith, and a consumer case for Cyberpunk's shape. Owed: the
|
||||
owner's acceptance run, rows B1–B4 in §H11.
|
||||
- **The report names the loaded vendor runtimes with their FILE versions, and a counted `none` is
|
||||
WITHHELD on the one shape measured to be wrong.** Dying Light: The Beast (Streamline 2.8.0) read
|
||||
`presents = tokens` five times with DLSS Frame Generation ON, and the owner's reading on 2026-09-05
|
||||
settled which way to read it: the title runs at DLSS ×4, the frames this hook records are the
|
||||
native ones, and the generated presents never reach the `Present` bodies the Overlay patches
|
||||
(`20_OPEN_QUESTIONS` §H5 case 3, realised). The census could not have said so — it records module
|
||||
NAMES, and Cyberpunk 2077 on 2.7.1 reads ×3.99 through the same hook — so the capture host now takes
|
||||
an out-of-process module snapshot beside every guard scan (`Process.Modules` + the file's version
|
||||
resource, the same documented module list the guard already enumerates; no game memory, no layout
|
||||
change, nothing on the present path) and prints one `module:` line per census-named module with
|
||||
version and path. `MeasuredFacts` withholds `none` when `sl.dlss_g.dll` — the Streamline plugin that
|
||||
would be doing the presenting, NOT `nvngx_dlssg.dll`, which every validated `none` also has loaded —
|
||||
is in the census beside an interposer at or above 2.8.0 (or one whose version could not be read), and
|
||||
the report falls through to `Presented FPS` with a qualifier that says the number counts APPLICATION
|
||||
frames and that the Displayed rate is unknown. Every validated `none` (Cyberpunk off / ×3 / ×4,
|
||||
Expedition 33 and Lies of P with frame generation off) is byte-identical, and eight cases pin that.
|
||||
The gate is interim: §H5 pre-commits the owner's session (DL:TB FG off / FG ×4, Cyberpunk MFG ×4,
|
||||
PresentMon elevated beside each) and the row on which it is withdrawn.
|
||||
|
||||
- **A whole-resource tag now yields the size the tagged `sl::Resource` declares.** Streamline
|
||||
documents a zero `extent` as "use the entire resource"; a title tagging that way stated the
|
||||
render size nowhere the Overlay read, and Dying Light: The Beast (SL 2.8.0) still published no
|
||||
extent on the `slSetTagForFrame` build with both tag rows live. `TagSize` in `fl_sl_inputs.h`
|
||||
reads the extent first and, when it is zero, the Resource's own `width/height` — GUID-checked,
|
||||
from the argument the hooked API received, on the local walk and both global-tag detours alike,
|
||||
so the three routes cannot disagree about what a tag says. A Resource declaring no size is
|
||||
still the honest unknown. Unit cases cover the shape, precedence of a non-zero extent over the
|
||||
Resource, a Resource that fails the GUID check and a half-declared size; the harness tags in
|
||||
that shape under `--sl-tag-whole-resource` and an injected case asserts the exact size arrives
|
||||
on every record through the 2.8 export.
|
||||
|
||||
@@ -0,0 +1,958 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66): part 3 of 5 of the ledger kept before the first tag, newest first. CHANGELOG.md lists every part. -->
|
||||
|
||||
## Ledger before 0.1.0-beta.1 (continued, part 3 of 5)
|
||||
|
||||
### Changed
|
||||
|
||||
- **7a on Dying Light: The Beast closes as measured `N/A`** (docs): the 00:53 capture on the
|
||||
whole-resource build still carried no render size on either global-tag route, so the quality
|
||||
byte and the render size are `N/A` on this title, honestly, and the derived-label decision
|
||||
applies to the titles that print the line. The DLSS-FG-on `presents = tokens` result is now
|
||||
five for five; by owner decision it is handled in its own session and PR (`HANDOFF` 7a, §H5).
|
||||
- **`20_OPEN_QUESTIONS` §H5 has a candidate title for case 3.** Dying Light: The Beast at DLSS
|
||||
with DLSS Frame Generation on read `presents = tokens` on four captures (the same title with
|
||||
FSR FG read ×2; Cyberpunk on Streamline 2.7.1 read ×3.99), so the report printed `frame
|
||||
generation: none` on a generating title. The two readings the record cannot separate and the
|
||||
discriminator — the owner's counter — are pre-committed there.
|
||||
|
||||
- **A row for `sl.interposer.dll!slSetTagForFrame`, Streamline 2.8's frame-based tag entry
|
||||
point.** Dying Light: The Beast ships Streamline 2.8.0, which deprecates `slSetTag` in favour of
|
||||
`slSetTagForFrame` (the frame token first, then the same tag list); the title published `Dlss`
|
||||
identity on every batch across three captures and the params bit on none, because the only
|
||||
params row hooked the deprecated export. The new detour hands the list to the same tag walk, has
|
||||
its own trampoline, and is selected by SYMBOL
|
||||
through a constant the inventory header binds to its row with a `static_assert` — Pass B forbids
|
||||
the literal anywhere else. **The params family is published when whole**, once every tag export
|
||||
the loaded interposer has is patched — a 2.7 interposer is whole with `slSetTag` alone, a 2.8 one
|
||||
needs both — because the first cut published it on the first row and the frame-based fixture
|
||||
measured 38 of 41 records claiming params, the ffx leaves' install-window defect from #110
|
||||
again. The stub exports it, the harness tags through it under `--sl-tag-for-frame`, and a Catch2
|
||||
case asserts the exact tagged extent arrives on every record with `slSetTag` never called.
|
||||
- **`tools/vendor-exports.ps1` unions exports across every copy of a module name** and lists every
|
||||
distinct version seen, instead of recording the first copy the walk reached. With `sl.interposer.dll`
|
||||
installed as 2.7.1 and 2.8.0 side by side, whether the oracle contained `slSetTagForFrame`
|
||||
depended on directory order; `docs/vendor-exports.json` is regenerated (ten interposer copies,
|
||||
eight versions from 1.5.6 to 2.10.3).
|
||||
|
||||
- **The report's `render -> output` line is computed, not "not computed yet".** Every real-title
|
||||
run since 2026-08-15 printed the raw sizes two lines above an N/A. `UpscaleExtent` takes the
|
||||
MODAL (render, output) tuple over the records that claim both `FL_MEASURED_UPSCALER_PARAMS` and
|
||||
`FL_MEASURED_OUTPUT_RES`, and the line prints the two measured sizes, `03_METRICS` §Upscaling's
|
||||
`sqrt((outW×outH)/(renW×renH))`, the reciprocal as a render-scale percentage, the record counts,
|
||||
and a **SETTINGS MOVED** flag when the window held more than one tuple — modal rather than mean,
|
||||
because averaging across a settings change is the classic way a benchmark number stops meaning
|
||||
anything. Cyberpunk's 1485×835 at 2560×1440 reads `1.72x (58% render scale)`. **No preset name is
|
||||
derived from it**: whether a label such as "≈ Balanced" may appear beside a measured field is
|
||||
HANDOFF item 7a's owner decision, and the quality byte stays what the writer measured.
|
||||
|
||||
- **The SDK 2.x loader is the fourth AMD row, because three loader-shipping titles read silent
|
||||
behind the leaf-only build.** The owner's run on #110 (thirteen captures, nine titles, one launch
|
||||
each) landed rows A1–A3 exactly as pre-committed — Lies of P `Fsr3` / `FsrFg` / `118.98 → 238.02
|
||||
(×2)` with the two per-frame counts agreeing at 1.00, `none` by count with frame generation off;
|
||||
Hell Is Us `FSR (3.1 or 4 …)` / `FsrFg` / ×2 — and produced a row the table lacked: Dying Light:
|
||||
The Beast at FSR + FSR frame generation, KCD2 at FSR and Black Myth: Wukong at FSR each dispatched
|
||||
**zero** times at any leaf export while the leaves sat in the census. The game calls the loader's
|
||||
export, and the signed loader reaches its providers through an object rather than the leaves'
|
||||
`ffxDispatch`, so "five identical export tables leave it no other route" was wrong about the
|
||||
loader. `amd_fidelityfx_loader_dx12.dll` is now an inventory row alongside the three leaves, the
|
||||
`static_assert` that refused it asserts the opposite with the measurement in its message, the
|
||||
loader stub forwards through the leaves' FrameLedger-named *direct* entry (never their export) to
|
||||
model what was measured, `--probe-ffx-resolve` asserts the forward touched no leaf export, and a
|
||||
third harness topology (`--ffx-topology ue`: the two effect DLLs called directly, no loader) keeps
|
||||
the leaf detours exercised now that the loader case never reaches them. The K = 1 control with
|
||||
all four modules hooked, and the consumer's `frames/upscale-drained`, are what would read 2× for a
|
||||
loader that re-entered an export. Also from the run: Expedition 33 at FSR upscaling under DLSS
|
||||
frame generation ×3 printed `×2.97`, *technology not identified*, from the UPSCALE count; Cyberpunk
|
||||
at FSR 3 generates through the 1.1.x monolith (`FsrFg`) while upscaling through the deferred FSR
|
||||
3.0 route; and **Rune Factory: Guardians of Azuma is HANDOFF 7b's statically linked title** — the
|
||||
monolith ships beside it and is never loaded, yet the Streamline token count still read
|
||||
`59.99 → 119.95 (×2 FG)`, so the ceiling for such a title is the trio with the vendor missing, not
|
||||
Presented FPS alone. **Row R6 ran the same night on this build:** Dying Light: The Beast at FSR +
|
||||
FSR FG printed `FSR (3.1 or 4 …)` / `FsrFg` / `70.49 → 140.9 (×2 FG)` with `frames/upscale-drained`
|
||||
1.01, and KCD2 at FSR the identity with `none` at 1.00 — the loader row carries both, once, which
|
||||
is the K = 1 control confirmed on a real title. Wukong at FSR with FG off read silent at the
|
||||
monolith and the loader alike with the monolith loaded, and offers no FSR frame generation at
|
||||
all: FSR upscaling compiled into its UE plugin (Rune Factory's shape), the monolith shipped and
|
||||
loaded for nothing this hook sees — the second static title, and nothing more is owed on AMD
|
||||
identity beyond the FSR 3.0 host route.
|
||||
`20_OPEN_QUESTIONS` §H11 carries the run tables; `HANDOFF` 7b/7c and `spike-notes` §9 carry the
|
||||
corrections.
|
||||
|
||||
- **AMD identity is measured through the ffx-api leaves, and the first non-NVIDIA vendor
|
||||
reaches the record.** HANDOFF item 7c. Lies of P at FSR 3.1 + frame generation printed
|
||||
`upscaler: N/A … frame generation: N/A` plus a census WARNING because the three AMD modules
|
||||
export the same five generic names and the identity lives in the descriptor the game passes
|
||||
— which needs the vendor's headers to decode, and `20_OPEN_QUESTIONS` §H11 forbids decoding
|
||||
it from observation. Five headers are vendored from FidelityFX-SDK **tag `v2.3.0`**,
|
||||
types-only under upstream's `Kits/FidelityFX/` layout, with upstream's `docs/license.md`
|
||||
verbatim: a binary-only default licence whose **MIT exception list names every one of the
|
||||
tree's 845 files** (the signed DLLs included), the five among them, and each header carries
|
||||
the grant inline; `license-check.ps1` §2d asserts both per vendored file. `v2.3.0` rather
|
||||
than the `v1.1.4` `18_GPU_VENDOR_APIS` first named, because its own reversal condition
|
||||
fired: installed titles already ship SDK 2.x effect DLLs (Hell Is Us 4.0.x, Expedition 33
|
||||
and Dying Light: The Beast 4.0.2 + 3.1.5) and the sample dispatches `PrepareV2`, which
|
||||
`v1.1.4` does not declare; every value and layout read is identical in both tags.
|
||||
**Three inventory rows, one compound family, one observer, three trampolines, and the rows
|
||||
are the LEAVES** — `amd_fidelityfx_dx12.dll` (the SDK 1.1.x monolith),
|
||||
`amd_fidelityfx_upscaler_dx12.dll`, `amd_fidelityfx_framegeneration_dx12.dll` — **never the
|
||||
SDK 2.x loader**, which forwards to the effect DLLs through their own exports (the only
|
||||
route five identical export tables allow) so hooking it too would count every dispatch
|
||||
twice, straight into `fg_factor`; a UE5 title ships the two leaves with no loader at all.
|
||||
The detour reads the descriptor's head type and, once matched, `renderSize` (UPSCALE,
|
||||
PREPARE) and `frameID` (PREPARE) — rule 4's class of read — and publishes: identity
|
||||
(`FSR3` from the monolith; the new **`FL_UPSCALER_FSR_UNVERSIONED`** from the 2.x upscaler
|
||||
DLL, which hosts FSR 3.1 and FSR 4 behind one dispatch type — an enumerator, no layout
|
||||
change), `renderW/H` exact with quality and sharpness `0xFF` (the ffx-api dispatch carries
|
||||
neither, so that is the true value), `fgMode = FSR_FG` on a present that drained a
|
||||
generated batch, and `fgEvaluations` from PREPARE's `frameID` counted on a **new** index
|
||||
only — this vendor's `slGetNewFrameToken` — falling back to the UPSCALE count on a title that
|
||||
never prepares. Streamline keeps precedence once it has ever issued a token, so every title
|
||||
validated on §S31 is byte-identical to before. Fixtures: three leaf stubs, a **forwarding
|
||||
loader decoy**, `--probe-ffx-resolve` (ctest `fl_ffx_resolve`), and `--hold-presenting-ffx`
|
||||
driven at K = 1 / K = 4 on both topologies with the PREPARE issued twice per frame — the
|
||||
K = 1 control reads 2.0 for a writer that counts calls, or that hooks the loader.
|
||||
`hookinventory-check` Pass C now reads the Overlay's **export table** too: `ffx_api.h`
|
||||
declares its entry points `__declspec(dllexport)` unconditionally. Hook-path overhead: the
|
||||
present path gains two `exchange`, two loads and a branch; the detour is one 8-byte read, a
|
||||
switch and one RMW per dispatch (a CAS loop on PREPARE). Owner-only runs owed: Lies of P at
|
||||
FSR + FG and FSR alone, Hell Is Us at FSR, against the table pre-committed in §H11.
|
||||
|
||||
- **`none` is reachable by counting, §S31 is resolved, and P0's frame-generation blocker is
|
||||
gone.** The owner's second run on #105's monotone count landed on row **P1** of the table
|
||||
pre-committed in `20_OPEN_QUESTIONS` §S31: Cyberpunk 2077 off / ×3 / ×4 at `presents/tokens`
|
||||
**1.00 / 2.99 / 3.99**, Hell Is Us DLSS + FG ×4 at **4.00**, and `tokens/batch` **1.00** on
|
||||
every leg with batches — so a drained Streamline batch *is* an application frame on that
|
||||
title, answered by a second per-frame count rather than by any of the four oracles that fell.
|
||||
The pre-P1 refusal of ratios near 1 is replaced: a published factor ≤ 1.05
|
||||
(`FgWindow.NoneCeiling`) is rung 4's `none` — every present carried an application frame,
|
||||
measured — a factor ≥ 1.5 (`ActiveThreshold`) is active, and the band between is refused as a
|
||||
configuration no vendor ships. `fgMode` reads `None` / `Active (technology not identified)`
|
||||
from the count when the identity hook named nothing; the report gains its third shape, the
|
||||
bare `FPS: 84.02` with a `frame generation: none` line — no pair, no factor, no qualifier.
|
||||
`15_ROADMAP` item 7 ✅; §S24 counts nine. *Flower in Us* resolved to its browser process,
|
||||
injected, and captured three swapchains' worth of presents, so the Overlay loads inside NW.js.
|
||||
|
||||
- **The frame-token count keys on a NEW frame INDEX, and the Chromium resolver knows the shape
|
||||
with no GPU process.** Both from the run that followed #103 / #104 the same evening.
|
||||
Cyberpunk 2077 asks `slGetNewFrameToken` three to four-and-a-half times per application frame
|
||||
and receives a distinct object each time, so a pointer-keyed count read the request rate:
|
||||
`presents/tokens` 0.22 / 0.64 / 1.31 at off / ×2 / ×4 — `20_OPEN_QUESTIONS` §S31 row **P4**,
|
||||
the refinement it prescribed. The detour now reads the frame index — the title-supplied
|
||||
`frameIndex`, or the token's own accessor when none is given — and counts it **only when it is
|
||||
above every index seen so far**: "differs from the last index" would still count every switch
|
||||
between the two or three frames a title keeps in flight. The stub hands back distinct objects,
|
||||
and the harness asks three times per frame with the previous frame's index in the middle, so
|
||||
the K = 1 control is red for a pointer-keyed writer and for a last-index-keyed one. No factor
|
||||
had been published on any leg — the ≥ 1.5 gate held — and the four-leg run is owed again.
|
||||
*Flower in Us* still refused through #104's rule because **NW.js has no `--type=gpu-process`**:
|
||||
six processes, the GPU in-process in the untyped browser. Second rule: exactly one untyped
|
||||
candidate among typed siblings is the browser and the target; two untyped are two instances
|
||||
and refuse. The refusal line prints the tree.
|
||||
|
||||
- **Chromium-based titles resolve to their GPU process instead of refusing as ambiguous.**
|
||||
NW.js, Electron and RPG Maker MV/MZ run several processes from one image path, and *Flower in
|
||||
Us* refused as `TargetAmbiguous` on 2026-09-03. The presenting process is Chromium's GPU
|
||||
process — it owns no window, so no window-based pick is correct — and Chromium labels it with
|
||||
`--type=gpu-process` on its own command line. `TargetResolver` now reads each candidate's
|
||||
command line through `NtQueryInformationProcess(ProcessCommandLineInformation)` — served by
|
||||
the kernel with `PROCESS_QUERY_LIMITED_INFORMATION`, no `ReadProcessMemory`, no PEB walk, 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, none, or an unreadable
|
||||
sibling still refuse; §S27 is untouched (consent keyed on the path, every candidate is that
|
||||
path, the guard scans the pid chosen, no `--pid`). `TargetResolverTests` drives it against
|
||||
real processes: a uniquely-named copy of `cmd.exe` started three times, one with the flag.
|
||||
|
||||
- **The frame-generation producer, chosen with no oracle and built: `slGetNewFrameToken`.**
|
||||
HANDOFF item 3 had five candidate routes and four fallen oracles. The one taken needs neither:
|
||||
Streamline hands a title **one frame token per application frame** by contract and the title
|
||||
must ask for it, so a detour on `sl.interposer.dll!slGetNewFrameToken` — a third inventory row,
|
||||
module-scoped, lazily installed — counts distinct tokens between presents, and `fg_factor =
|
||||
presents / tokens`. No premise about Ray Reconstruction batches, and it installs on the titles
|
||||
where `slEvaluateFeature` is never called (three of five measured). `fgEvaluations` keeps its
|
||||
name and its `03_METRICS` definition ("application frames, counted at the source") and changes
|
||||
producer; `FL_HOOK_FG_EVALUATIONS` moves to the new row and the evaluate detour claims identity
|
||||
only, with the `static_assert` flipped to say so.
|
||||
|
||||
**The one premise it carries is gated, not assumed.** From inside the process, "no frames were
|
||||
generated" and "the DLSS-G plugin requested a token for every frame it generated" both read
|
||||
1.0. A ratio ≥ 1.5 cannot come from the second, so the trio is published from it now; a ratio
|
||||
near 1 is refused by name (`FgWindow.PublishableFactor`) until the owner's Cyberpunk off / ×2 /
|
||||
×4 and Hell Is Us ×4 run lands on row P1 of the table pre-committed in `20_OPEN_QUESTIONS`
|
||||
§S31. `none` on a Streamline title is the PR after that run.
|
||||
|
||||
Fixtures: the stub interposer hands out tokens from a pool of eight (a nullptr token would
|
||||
have made every call the same frame); `--hold-presenting-fg` issues one token and one
|
||||
evaluation per K presents, and `fl_guard`'s K = 1 / K = 4 pair now discriminates the token
|
||||
count from the present count. Report labels `evaluations=` → `tokens=`. Hook-path overhead:
|
||||
one atomic exchange and one conditional increment on a call the title makes once per frame;
|
||||
nothing on the present path changed.
|
||||
|
||||
- **Presented FPS, and a runtime census that says what the one number may and may not mean.**
|
||||
With this writer, `03_METRICS`' frame-generation ladder lands on rung 0 for *every* title — no
|
||||
non-Streamline title sets `FL_MEASURED_FG`, and `Σ fgEvaluations` is 0 on every Streamline title
|
||||
measured — so a 2D title with no upscaler and Black Myth: Wukong running DLSS-G through a path
|
||||
this writer does not hook printed the same report line. `08_UI` said *"FG not detected →
|
||||
`144 FPS`"* while `03_METRICS` rung 0 said `N/A`, not `none`; both were half right.
|
||||
|
||||
**The rule (owner decision 2026-09-03, CLAUDE.md rule 6 amended):** when frame generation is
|
||||
not measured, the one number that stands alone is **Presented FPS** — `presents / D`,
|
||||
numerically Displayed FPS, named so that "Native" and "Displayed" are only ever printed
|
||||
*together* — with a mandatory qualifier chosen by the **runtime census**.
|
||||
|
||||
**The census.** `FlWriterState.runtimeCensus` (`reserved[0]`, no layout bump: the build-id
|
||||
handshake refuses an older writer first) is taken on the Overlay's watchdog once a second —
|
||||
`GetModuleHandleExW(UNCHANGED_REFCOUNT)` per name in `FL_RUNTIME_CENSUS`, twenty measured
|
||||
module names in two families, OR-only, nothing on the present path, nothing patched. `Ran` is
|
||||
bit 0 so a writer that never took it publishes 0 and decodes as "nobody looked".
|
||||
`hookinventory-check` gains **Pass D**: every census name must be a module `vendor-exports.json`
|
||||
has actually seen, because a misspelt name reads as "not loaded", which reads as the 2D case.
|
||||
|
||||
**What it changes in the report.** Under Presented FPS, one of three lines: the census did
|
||||
not run; *no known frame-generation runtime was loaded, so this cannot include in-process
|
||||
generated frames (statically linked FSR3-FG and driver-level AFMF excepted)*; or **WARNING:
|
||||
a frame-generation runtime was loaded (`nvngx_dlssg.dll`) and no evaluation was observed —
|
||||
this MAY include generated frames**. The upscaler line stops saying *"our coverage is short,
|
||||
not the title's"* — false in the commonest case — and names the three causes it cannot tell
|
||||
apart: settings off, an unhooked path, an undecoded vendor.
|
||||
|
||||
**What it never does: produce `none`.** `FL_FG_NONE` / `FL_UPSCALER_NONE` mean a hook ran and
|
||||
saw the alternative. FSR is routinely linked statically, so a census-`none` on an FSR3-FG
|
||||
title would print presents as native — the exact number rule 6 forbids — with a confident
|
||||
label. The census narrows an N/A's reason and raises a warning; it does not close the question.
|
||||
|
||||
Fixtures: `fl_guard`'s present-only case asserts `runtimeCensus == FL_CENSUS_RAN` by equality,
|
||||
the Streamline-stub case asserts the interposer bit set and every FG bit clear;
|
||||
`amd_fidelityfx_dx12.dll` — the FSR 3.1 facade, which Lies of P ships ALONE while generating
|
||||
frames — is in the FG group, so its presence warns rather than reassures;
|
||||
`CensusReportTests` drives all three report shapes, the Witcher-3 shape (runtime loaded, no
|
||||
hook) and the inconsistent-writer shape. **Hook-path overhead: none** — the census runs only on
|
||||
the watchdog. **Run the same day on six titles** (`spike-notes` §9): both qualifiers seen on real
|
||||
games with the loader's own names; the census is a startup property on UE5 (identical word at
|
||||
off / FSR / DLSS + FG ×4); Hell Is Us is the third title where DLSS is on and `slEvaluateFeature`
|
||||
sees nothing; a Chromium-based title refuses as `TargetAmbiguous`, now a scope row.
|
||||
|
||||
- **The first telemetry source, and the measurement it exists for: §M5 is answered — GPU
|
||||
sensors work unelevated, without PawnIO, on NVIDIA.** `FrameLedger.Application.Telemetry`
|
||||
gains the port `18_GPU_VENDOR_APIS` specified (`IGpuTelemetrySource`, `GpuSample`,
|
||||
`GpuCapabilities`, `TelemetryLayer`); `FrameLedger.Infrastructure.Telemetry` gains
|
||||
`LhmTelemetrySource` (L2) over LibreHardwareMonitorLib 0.9.6 — GPU group only, its own
|
||||
poller thread, 1 Hz and never under 500 ms, *throws or hangs twice ⇒ disabled for the
|
||||
session*, capabilities value-derived and monotonic so a sensor that never reports is never
|
||||
a capability — behind an `ILhmComputer` seam so every branch of the fault policy runs on
|
||||
CI, which has no GPU. `SensorMap` carries the name heuristics and their two traps (NVIDIA's
|
||||
`GPU Memory` *load* is VRAM-in-use; `Control` is fan duty, not RPM).
|
||||
|
||||
**The instrument is `FrameLedger.CaptureHost probe-lhm [--seconds n]`** — the unshipped
|
||||
host's fifth verb, the only one besides `consent list` that names no game, because it opens
|
||||
a sensor library in its own process and nothing else. It prints the raw tree before the
|
||||
mapped sample before the verdict, and the verdict names a row of the decision table that
|
||||
`20_OPEN_QUESTIONS` §M5 carried **before** the run.
|
||||
|
||||
**Row R1, twice.** Unelevated: core and memory temperature, load, VRAM used, core and memory
|
||||
clock, package power, fan — eight fields, all five deciding ones among them. The elevated
|
||||
control, launched through UAC, returned the same eight. PawnIO was installed on the box and
|
||||
never opened: only LHM's CPU and board groups use it. So the sentence already in `README`,
|
||||
`legal/EULA.md` and `OperatorDisclosure` — *"whatever hardware telemetry this machine can
|
||||
provide"* — is true as written, and `README`'s row now names what that is on NVIDIA.
|
||||
`OperatorDisclosure.Version` stays /2. Hotspot temperature is absent on this driver / GPU /
|
||||
library and is recorded as N/A, not as a defect. Numbers in `spike-notes` §10; the L2 NVIDIA
|
||||
column of the capability matrix is filled; AMD and Intel are exactly as untested as before.
|
||||
|
||||
**One defect the raw tree caught before the verdict did:** the first `SensorMap` mapped
|
||||
`D3D Shared Memory Used` — system RAM — to adapter VRAM by a fragment rule.
|
||||
`SharedMemoryIsNotVram` pins the fix. Printing the evidence ahead of the interpretation is
|
||||
the whole reason the probe is shaped the way it is.
|
||||
|
||||
Closes the `HANDOFF` loose end that `LibreHardwareMonitorLib` shipped into the Agent's
|
||||
output under an MPL-2.0 §3.1 obligation while used by zero lines.
|
||||
|
||||
### Changed
|
||||
|
||||
- **The consent texts now say what DECLINING costs, and the anti-nudge rule is normative.**
|
||||
`README`'s safety row, `legal/DISCLAIMER.md`, `legal/EULA.md` and `19_SAFETY` §User-facing consent
|
||||
all called a no-injection mode *"the default"*. That mode does not exist. The consent disclosure
|
||||
in `OperatorDisclosure` said it too, and added *"Nothing here is required to measure frame
|
||||
times"* — **the worst sentence in the tree**, because it told someone about to type
|
||||
`I ACCEPT THE INJECTION RISK` that the risk was optional when hooking is now the only
|
||||
frame-time path.
|
||||
|
||||
**Removing the fallback makes declining more costly, so the wording gets more careful rather
|
||||
than more persuasive.** §19_SAFETY gains a normative rule: both options are enumerated at the
|
||||
same grain, neither is recommended, *"limited"* / *"reduced"* / *"degraded"* are not acceptable
|
||||
descriptions of Tier 2, no sentence describes what the user **loses**, and Tier 2 is never
|
||||
described as temporary — a user deciding today decides against what exists today.
|
||||
|
||||
**The disclosure is also REORDERED.** The Tier-2 sentence used to be the last thing before the
|
||||
prompt, so whatever it said read as the set-up for accepting. Anti-cheat risk and terms of
|
||||
service now sit there instead.
|
||||
|
||||
**`OperatorDisclosure.Version` bumps /1 → /2**, because /1 carried two sentences that were false
|
||||
rather than differently phrased. Traced while doing it: **nothing re-prompts on a version
|
||||
mismatch.** The field is written, merged forward, cleared on revoke and read by exactly one
|
||||
non-test caller — the `consent list` status line. `HookRequest.FromConsent` never sees it, so a
|
||||
/1 record still yields consent. That limit is now written into the type rather than assumed.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A candidate with no main module yet is counted as unreadable, not dropped as absent.** `TargetResolverTests.OneInstanceResolves` went red on the hosted runner twice in one hour on 2026-09-04 with `TargetNotRunning` about a process the test had just shown was enumerable: a freshly started process can be in the snapshot before its image is mapped, `Process.MainModule` is then null, and the resolver skipped it without counting it — narrowing the set exactly the way its own comment says "could not look" must not. It is now counted like a process we lack the rights to read (so the answer is `TargetAmbiguous`, never a false `TargetNotRunning`), and the test's "visible" wait means readable, not merely enumerated.
|
||||
|
||||
- **Two review checklists were boxes that could not fail**, in `19_SAFETY` §Review checklist and in
|
||||
the pull-request template: *"Is there a Tier-2 degradation path if the hook is unavailable?"*
|
||||
Under a two-rung ladder the answer is always yes. Replaced with something falsifiable — does the
|
||||
session record `N/A` rather than a fabricated value, **and record why**.
|
||||
|
||||
- **`CommandLineSurfaceTests` could not fail for the thing that changed.** It asserted
|
||||
`Contain("Tier-2")` against the disclosure while claiming to guard `19_SAFETY`'s four statements
|
||||
— so any rewrite keeping that literal token would have passed while the claim behind it changed
|
||||
completely. It now pins the substance (`N/A`, and the absence of both removed false sentences),
|
||||
and the new assertion was **canaried**: restoring one removed sentence turns it red.
|
||||
|
||||
- **The capture ladder collapses to two rungs, and Tier 2 is not a measurement.** Owner decision
|
||||
2026-08-28, and it is the honest shape once PresentMon was dropped: there is no no-injection
|
||||
measurement mode, so nothing holds a middle rung. What was Tier 3 is now Tier 2 — **session
|
||||
duration, whatever hardware telemetry the machine can provide, and the REASON nothing was
|
||||
measured**. Every measured field reads `N/A` (FR-4.9), and the reason is the payload rather than
|
||||
a consolation attached to it.
|
||||
|
||||
**Frame times, FPS and the lows are now Tier-1-only**, which is a real reduction in what this
|
||||
product promises: `README` previously offered them without injection.
|
||||
|
||||
**No capture tier needs an elevated Agent any more.** The requirement came from ETW trace
|
||||
sessions and there is no ETW rung. That closes §Scope's "Tier 2 requires an elevated Agent" row
|
||||
— as false now, not merely vacuous.
|
||||
|
||||
**§M5 was promoted from a design note to a blocker on a user-facing claim.** Whether LHM GPU
|
||||
sensors work unelevated without PawnIO is UNMEASURED; if they do not, the DEFAULT Agent's Tier-2
|
||||
session is **duration only**, which would falsify the sentence this change puts into `README`,
|
||||
the consent dialog and the EULA. All three therefore say *"whatever hardware telemetry this
|
||||
machine can provide"* — honest under either outcome, vague on purpose.
|
||||
|
||||
Twenty files. The ones that changed MEANING without changing WORDS are annotated in place —
|
||||
chiefly the 32-bit / D3D9 catalogue, "Tier 2" before and after, which went from *frame times
|
||||
without injection* to *unmeasurable in v1* across six files.
|
||||
|
||||
### Removed
|
||||
|
||||
- **`14_TESTING` §Tier cross-validation — a RELEASE-BLOCKING accuracy gate — is struck, and nothing
|
||||
replaces it.** It required Tier 1 and Tier 2 over the same frames agreeing within 1%. There is no
|
||||
second instrument. Its own last sentence is why this is recorded rather than dropped: it called
|
||||
itself *"the check that would have caught the original detection-accuracy problem"*.
|
||||
|
||||
**So Tier-1 frame times are not falsifiable by anything inside this project.** This is the same
|
||||
absence that killed the frame-generation oracle — one root cause, two casualties, and until now
|
||||
only §S31 was written down. A Tier-2 mechanism would restore both (§G).
|
||||
|
||||
- `EtwFrameSource` from the design, `fg_source`'s `etw` value, `HelloAck.etwAvailable`,
|
||||
`CaptureError.EtwAccessDenied`, the `PresentMon version` field in `sysinfo.json`, and the
|
||||
three-tier dropdown in the bug-report template.
|
||||
|
||||
- **PresentMon is DROPPED — owner decision 2026-08-27 — and Tier 2 keeps its place while losing
|
||||
its mechanism.** §S31 retired it as a measurement oracle (row P2); this removes it as an
|
||||
implementation. It is not bundled, not fetched, not used, and `tools/frametype-oracle.ps1` — the
|
||||
parser written for its output — is deleted with it, along with its `build.ps1` gate.
|
||||
|
||||
**Twelve documents named it as the Tier-2 mechanism and every one is corrected**: `CLAUDE.md`'s
|
||||
pinned-stack row, `README`'s capture-tier table **and its safety row**, `01_ARCHITECTURE`'s tier
|
||||
table and ADR-3, `03_METRICS` rung 2, `04_CAPTURE`'s source table and tier selection,
|
||||
`05_DETECTION`'s two Tier-2 rows, `07_IPC`'s `PresentMonMissing` error code, `12_BUILD`,
|
||||
`13_CI_CD`, `14_TESTING`'s CSV-parser row, `15_ROADMAP`'s P2 phase and v2 backlog, and
|
||||
`legal/THIRD_PARTY_NOTICES.md` plus `legal/licenses/README.md`.
|
||||
|
||||
**The notices row and `license-check`'s claim had to go together, and that is the gate working.**
|
||||
`tools/license-check.ps1` bound `Intel PresentMon` to `assets/native/PresentMon.exe`
|
||||
bidirectionally; removing the row alone fails with *"no table row mentions Intel PresentMon, so
|
||||
its bundling claim cannot be checked"*. Removing a claim is a deliberate act and is recorded as
|
||||
one. `legal/licenses/README.md` also listed a `presentmon-MIT.txt` that never existed.
|
||||
|
||||
**§M1, §M2 and §M6 close by DECISION, not by measurement**, and each says so: they were questions
|
||||
about a tool that no longer has a subject. §M2's answers are kept in full because every one cost a
|
||||
measurement. **§G is not closed — it gets bigger**: *"is the binary committed or fetched?"* becomes
|
||||
*"by what mechanism does a shipped build reach Tier 2 at all?"*, and nothing in this repository
|
||||
names one.
|
||||
|
||||
**What this costs users, stated where they will read it.** `README`'s **safety** row promises a
|
||||
no-injection mode as *"always a way out"*, and `legal/DISCLAIMER.md` §73 and `legal/EULA.md` §33
|
||||
both call it **the default** for uncertain cases. The README row now carries the fact that it is
|
||||
unbuilt and has no chosen mechanism, so **a refused or unhookable title gets Tier 3** — session
|
||||
duration and hardware telemetry. The two legal documents still say "default" without that
|
||||
qualification; §G owns the gap and names them. Not fixed here, because changing a legal document
|
||||
is not a cleanup.
|
||||
|
||||
**And the discriminator run was attempted and produced nothing**, so it settled nothing: the
|
||||
command targeted `explorer.exe`, which may present nothing PresentMon tracks, and "no CSV" is
|
||||
indistinguishable from "no `FrameType` column" — the §Traps entry about a canary that dies before
|
||||
reaching the gate. Badly chosen target, recorded as such, and moot now.
|
||||
|
||||
- **§S31 ran, and PresentMon is RETIRED as the application-frame oracle — row P2.**
|
||||
Three legs, three game launches, Cyberpunk 2077 at off / ×2 / ×4. `FrameType` is present and
|
||||
**every row of all three legs reads `Application`** — 1,937 / 6,488 / 10,881 rows, no other
|
||||
value anywhere, counted off the raw CSVs rather than off the tool's summary.
|
||||
|
||||
**The half that makes it a measurement rather than a shrug:** the two instruments agree on the
|
||||
present rate to within **0.3% on every leg** (43.16 vs 43.04, 144.31 vs 144.18, 241.84 vs
|
||||
241.80 present/s). They are counting the same stream, displayed rate tracks the configured
|
||||
multiplier, and at ×4 roughly three presents in four cannot be application frames — while
|
||||
PresentMon classifies **100%** of them as application frames. `tools/frametype-oracle.ps1`
|
||||
reported it as a **falsifier** on all three legs and never as a ratio of 1.0, which is the one
|
||||
behaviour it was written to guarantee.
|
||||
|
||||
**What P2 retires and what it leaves untouched.** Retired: PresentMon 2.x `FrameType` as the
|
||||
oracle for NVIDIA frame generation, and `03_METRICS` rung 2 is narrowed — the honest scope is
|
||||
now *no vendor is known to instrument this provider, and one is known NOT to*. **Not answered:**
|
||||
§S31's actual question. *Is a drained Streamline batch an application frame?* is exactly as open
|
||||
as it was; `presents/batch` still reads 2.00 and 3.99 on the same unverified premise and is
|
||||
still unpublishable as `fg_factor`. **Four oracles have now fallen.** `HANDOFF` item 3 goes back
|
||||
to the hook routes — unblocked, unmade, and now without an oracle behind whatever is chosen.
|
||||
|
||||
**One sub-question is unmeasured and it changes the REASON, not the action:** whether
|
||||
`--track_frame_type` was in effect at all. If the column ships by default, the legs recorded a
|
||||
default rather than an absence. Both branches end at *PresentMon did not answer as invoked*,
|
||||
which is why the row landed without waiting. The discriminator is one five-second run without
|
||||
the flag; it needs elevation, and it is recorded in §S31 with the command.
|
||||
|
||||
**Two findings nobody was looking for.** The `off` leg drained **zero** Streamline batches,
|
||||
against `presents/batch = 1.000` at off in §8 — Ray Reconstruction was not on, and §S30
|
||||
established RR is what produces batches when FG is off, so our side had two readable legs and
|
||||
not three. And the CSV's **first column is named `Application`** while the value being counted
|
||||
in column 9 is also `Application`: a parser resolving by position, or grepping for the word,
|
||||
counts process names. That rule was written into the oracle before it had ever seen a real CSV.
|
||||
|
||||
§M2's column set is measured at last — 24 columns — and `kFeatureDLSS_G` is zero on all three
|
||||
legs, taking that to five capture sets across five titles.
|
||||
|
||||
- **Five real-title captures across four titles, and the RT tri-state is complete** —
|
||||
`spike-notes` §6 and §8 carry the numbers; §8's per-title table was empty and now has five
|
||||
rows. Every run: 40 s, one swapchain, one segment, **0 gaps, 0 dropped**, `faults=0`, all six
|
||||
hook families installed, payload hash-verified against the just-built DLL first.
|
||||
|
||||
**`Yes` twice and `No` twice, every verdict agreeing with the game's own settings menu.**
|
||||
Cyberpunk 2077 with path tracing on and Black Myth: Wukong at RT High read `Yes`; Rune
|
||||
Factory: Guardians of Azuma, whose menu has no ray-tracing option, **and Cyberpunk with every
|
||||
RT option switched off** read `No` — the branch that had never been reachable. The second is
|
||||
the harder case: a title that *can* ray-trace and is not doing so. Both negatives satisfy all
|
||||
three conjuncts (`rtTier` 12, `RtAsBuild` installed, zero evidence over 36,575 and 16,871
|
||||
claiming records).
|
||||
|
||||
**The #87 falsifier did not fire, on two independent titles.** `rt_frame_pct` reads **25.0%**
|
||||
of the claiming window at ×4 on Cyberpunk and on Wukong — and Wukong got there through the RT
|
||||
evidence alone, with no Streamline batches involved at all.
|
||||
|
||||
**HANDOFF item 3's premise generalises from one title to four, and gets stronger.**
|
||||
`kFeatureDLSS_G` is zero on every run, and **two of the four titles never call
|
||||
`slEvaluateFeature` at all** — Wukong with `sl.interposer.dll` and `sl.dlss_g.dll` both loaded
|
||||
and DLSS-G demonstrably running, and Rune Factory. So it is not that DLSS-G avoids that
|
||||
export; on half the titles measured nothing goes through it, and `upscaler` correctly reads
|
||||
`Unknown` — *a hook ran and could not identify what it saw* — the first time that distinction
|
||||
has mattered outside a fixture.
|
||||
|
||||
**§S30's closure survived a test in the reverse direction it never had.** It concluded that
|
||||
Ray Reconstruction *replaces* the super-resolution pass, from one configuration. Turning RR
|
||||
off on the same title flips the census from `DLSS_RR` 2578 / `DLSS` 0 to **`DLSS` 4242 /
|
||||
`DLSS_RR` 0**, which is also the **first observation of `kFeatureDLSS` anywhere in this
|
||||
project**, and the local-tag extent arrives on that evaluation exactly as it did on the RR
|
||||
one — the same 1485×835.
|
||||
|
||||
**A second FG proxy, covering what the first cannot.** `presents ÷ RT-active presents` read
|
||||
**5,764 / 1,441 = 4.0000 exactly** on Wukong, where `presents/batch` is unreadable. Same
|
||||
unverified premise, disjoint coverage, still a proxy and not a producer.
|
||||
|
||||
**Two honest absences and one unexplained result.** `FL_MEASURED_UPSCALER_PARAMS` produced
|
||||
nothing on three of four titles — §2b's local-tag route is narrower than that entry assumed,
|
||||
and the writer published nothing rather than something wrong. And **Alan Wake 2 is not
|
||||
explained**: `presents/batch` = 1.00 with `rt_frame_pct` = 96.8% against a menu set to FG 4X
|
||||
fits both "generated presents miss our vtable" (§H5 case 3) and "frame generation was not
|
||||
running". The operator reported that title would not apply its settings, which is evidence for
|
||||
the second, and is why it is **not** written up as §H5 case 3. The discriminating run was not
|
||||
taken.
|
||||
|
||||
### Added
|
||||
|
||||
- **`fl-probe-signer`, and §S19(b)'s three questions answered before anything is designed.**
|
||||
That entry has been deferred since 2026-08-05 and its own rationale names the next step:
|
||||
*"Build `fl-probe-signer` first, in the shape `fl-probe-guard` established, and answer those
|
||||
three questions with measurements before any design is fixed."* This is that probe
|
||||
(`ctest fl_signer_probe`). **Nothing under `FrameLedger.Injector` changes with it** — reading
|
||||
a row off the table is a separate PR, including the row that says build nothing.
|
||||
|
||||
**The two Q1 results cut opposite ways, which is what makes the work affordable.** The CI
|
||||
blocker — `System.Security.Cryptography.ProtectedData.dll` — is embedded-signed and verifies
|
||||
offline as `O=Microsoft Corporation`, already in the shipped `trustedSigners`, so the embedded
|
||||
half alone would clear that refusal. But `mskeyprotect.dll`, the module §S19(b) was *written
|
||||
about*, returns `TRUST_E_NOSIGNATURE` on the embedded route and `ERROR_SUCCESS` only on the
|
||||
catalog one. The entry predicted exactly that; it is now measured rather than argued, and the
|
||||
expensive `CryptCATAdmin*` half is **not** on the path to the merge gate.
|
||||
|
||||
**§S19(b) also mis-describes the module, and the correction closes the cheapest-looking
|
||||
route.** It calls the blocker "a .NET shared-framework assembly". It is not —
|
||||
`Microsoft.NETCore.App` 10.0.11 does not contain it. It is a NuGet package assembly (6.0.0)
|
||||
reached transitively as `Microsoft.NET.Test.Sdk` → `System.Configuration.ConfigurationManager`
|
||||
→ `System.Security.Cryptography.ProtectedData`. So "just drop the package reference" fails:
|
||||
dropping it means dropping the test SDK.
|
||||
|
||||
**Q3 came back neither pass nor fail, and that is the honest answer.** Under
|
||||
`WTD_REVOKE_NONE | WTD_CACHE_ONLY_URL_RETRIEVAL`, `cryptnet.dll` is **newly loaded** — in a
|
||||
census bracketing the offline arm alone. Mapped is not transmitted, and this probe has no
|
||||
packet counter, so it reports the module and refuses to conclude. The discriminating run is the
|
||||
owner's: adapters disabled, same subjects, compare verdicts.
|
||||
|
||||
> **The probe's first version could not have told the two arms apart.** It censused once at
|
||||
> the top and once at the bottom with *both* the offline and the default
|
||||
> `WTD_REVOKE_WHOLECHAIN` calls in between, so `cryptnet.dll` appeared and the delta could not
|
||||
> attribute it — a census spanning both arms of the comparison it exists to discriminate.
|
||||
> Fixed before the recorded run. It read like an answer, which is why it is written down.
|
||||
|
||||
**Q2:** about 3.5 ms per module, and **warm is not cheaper than cold** (3.45 vs 3.54 ms over
|
||||
20 repeats) — there is no amortisation to plan around. Comfortable against the 30 s re-scan
|
||||
only because the scan set is small; a cache *within* one evaluation is admissible, a cache
|
||||
*across* evaluations is a re-scan that did not run.
|
||||
|
||||
**The decision table is honest about what it is.** §S30 and §S31 each pre-committed theirs
|
||||
before the run. This one could not: the probe had to be run to be finished, since its
|
||||
acceptance criterion is that it *prints* answers. The rows are therefore pre-committed only
|
||||
for the legs still **unrun** — CI, and the adapters-disabled run — and the entry says so in
|
||||
its first paragraph rather than borrowing a discipline it did not follow.
|
||||
|
||||
**And a constraint no measurement can lift.** Wiring the signer half makes `trustedSigners` a
|
||||
live allow-widening surface, and the gate over it — `Rules / validate` — is **not** a required
|
||||
status check on `main` (§S23-2). `19_SAFETY` already ruled on this shape: *"the boundary of
|
||||
what the gate looks at is code."* So even a clean result does not authorise the build. Owner
|
||||
decision, recorded in §S19(b).
|
||||
|
||||
Carries a canary: the probe's own unsigned executable must return `TRUST_E_NOSIGNATURE` and
|
||||
yield no organisation, so a green run discriminates rather than merely running —
|
||||
`fl-baseline-probe` was retired by exactly this class of test. The include block is
|
||||
`clang-format`-fenced and says why: `.clang-format`'s `IncludeBlocks: Regroup` sorts
|
||||
`<mscat.h>` ahead of `<wincrypt.h>`, and `mscat.h` uses types `wincrypt.h` declares, so the
|
||||
alphabetical order fails with twenty errors inside the Windows SDK and one in our own code.
|
||||
|
||||
- **`tools/frametype-oracle.ps1`, and §S31 with its decision table written BEFORE the run.**
|
||||
HANDOFF item 3's producer decision needs one measurement: is a drained Streamline batch an
|
||||
application frame? Three oracles have already fallen, so the mapping from measurement to
|
||||
action is committed first, in the file that owns the item — the discipline §S30 used,
|
||||
including the part where its table turned out to have holes and was kept unchanged anyway.
|
||||
Two of §S31's six rows **retire** PresentMon outright. The tool compares **two dimensionless
|
||||
ratios** — PresentMon's `displayed / application` against our `presents / batch` — because
|
||||
§S30's own correction records that comparing *rates* needs a shared span, and the span is
|
||||
where the previous draft went circular. Its `-SelfTest` runs in `build.ps1 check`.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`03_METRICS`' frame-generation ladder presented rung 2 as unconditional, and it is not.**
|
||||
Measured 2026-08-20: `--track_frame_type` is a **beta** option in PresentMon 2.5.1 whose own
|
||||
help says it *"requires application and/or driver instrumentation using Intel-PresentMon
|
||||
provider"*. So `FrameType` reports events a vendor chose to emit rather than classifying any
|
||||
present from first principles, and whether NVIDIA's DLSS-G driver instruments Intel's
|
||||
provider is unmeasured — which decides whether the rung exists at all on the titles P0 needs.
|
||||
The ladder now says so, and adds the consequence: a `FrameType` column that classifies
|
||||
nothing is an **absence**, so rung 0 turns it into `N/A` rather than rung 4 turning it into
|
||||
`none`.
|
||||
- **Ray tracing has a producer, and the RT tri-state's `Yes` and `No` are reachable for the
|
||||
first time.** `ID3D12GraphicsCommandList4::DispatchRays` and
|
||||
`::BuildRaytracingAccelerationStructure` are detoured, `rtFlags` and `dispatchRaysVolume`
|
||||
are drained per present with `exchange(0)` beside `g_slSeen`'s, and `FL_MEASURED_RT` is set
|
||||
whenever either family is live. `rtTier` and `hooksInstalledMask` already had producers, so
|
||||
all three conjuncts of `03_METRICS`' `No` branch are now live. §S29(f) is closed on both of
|
||||
its halves, and CLAUDE.md rule 7 is amended per the 2026-08-14 owner ruling: `N/A` applies to
|
||||
*naming the technique as RayQuery*, not to whether rays are being traced.
|
||||
|
||||
**Both hooks, because one of them alone is a trap.** A writer with only `DispatchRays` sees
|
||||
nothing on an inline-RayQuery title, and its silence is indistinguishable from a real
|
||||
negative. The injected fixture pair makes that falsifiable rather than a sentence in a
|
||||
document: two harness modes differing by **one recorded call**, sharing their acceleration
|
||||
structure, state object, swapchain and loop — `--hold-presenting-dxr` yields dispatch
|
||||
evidence and an exact multiple of the fixture's own 64×32×1 volume, `--hold-presenting-rayquery`
|
||||
yields AS-build evidence and **zero** dispatch evidence.
|
||||
|
||||
- **`fl_rt_accum.h`** — the dispatch-volume arithmetic in a header, with its identities as
|
||||
`static_assert`s and its behaviour in `ctest fl_dxr_inputs`, the same split `fl_sl_seen.h`
|
||||
uses. **The assertions found a real wrap bug before it ever ran**: `AddedTo(cur, add)` with
|
||||
`add` near `UINT64_MAX` — which the saturating product returns for a hostile descriptor —
|
||||
overflowed the 64-bit sum and wrapped to a small number that passed the ceiling check. They
|
||||
also corrected the justification written above them: two `uint32`s multiply *within* a
|
||||
`uint64`, and it is the third dimension that overflows.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The ray-tracing hook installed, published its family bit, and never fired — and the reason
|
||||
generalises past ray tracing.** A command list's first `Reset()` replaces its class vtable
|
||||
with a **per-object** one in which the vendor driver has taken methods over: measured on an
|
||||
RTX 5080, `DispatchRays` moves from `D3D12Core.dll` into `nvwgf2umx.dll` while
|
||||
`BuildRaytracingAccelerationStructure` stays put. Every game resets its lists every frame, so
|
||||
the addresses in an unreset throwaway's vtable are ones no title ever calls for the moved
|
||||
methods. The injected fixture caught it exactly — `withDispatch = 0` beside
|
||||
`hooks = RT_DISPATCH | RT_AS_BUILD`, a mask bit with nothing behind it — and because the
|
||||
*other* hook worked it read as a bug in the dispatch detour rather than in the acquisition
|
||||
they share. **The rule: put a throwaway object through the same lifecycle the game's objects
|
||||
go through, or it is not a sample of them.** The fix is one call.
|
||||
|
||||
- **Two of #86's five pre-flight answers were wrong, and this corrects them.** That probe read
|
||||
vtables off **freshly created** lists and compared vtable ARRAYS — neither of which is what a
|
||||
hook depends on, since a game's list is Reset and the Overlay patches the FUNCTION a slot
|
||||
points at. Corrected, measuring reset lists and comparing functions: **Q3** is now *DIRECT and
|
||||
COMPUTE resolve to the SAME functions*, so one detour per method covers both list types
|
||||
(#86 said they did not share and the hook must patch two vtables); **Q4** is now *a WARP list
|
||||
and a hardware list resolve to DIFFERENT functions*, so a throwaway-device acquisition would
|
||||
silently miss every call (#86 said they shared and one would have worked). A new Q5 prints the
|
||||
module on each side of the `Reset` so the next machine answers for itself rather than
|
||||
inheriting one driver's behaviour.
|
||||
|
||||
- **`IsHonest` did not cover `dispatchRaysVolume`**, on either side of the mirror. A volume set
|
||||
with `FL_MEASURED_RT` clear is a writer contradicting itself and is the shape a drain that
|
||||
cleared one word and not the other would produce; 0 is a real measurement, so only the mask
|
||||
bit can tell the two apart. Added to `MeasuredFacts.IsHonest` and to its native twin.
|
||||
|
||||
- **The Overlay's "NOT SET, deliberately" list had gone stale three entries deep**, in a comment
|
||||
block whose whole subject is which measurements have no producer. It still described
|
||||
`FL_MEASURED_UPSCALER_PARAMS` as having "no source in this writer" after `Hook_SlSetTag` gave
|
||||
it one. Rewritten to what is actually absent — PSO, VRAM, latency, HDR — with the staleness
|
||||
itself recorded.
|
||||
|
||||
- **HANDOFF item 4's pre-flight, run before a single ray-tracing hook was written — and it found
|
||||
the defect the hook would have shipped.** `fl_d3d12_vtable.h` records the two
|
||||
`ID3D12GraphicsCommandList4` slots (72 `BuildRaytracingAccelerationStructure`, 76
|
||||
`DispatchRays`), one header and two consumers, and `ctest fl_d3d12_vtable_indices` proves each
|
||||
by **behaviour on both list types** rather than by the COM ABI's say-so. `ctest fl_dxr_probe`
|
||||
answers four questions the hook design must not guess at, and prints an unanswerable one as
|
||||
unanswered rather than as a pass.
|
||||
|
||||
**DIRECT and COMPUTE command lists do NOT share a vtable.** A hook patching only the DIRECT
|
||||
class would have missed every AS build and every `DispatchRays` recorded on a compute list —
|
||||
and async BLAS builds on a compute queue are ordinary practice. The mask bit would still be
|
||||
set and the evidence would be absent, so `03_METRICS`' `No` branch would have published a
|
||||
**confident `Ray Tracing: No` about a title that ray-traces every frame**, with all three of
|
||||
its conjuncts satisfied and none of them watching this direction. The two vtables hold the
|
||||
*same function pointers*, so the fix is a patch applied twice or one inline patch on the
|
||||
shared target; what is now excluded is patching one and stopping.
|
||||
|
||||
Also measured: **WARP reports `RaytracingTier` 12 here**, so a DXR fixture is not condemned to
|
||||
a GPU box — item 4's "check first whether WARP supports DXR" is answered for this machine, and
|
||||
the probe prints the tier on every run so CI answers for itself. And a WARP list and a
|
||||
hardware list **do** share a vtable, so a throwaway-device acquisition would have worked; the
|
||||
design still takes the vtable off the game's own device, because this machine lost WARP's
|
||||
D3D12 path to an Insider build for a fortnight and a design that needs no WARP cannot be taken
|
||||
down by one. `spike-notes.md` §6 carries the numbers, `17_HOOK_ENGINE` §Ray tracing the
|
||||
constraint.
|
||||
|
||||
- **`presents / batch` gets a guard of its own, because the one it had could not fail.**
|
||||
`FgWindow.BucketFactors` splits the window into eight buckets and refuses a factor when one
|
||||
departs from the whole — and it divides by `Σ fgEvaluations`, which is **zero on every record**
|
||||
on the one route a real title has been measured on. So every bucket matched, the check passed
|
||||
vacuously, and `RefusalFor` returned at the data-gap clause before uniformity was ever
|
||||
considered, while `presents / batch` was printed underneath with nothing behind it. Measured
|
||||
2026-08-16: an alt-tab mid-capture produced an achieved ratio of **1.84** against a title
|
||||
configured for ×2 — wrong by 8%, and the report said nothing. `FgWindow.BatchRefusal` is the
|
||||
per-bucket `presents / batch` check §S30 named as a prerequisite, `FgWindow.PresentsPerBatch`
|
||||
moves the arithmetic out of the renderer, and `SessionReport` prints the verdict on the line
|
||||
under the ratio so the number cannot be read without it. Proven both ways: a canary returning
|
||||
`null` from the check turns the two uniformity cases red and leaves the uniform case and the
|
||||
attribution refusals green.
|
||||
- **The capture host samples whether the operator was actually watching the game**, once per
|
||||
10 Hz drain tick, and the session carries the pair `(DrainTicks, ForegroundTicks)`.
|
||||
Out of process — `ForegroundWindowProbe` in `Infrastructure`, two documented Win32 calls — so
|
||||
it costs the hook path nothing, reads nothing belonging to the target, and needs no record
|
||||
byte; §S30 suggested doing it in-process and that would have bought nothing. **The pair,
|
||||
because zero is not a finding:** a target owning no top-level window is unfocused on every
|
||||
tick of every run, which is what `hook-harness` does, so collapsing "never had focus" into
|
||||
"lost focus" would fire on every integration run. It is attribution and never the guard —
|
||||
`BatchRefusal` refuses a mixed window from the records alone, so a caller that never wires
|
||||
focus still cannot publish an averaged ratio.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`hook-harness/CMakeLists.txt` still carried the pre-2026-08-14 subtraction** in the comment
|
||||
justifying module-scoped resolution — a fifth site for the formula `fl_shm.h` retracts. The
|
||||
argument survives the correction with its polarity flipped: an inflated count now inflates
|
||||
Native FPS and deflates `fg_factor`.
|
||||
- **Ray Reconstruction answered `N/A` on every frame-generating title, and the reason was a
|
||||
consumer bug rather than a coverage gap.** `MeasuredFacts.RayReconstructionOf` required
|
||||
`FL_FEAT_RAY_RECONSTRUCTION_OBSERVED` on **every** record in the stream, while the writer sets
|
||||
that bit only on the present that drained a Streamline batch — roughly one in four at ×4,
|
||||
measured 24% on the Cyberpunk 2077 stream. A condition that cannot hold above ×1 meant the
|
||||
verdict was decided by the frame-generation setting rather than by whether Ray Reconstruction
|
||||
ran: the title evaluated `kFeatureDLSS_RR` on 2,523 of 2,523 batches and this reported `N/A`.
|
||||
The population is now the batch-carrying presents — none ⇒ `N/A`, any carrying the fact bit ⇒
|
||||
`Yes`, batches with none ⇒ `No`, the branch that was unreachable. The lazy-install prefix drops
|
||||
out for free instead of forcing `N/A` over a whole session.
|
||||
|
||||
The comment this replaces reasoned that the alternative would publish a whole-session verdict
|
||||
from a single frame and that fixing it needed the application-frame unit HANDOFF item 3 would
|
||||
introduce. Both halves were wrong — the natural population is thousands of batches, not one
|
||||
frame, and it needs no application-frame unit, which is fortunate because item 3 could not
|
||||
produce one. Proven both ways: restoring the `All` rule turns the three positive cases red and
|
||||
leaves `NoBatchObservedIsNAAndNeverNo` green, so the fix is not "answer `Yes` to everything".
|
||||
- **Four comments still carried the pre-2026-08-14 subtraction `F_app = presents − Σ
|
||||
fgEvaluations`**, which `fl_shm.h` explicitly retracts — `ShmLayout.cs`, `MeasuredFactsTests`,
|
||||
`stub_sl_common.cpp` and `fl-probe-interposer`. The mirror's doc comment also said the count is
|
||||
"3 at ×4"; it is 1 per application frame at every multiplier, and the two forms differ by a
|
||||
factor of four on the one real title measured. The decoy stub's arithmetic argument was
|
||||
reversed by the same correction: an inflated count now INFLATES Native FPS and DEFLATES
|
||||
`fg_factor` rather than the other way round.
|
||||
- **`docs/HANDOFF.md` item 3 contradicted itself inside one entry** — one block recorded that
|
||||
three oracles had been tried and fallen, and a later bullet said neither of the two cheap
|
||||
measurements had been run. `fl-baseline-probe` was run on 2026-08-16 and retired by its own
|
||||
pre-committed falsifier; only the game's own frame counter is still unrun.
|
||||
- **`docs/HANDOFF.md`'s "`./build.ps1 check` cannot go fully green here" is no longer true**, and
|
||||
it was the first thing a new session read. Measured 2026-08-20: the gate is fully green on the
|
||||
dev box, 20/20 native tests, and `hook-harness --probe-d3d12` succeeds. Nothing in this
|
||||
repository fixed it — the machine moved from Insider build 26300/29639 to **29648**, with
|
||||
`d3d10warp.dll` and `D3D12Core.dll` both at `10.0.29648.1000`, so the WARP D3D12 regression was
|
||||
fixed upstream. The trap entry is dated rather than deleted: the durable fact is that this
|
||||
dependency broke and healed under the machine without a code change, twice giving the native
|
||||
suite a colour that said nothing about `main`.
|
||||
|
||||
### Changed
|
||||
|
||||
- **`spike-notes` §11 is filled, and the news is bad in a useful way.** PresentMon **2.5.1**
|
||||
is present and pinned by hash (956,768 bytes, SHA256 `9BEC…A191`) — **it carries no
|
||||
VERSIONINFO at all**, so pinning can only mean hash plus filename, which is worth stating in
|
||||
a repository that requires that metadata of everything it builds. It does **not** run
|
||||
unelevated here: exit 6, and the account is in neither Administrators nor Performance Log
|
||||
Users. `PresentMonSharedService` is installed and running as LocalSystem and **does not
|
||||
help** — the console starts its own trace session — which answers half of §M6 in the
|
||||
direction nobody expected. The 2.x column set is therefore still unmeasured, and
|
||||
`tools/frametype-oracle.ps1` **has never seen a real PresentMon CSV**: it resolves columns by
|
||||
name, prints the whole `FrameType` vocabulary rather than assuming one, and refuses loudly
|
||||
instead of guessing. Said plainly rather than left for the next reader to assume.
|
||||
|
||||
- **XeFG and FSR3-FG identity is deferred with a written rationale (§H11)**, which is what
|
||||
HANDOFF item 3 asked for instead of a guess. `libxess_fg.dll` and `ffx_fsr3_x64.dll` export
|
||||
nameable entry points; the newer `amd_fidelityfx_framegeneration_dx12.dll` (3.1.5, three
|
||||
installed titles) exports only five generic `ffx*` names, so identity lives in a struct field
|
||||
and hand-declaring a vendor ABI from observation is the #71 defect class with another
|
||||
vendor's name on it. The licence checklist has not been run on either SDK either. **The cost
|
||||
is coverage, not correctness**: such a title reports `FL_FG_UNKNOWN`, never `NONE`.
|
||||
|
||||
- **The ledger now records what five real-title captures actually established, and HANDOFF
|
||||
item 3 is struck because its premise is false.** `slEvaluateFeature(kFeatureDLSS_G)` is
|
||||
never called by Cyberpunk 2077 — 0 across ~14,000 Streamline batches at four
|
||||
frame-generation settings, while frame generation was demonstrably active — so the
|
||||
2026-08-14 owner ruling to count evaluations directly is correct arithmetic on a route the
|
||||
vendor does not use. The counter, its drain, its consumer and its fixtures are all in and
|
||||
gated; there is nothing to count. The open question is no longer "build a counter" but
|
||||
"what is the in-policy producer for DLSS-G on Streamline 2.x", and item 3 now lists the
|
||||
candidate routes without choosing one.
|
||||
- **§H5 is NARROWED, not closed, and the wording is deliberate.** `presents / batch` reads
|
||||
1.000 / 2.000 / 4.000 against the title's own off / ×2 / ×4 (×4 three times), one
|
||||
identified swapchain and 0 gaps in every run — so generated presents ARE visible to a hook
|
||||
on the shared `dxgi.dll` vtable and the count tracks the MULTIPLIER, which a two-point
|
||||
sweep could not have shown. Recorded as still open: case 3 is narrowed rather than
|
||||
answered; **case 2 is made worse** — at ×4 roughly 75% of records carry `syncInterval` /
|
||||
`presentFlags` no application call produced, and the writer claims
|
||||
`FL_MEASURED_PRESENT_ARGS` on all of them; the proxy's denominator is unverified, because a
|
||||
batch equals an application frame only if Ray Reconstruction is evaluated once per frame,
|
||||
which no independent oracle has confirmed.
|
||||
- **`03_METRICS` §Frame Generation and §RT/PT/RR both carry the consequence.** `F_app =
|
||||
Σ fgEvaluations` was written when the counter was expected to have a producer; the section
|
||||
now states that on the measured route it yields zero and that `presents / batch` must not
|
||||
be promoted to `fg_factor` without its premise attached. And RT's per-application-frame
|
||||
quantities — `rt_frame_pct`, `rays_per_pixel`, the 5% gate — are left **without a settled
|
||||
denominator**, which is now the first thing HANDOFF item 4 has to decide rather than
|
||||
something it inherits.
|
||||
- `17_HOOK_ENGINE`'s FG row stays ✅ and says it counts zero on the measured route — built,
|
||||
honest, and yielding nothing is three different facts from unbuilt.
|
||||
- `15_ROADMAP` item 7's ETW comparison is struck as blocked on a producer rather than on
|
||||
tooling, and `spike-notes` §9 — three empty bullets since the file was written, and the
|
||||
section named after this item — carries the five-capture table.
|
||||
- §S30 closed in §S24 with the two defects it produced on the way out: the pre-committed
|
||||
decision table had two holes, and the fix contaminated the census that found it.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **§S30 is ANSWERED, and the answer is that Ray Reconstruction was doing the upscaling all
|
||||
along.** Cyberpunk 2077, 2026-08-15, three 40 s captures: with `DLSS_D = True` the title
|
||||
evaluates `kFeatureDLSS_RR` on every application frame and `kFeatureDLSS` **not once** —
|
||||
2,569 of 2,569 batches, zero DLSS, zero NIS, zero undecoded ids. RR replaces the separate
|
||||
super-resolution pass rather than running beside it, and the decode had no arm for it, so
|
||||
every record reported `UNKNOWN`. **What makes this evidence and not an inference:**
|
||||
`renderW/H` are published only on a frame where an evaluation was seen, and they came back
|
||||
`1485x835` against the title's own `DLSS = Balanced` at `2560x1440` — 0.58 exactly. The
|
||||
scaling-input tag arrives ON the RR evaluation. `FL_UPSCALER_DLSS` and not a new value:
|
||||
layout v3 retired `FL_UPSCALER_RETIRED_RAY_RECONSTRUCTION` precisely because RR is an
|
||||
independent axis, which `FL_FEAT_RAY_RECONSTRUCTION` already carries from the same word.
|
||||
- **The census was measuring its own subject, and the decode fix is what exposed it.**
|
||||
`SlCensus` derived "a super-resolution id arrived" from the DECODED `upscaler` byte, so the
|
||||
correction above made it report 2,569 arrivals of an id that arrived zero times — an
|
||||
instrument that moves when its subject moves cannot be evidence about the subject, which is
|
||||
the only job §S30 gave it. `FL_FEAT_SL_SUPER_RESOLUTION` now carries the RAW fact, set from
|
||||
the drain word and independent of any decode. An enumerator, not a field: no layout bump.
|
||||
It deliberately gets **no OBSERVED companion** against this enum's own convention — all
|
||||
three Streamline facts in the byte are published under one condition, so their companions
|
||||
would be equal bit for bit, and `FL_FEAT_RAY_RECONSTRUCTION_OBSERVED` already carries it.
|
||||
- **`UpscalerOf` read the LAST record, which under frame generation is usually the wrong
|
||||
one.** The writer publishes an identity only on presents that drained an evaluation — one
|
||||
in N — so at ×4 the last record is `UNKNOWN` with probability 3/4, and the report printed
|
||||
"a hook ran and could not identify it" three lines below its own raw block printing
|
||||
`upscaler=Dlss on 2561 record(s)`. Now scans for any record naming a technology, exactly as
|
||||
`FgModeOf` already did, and for the same reason.
|
||||
- Two `SlCensusTests` fixtures went red on the raw-fact change and were **right to**: they set
|
||||
a decoded `Dlss` without the raw bit, which is a state no writer produces. Corrected, and a
|
||||
new case pins the discrimination directly — a record with `upscaler == Dlss` and no raw
|
||||
super-resolution fact is the RR-decoded shape and must NOT count as an arrival of
|
||||
`kFeatureDLSS`.
|
||||
|
||||
### Added
|
||||
|
||||
- **The FG factor gets a consumer, and most of it is the refusals.** `FgWindow` takes
|
||||
`F_disp` and `F_app` from **one record set** — every drained record in one QPC span, not
|
||||
the dominant stream — because `g_slSeen` is one process-wide word drained by whichever
|
||||
present arrives first, so an evaluation belonging to the game's frame can be consumed by
|
||||
a UI swapchain's present. Summing the denominator over one stream while counting presents
|
||||
over all of them overstates the factor with no diagnostic. Five refusals, each a number
|
||||
this consumer would otherwise have printed as a measurement: nothing counted (a data gap,
|
||||
never 1.0); a saturated 255 (a sentinel, not a floor to divide by); a record with
|
||||
`swapchainId 0`; more than one stream in the span; and **the frame-generation state
|
||||
changing during the session**.
|
||||
- **That last one was found by an adversarial review of the design, before any of this was
|
||||
written, and it produces a number above the physically achievable one.** Half a session at
|
||||
×4 and half with FG off gives a whole-window factor of 8 from an ×4 configuration, and
|
||||
`NativeFps` inherits the whole error — while every other guard stays silent, because the
|
||||
count is not zero, the factor is not 1.0 and it is not below 1.0. `03_METRICS:133` already
|
||||
forbids this for upscaling ("averaging across a settings change is the classic way
|
||||
benchmark numbers become meaningless") and lists `fg_mode` as a **segment** column. The
|
||||
window is now split into eight buckets and any bucket whose factor departs from the whole
|
||||
refuses the lot.
|
||||
- **`evaluations/batch`, the premise check that needs no oracle.** HANDOFF item 3 rests on
|
||||
`slEvaluateFeature(kFeatureDLSS_G)` firing **once** per application frame, and nothing in
|
||||
this repository had verified it. The quotient of the two ratios a run can compute —
|
||||
`(presents/batches) ÷ (presents/Σ)` — reduces to `Σ/batches`, and it is the ONLY check
|
||||
that catches the k-per-frame case: three evaluations per frame at ×4 yields a factor of
|
||||
1.34, which is above 1.0 so an over-counting guard is silent, is not 1.0 so a
|
||||
structurally-1.0 guard is silent, and still **moves with the setting** so a three-point
|
||||
sweep passes too. Batches come from `FL_FEAT_RAY_RECONSTRUCTION_OBSERVED`, which the
|
||||
writer sets under `seen != 0` and nothing else — an exact indicator, unlike the params bit
|
||||
whose extra tag-validity conjunct makes the ledger's 4.0134 an upper bound.
|
||||
- **`NativeFps` is counted, not derived.** `Σ / seconds`, not `DisplayedFps / factor`.
|
||||
Derived, the rule-6 trio is internally consistent by construction and a reader can
|
||||
conclude nothing from that consistency; computed separately, `Native × Factor ≈ Displayed`
|
||||
is a property a test checks — to within exactly one frame, because Displayed counts
|
||||
intervals and Native counts records, and that difference is asserted rather than rounded
|
||||
away. The renderer now prints all three off **one** window or prints one labelled number
|
||||
and the reason, which is the half of rule 6 that had no test at all.
|
||||
- **`SlCensus` — §S30's "print them first", built rather than promised.** Per record, which
|
||||
of the five Streamline feature classes arrived, including the undecoded one, which is only
|
||||
separable because of the `FL_FEAT_SL_UNDECODED` bit added in the previous commit. It names
|
||||
the §S30 shape directly: batches that generated frames carrying **no** super-resolution id.
|
||||
- **The O1–O5 decision table is committed to `20_OPEN_QUESTIONS` §S30 BEFORE the run.**
|
||||
"Measure, then fix" becomes "fix, then justify" the moment the table is written after the
|
||||
numbers are known, and nobody can tell the two apart afterwards. The table includes the
|
||||
falsifier for its own independent oracle: if `fl-baseline-probe` reports `nvngx_dlssg.dll`
|
||||
LOADED with multi-frame generation off, it is not an oracle for FG engagement and must be
|
||||
retired in the same `spike-notes` row rather than quietly relied on.
|
||||
- **A factor of exactly 1.0 is NOT reported as §H5 case 3.** Three causes produce it and this
|
||||
data cannot separate them — generated presents never reaching the vtable we patch, FG
|
||||
configured off while the feature is still evaluated, and an evaluation that FAILED and was
|
||||
counted anyway, because `Hook_SlEvaluateFeature` increments before forwarding and ignores
|
||||
the `sl::Result`. The report prints all three. Naming one is how the item gets routed down
|
||||
the wrong branch.
|
||||
|
||||
- **`fgEvaluations` and `fgMode` get a producer, and the count is of EVALUATIONS.**
|
||||
`slEvaluateFeature(kFeatureDLSS_G)` now contributes to a saturating 24-bit count in the
|
||||
high field of the same word the feature bits live in (`fl_sl_seen.h`), consumed by the
|
||||
one `exchange(0)` `RecordPresent` already performed. A bit could not carry it: a bit
|
||||
collapses several evaluations between two presents into one, and under multi-frame
|
||||
generation that is the common case rather than the edge — 10,169 presents carried 2,461
|
||||
Streamline batches on the one real title measured.
|
||||
**The five existing consumers of that word are untouched**, which is why the split was
|
||||
chosen over a second atomic: `seen != 0` still means "an evaluation happened this
|
||||
present" (any evaluation either sets a feature bit or increments the count), and the
|
||||
three bit tests read bits 0-2, which the count cannot reach. Still exactly one
|
||||
read-modify-write per call, on either arm — making the count itself the identity removes
|
||||
the need for a compare-exchange rather than paying for one on a hook path.
|
||||
- **`F_app = Σ fgEvaluations`, not `presents − Σ fgEvaluations`** (owner ruling
|
||||
2026-08-14), swept across `03_METRICS` §Frame Generation and its export table,
|
||||
`fl_shm.h`'s field and mask comments, `fl_hook_inventory.h`'s module-scoping rationale
|
||||
and `17_HOOK_ENGINE`'s FG row. The subtraction needs a count of *generated* frames, and
|
||||
nothing can produce that in policy: the evaluation fires once per **application** frame
|
||||
and yields N−1 generated ones, where N lives in `sl::DLSSGOptions` — set out of band
|
||||
through `slDLSSGSetOptions`, the route HANDOFF §2b refused on five grounds. The two
|
||||
forms are not interchangeable: on the one real title measured they differ by ×4.
|
||||
`native_or_generated`'s polarity inverts with it, and the per-frame classification is
|
||||
now documented as exact in aggregate and accurate to one frame per record.
|
||||
- **`FL_FEAT_SL_UNDECODED` + its OBSERVED companion**, so §S30 can be answered rather than
|
||||
guessed at. Once frame generation leaves the feature bitmask, a present carrying
|
||||
`kFeatureDLSS_G` alongside any id that falls to `FL_SL_SEEN_OTHER` — Reflex, PCL,
|
||||
DeepDVC, Latewarp, DirectSR — is byte-identical to one that carried DLSS-G alone, so a
|
||||
consumer counting "presents that carried an id we cannot decode" would read ZERO on a
|
||||
title evaluating one every application frame. Cyberpunk runs Reflex. A decision table
|
||||
keyed on that bucket would have closed §S30 on a number that could not have been
|
||||
anything else. **Enumerators, not fields**: no struct change, so no
|
||||
`FL_SHM_LAYOUT_VERSION` bump, no `fl-layout-dump` entry, no `ShmLayout.cs` struct edit.
|
||||
- **The CONSUMER half is not in this PR, and a capture will still print "FG state not
|
||||
measured".** `MeasuredFacts.FgMode`, `NativeFps` and `FgFactor` stay hard-null: the
|
||||
arithmetic they need — one record set for both sides of the ratio, a refusal to publish a
|
||||
session-level factor across an FG state change, and the presents-per-batch cross-check —
|
||||
is its own change with its own canaries, and shipping half of it would put a number in
|
||||
front of a reader before the thing that decides whether the number is allowed. So the
|
||||
writer measures and the report is silent, on purpose, for exactly one PR.
|
||||
- **The decode is UNCHANGED, deliberately.** §S30 — a real title decoding every
|
||||
params-carrying record as `UNKNOWN` while running DLSS — is not fixed here. HANDOFF
|
||||
forbids by name changing the decode before the ids that actually arrive have been
|
||||
printed, because that turns a wrong answer into a confident wrong answer. This PR builds
|
||||
the instrument.
|
||||
- **`--hold-presenting-fg` and `--presents-per-eval`**, the first fixture in the tree where
|
||||
presents ≠ evaluations. Every other injected fixture evaluates once per present, so a
|
||||
writer counting evaluations and a writer counting presents are indistinguishable in all
|
||||
of them — every ratio is 1. It also passes the scaling-input extent as a **local** tag
|
||||
through `slEvaluateFeature`'s own `inputs` and never calls `slSetTag`, which closes a
|
||||
coverage hole this PR would otherwise have widened: `FindScalingInputExtent` has one
|
||||
production call site, inside the detour, and nothing reached it — every test called the
|
||||
header directly and every fixture passed `inputs = nullptr`. Frame generation now takes a
|
||||
different decode arm, so "the arm must fall through to the walk" became a property
|
||||
somebody could reasonably tidy away.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Four session calculators asked a question no session could answer yes to.** `UpscalerOf`,
|
||||
`RayTracingOf`, `HdrOf` and `RayReconstructionOf` each gated on `stream.All(... bit ...)`,
|
||||
and feature hooks install lazily from the 1 Hz watchdog — so the opening of every session
|
||||
predates them. Measured on Cyberpunk 2077: **292 of 10,169 records carry no `Upscaler`
|
||||
bit**, and the consumer therefore reported *"no upscaler hook ran"* about a session in
|
||||
which the hook was live for 97% of the presents. `Program.cs` had already grown a per-bit
|
||||
record count to explain that in prose. The three hook-liveness axes now aggregate over the
|
||||
maximal claiming **suffix**, and the boundary must be **clean** — a bit that goes on, off
|
||||
and on again is a writer contradicting itself, and its trailing run must not be averaged as
|
||||
though it were a whole session, which is the same defect reached from the other side.
|
||||
- **`RayReconstructionOf` is deliberately NOT in that sweep, and the reason is now in the
|
||||
code.** It looks identical and is not: the other three gate on a *hook-liveness* bit, which
|
||||
is monotonic, while this one gates on a *per-present observation* (`seen != 0`), which under
|
||||
frame generation is intermittent by construction — one Streamline batch spans ~4 presents on
|
||||
the Cyberpunk stream, so the maximal claiming suffix is ONE record and feeding it to the
|
||||
`Any` below would publish a whole-session Yes/No from a single frame. Worse than the `N/A`
|
||||
it returns today. Fixing it needs the application-frame unit HANDOFF item 3 introduces.
|
||||
- **`guard_test.cpp`'s honesty assertion was a hardcoded equality where the managed twin was a
|
||||
derived subset test.** It compared `measuredMask` against the constant
|
||||
`FL_MEASURED_OUTPUT_RES | FL_MEASURED_PRESENT_ARGS` with `!=` — right while the Overlay
|
||||
hooked only presents, and a statement about **one build** rather than about honesty. It is
|
||||
now derived from `hooksInstalledMask` the way `MeasuredFacts.EntitledBy` is, as a subset
|
||||
test, plus the value-without-bit conjuncts. Left as an equality it would have gone **red on
|
||||
a correct writer** the moment any feature bit is per-frame rather than per-session:
|
||||
`FL_MEASURED_UPSCALER_PARAMS` is gated on `seen != 0`, so under frame generation three
|
||||
records in four legitimately lack it. **The derived form is paired with an equality on
|
||||
`hooksInstalledMask` itself** — without it a writer that installed everything would be
|
||||
"honest" about any claim and the loop would pass while proving nothing.
|
||||
Both sides gained two conjuncts they were missing: `fgEvaluations` with `FG_COUNTS` clear,
|
||||
and `featureFlags` on a writer not entitled to claim an upscaler.
|
||||
**Two copies of one contract with nothing gating their agreement** — the struct mirror has
|
||||
`fl-layout-dump`; this does not. Stated in both files rather than left to be discovered.
|
||||
- **`slSetTag` shipped on 2026-08-15 with no row in `17_HOOK_ENGINE` §Hook inventory**, whose
|
||||
own first line says anything not on the list is not allowed to exist and which NFR-11 makes
|
||||
the enumeration of the hook set. `hookinventory-check` never reads that file — it checks
|
||||
`FL_HOOK_INVENTORY` against `vendor-exports.json` — so a shipped hook missing from the doc
|
||||
is invisible to every gate in the tree. Row added; the banner above it said **three** rows
|
||||
were built when the answer was five, and said a present-only writer's `measuredMask` is what
|
||||
the record carries, which stopped being true at item 2.
|
||||
- **The removed `presentdelta` rung outlived its removal in two more places.**
|
||||
`03_METRICS` retired `GetFrameStatistics().PresentCount` on 2026-08-05 as *structurally*
|
||||
zero rather than unreliable, and `17_HOOK_ENGINE` forbids re-adding it — but
|
||||
`05_DETECTION`'s FG row and `06_DATA_MODEL`'s `fg_source` enum both still named it. Both
|
||||
corrected, with the reasoning kept where a reader of either would need it.
|
||||
- **`sessions.fg_mode` defaulted to `'none'`**, reinstating at the storage layer the exact
|
||||
affirmative negative the writer and the consumer both refuse — `none` is the one FG state
|
||||
`03_METRICS` allows to be aggregated as a negative. Now `'na'`, matching the four tri-state
|
||||
columns beside it. And `frame_blobs.rt_flags` named its third bit `rtPsoAlive`, a name
|
||||
`fl_shm.h` renamed away because the bit **latches**: creation is observed at
|
||||
`CreateStateObject`, destruction is COM `Release`, which is not in the hook inventory and
|
||||
must not be added, so "alive" claimed a present-tense fact the hook set cannot retract.
|
||||
`06_DATA_MODEL:133` records that the schema is free to edit exactly once, before P2 writes
|
||||
`0001_init.sql`; after that these are migrations.
|
||||
|
||||
@@ -0,0 +1,994 @@
|
||||
<!-- Moved verbatim from CHANGELOG.md on 2026-10-19 (beta.24, owner decision D66): part 4 of 5 of the ledger kept before the first tag, newest first. CHANGELOG.md lists every part. -->
|
||||
|
||||
## Ledger before 0.1.0-beta.1 (continued, part 4 of 5)
|
||||
|
||||
### Added
|
||||
|
||||
- **`capture` can be bounded, because a real-title measurement otherwise could not end.**
|
||||
`CaptureLoop` honoured `CaptureOptions.MaxDuration` and tests covered it — **nothing could
|
||||
set it**, so `capture` against a running game ran until the game was closed, and the report
|
||||
only prints at the end. `--seconds <n>` is a **duration bound, not a safety bypass**: the
|
||||
options this host refuses (`--pid`, `--payload`, `--force`, `--yes`) each widen *what* is
|
||||
injected or skip a check, while this only shortens an already-consented, already-guarded
|
||||
session. A non-positive or non-numeric value is an **error, never a silent 0** — 0 means
|
||||
*unbounded*, so leniency would produce the opposite of what the operator asked for.
|
||||
`TheAcceptedOptionsAreExactlyThese` went red, which is the gate working.
|
||||
- **The session report could not tell "no hook ran" from "the hook came up late".** Both
|
||||
produce N/A and the same wording, and against Cyberpunk 2077 it said *"no upscaler hook
|
||||
ran"* while the hook was live for 97% of a 10,169-present session — feature hooks install
|
||||
lazily on a 1 Hz watchdog, and the consumer requires the bit on *every* record. The host now
|
||||
prints `hooksInstalledMask`, `apiMask`, `rtTier`, the per-bit record counts, and the modal
|
||||
raw `renderW/H` / `quality` / `upscaler`, so a partial count reads as *came up mid-session*
|
||||
and a verification run can be checked against the game's own settings file.
|
||||
|
||||
- **`upscalerQuality` gets a real preset, and `sl_dlss.h` is vendored with its consumer** —
|
||||
the last piece of `docs/HANDOFF.md` item 2b that could be built. The same bounded `inputs`
|
||||
walk now also matches `sl::DLSSOptions` and reads `mode`.
|
||||
- **Vendored the way the process requires, not approximately.** Upstream
|
||||
`NVIDIA-RTX/Streamline@main`, 8,489 bytes, **CRLF preserved**,
|
||||
`git hash-object 3aac47be62c9322aef119b88926602d37655d3ed`. Its include closure is
|
||||
**empty** — verified on the upstream file — so it adds no other header. None of
|
||||
`18_GPU_VENDOR_APIS` §Checklist step 2's four needles appear in it, so step 1 applies and
|
||||
step 3 is unreachable. Notices, the vendoring README and `17_HOOK_ENGINE` are corrected in
|
||||
the same commit: nine headers → ten.
|
||||
- **`DLSSMode::eOff` is 0, and `upscalerQuality` reserves 0 for "nobody looked."** Storing
|
||||
the vendor enum verbatim would make *"the title turned DLSS off"* and *"no hook ran"* the
|
||||
same byte — and 0 decodes as NGX MaxPerf, i.e. it would publish **"DLSS Performance"** as
|
||||
a measurement. `QualityFromMode` maps `eOff` and anything at or beyond `eCount` to `0xFF`.
|
||||
**Exactly the collision `D3D12_RAYTRACING_TIER_NOT_SUPPORTED` had against `rtTier`**, in a
|
||||
different vendor's enum, resolved the same way: at the writer, while the two are still
|
||||
distinguishable.
|
||||
- Asserted **exhaustively** rather than by example: no `DLSSMode` value, in range or out,
|
||||
may map to 0. A single mapping mistake publishes a wrong preset rather than an absence.
|
||||
- The walk no longer returns on its first hit. Extent and quality arrive in **different**
|
||||
structures and a title may chain them in either order, so an early return made quality
|
||||
depend on chain order — a property of the title, not of what it is doing.
|
||||
|
||||
|
||||
- **The LOCAL tags too — `slEvaluateFeature`'s `inputs` walk, hardened against input a title
|
||||
should never send.** `sl_core_api.h:258` is explicit that buffer tags passed to
|
||||
`slEvaluateFeature` are *"local"* and *"do NOT interact with same tags sent in the global
|
||||
scope using slSetTag API"*. The two are alternative integration styles, not layers, so a
|
||||
locally-tagging title yields nothing from the `slSetTag` hook and vice versa. Both are now
|
||||
read; the local one wins when present, because it is scoped to the evaluation rather than to
|
||||
the viewport and cannot be older than the frame being measured.
|
||||
- **In a header, `fl_sl_inputs.h`, precisely so it can be tested without a game.** Every
|
||||
branch dereferences caller-supplied pointers, and a fault lands in `FL_HOOK_GUARD` and
|
||||
burns one of the three that self-disable the Overlay — so a malformed input that faults is
|
||||
a **bug**, not degradation. `ctest fl_sl_inputs` drives 12 shapes in microseconds: null
|
||||
array, zero count, null element mid-array, wrong buffer type, wrong struct GUID,
|
||||
`structVersion` below `kStructVersion1`, whole-resource extent, a tag reached through
|
||||
`next`, a **self-referential** `next`, a **two-node cycle**, and a `numInputs` of
|
||||
`0xFFFFFFFF`.
|
||||
- **The cycle handling is the depth cap, and that is deliberate**: a visited-set would
|
||||
allocate, which a hook path may not. A cycle is worse than a fault — no exception, no
|
||||
self-disable, just a frozen game with our DLL in it.
|
||||
- **What the input cap does not buy, stated rather than implied.** It turns
|
||||
`numInputs = 4 billion` into 32 reads. It does **not** protect against a count of 5 with a
|
||||
2-element array: nothing in the ABI carries the allocation's length, so that direction is
|
||||
unprotectable from here. Same for a struct whose GUID matches but whose allocation is
|
||||
short. Both are the vendor's contract to keep, and both are written down.
|
||||
|
||||
- **`FL_MEASURED_UPSCALER_PARAMS` gets its first producer: render resolution, from the global
|
||||
resource tags** — `docs/HANDOFF.md` item 2b, and one of the five values P0 exit criterion 1
|
||||
names. A second inventory row detours `sl.interposer.dll!slSetTag`, reads the
|
||||
`kBufferTypeScalingInputColor` extent, and publishes `renderW/H`.
|
||||
- **`slSetTag` was scheduled for deferral and is included instead**, on measured grounds:
|
||||
`sl_core_api.h` documents the local tags in `slEvaluateFeature`'s `inputs` as merely
|
||||
*allowed* — *"they do NOT interact with same tags sent in the global scope"* — and only
|
||||
**four of the ten** Streamline titles installed here route DLSS super-resolution through
|
||||
Streamline at all. An inputs-only producer could have shipped with a hit rate of zero.
|
||||
- **The installer had to be restructured first, and it was a latent mis-bind.** The
|
||||
expansion over `FL_HOOK_INVENTORY` ignored the `family` column, stopped at the first row
|
||||
that resolved, and hooked it with `Hook_SlEvaluateFeature`. Correct with one row; with two
|
||||
it would have detoured `slSetTag` with a body that reads argument 1 as a feature id. Each
|
||||
row now carries its own detour, family bit and latch, and a row whose family has no detour
|
||||
installs **nothing** rather than borrowing a neighbour's. The install-after-stop guard is
|
||||
factored out of the single installer for the same reason.
|
||||
- **Two conditions to publish, and the second is the one that is easy to drop:** the params
|
||||
hook live, **and** an evaluation seen *this frame*. A tag is viewport state that outlives a
|
||||
frame, so publishing on the tag alone would report a render resolution for every frame
|
||||
after a title stopped upscaling — stale state dressed as a measurement.
|
||||
- `upscalerQuality` is **`0xFF`, never 0** — 0 is NGX MaxPerf, a real preset, so it would
|
||||
publish "DLSS Performance" as a measurement. `upscalerSharpness` is `0xFF` **permanently**:
|
||||
`DLSSOptions::sharpness` is deprecated as unsupported and `optimalSharpness` is
|
||||
Streamline's recommendation, not what the title applied.
|
||||
- **`claimedParams == 0` is inverted, not deleted** — that was the honest assertion while
|
||||
`renderW/H` had no source, and it is the line a reviewer should see change. It now asserts
|
||||
the **exact** tagged extent, the honesty invariant on every claiming record, and the
|
||||
reverse direction (a value set while the bit is clear).
|
||||
- Two fixture bugs the test found rather than reasoning: tagging **once** at startup landed
|
||||
before injection and left the bit set on **0 of 43** records — and `eValidUntilPresent`
|
||||
means a real title re-tags every frame anyway, so tagging once was simply wrong about the
|
||||
vendor contract. And a floor of `> size - 3` hid a real 6-record window where identity was
|
||||
live and params was not; the drain now waits for **both** families and asserts equality.
|
||||
- Proved red by canary: hardcoding a plausible 1920×1080 trips `wrongExtent` on all 40
|
||||
records, and it compiles.
|
||||
- No `#pragma warning` for C4996 on the deprecated `slSetTag`, and that is measured:
|
||||
`/std:c++20` **without** `/Zc:__cplusplus` makes MSVC report `199711L`, so the
|
||||
`#if __cplusplus >= 201402L` guard on the attribute never opens. A pragma would suppress a
|
||||
warning that is not emitted. The condition that would change it is recorded at the
|
||||
declaration.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **The Overlay would hook a Streamline module of the wrong generation, and read its
|
||||
arguments through the wrong signature.** The inventory scopes `slEvaluateFeature` to
|
||||
`sl.interposer.dll` — correct, and not enough. **The Witcher 3 ships that module at
|
||||
1.5.6**, a different API generation: it exports `slInit`, `slEvaluateFeature`, `slSetTag`
|
||||
and `slShutdown` so every name check passes, plus `slGetHooks`, `slIsFeatureEnabled` and
|
||||
`slSetFeatureConstants` which Streamline 2 does not have, and **none** of
|
||||
`slSetD3DDevice` / `slIsFeatureLoaded` / `slGetNewFrameToken`.
|
||||
- **The name survived the version bump and the signature did not**, which is why no gate
|
||||
saw it. `docs/vendor-exports.json` records one copy per module *name*, so
|
||||
`hookinventory-check` Pass A resolves against one machine's 2.7.4 and says nothing about
|
||||
a 1.5.6 in a game. A detour typed with SL2's `PFun_slEvaluateFeature`, called with SL1's
|
||||
argument list, reads argument 1 as a feature id when it is not one — a **wrong upscaler
|
||||
name**, not a crash, which `17_HOOK_ENGINE` calls the highest false-confidence risk in
|
||||
the spike.
|
||||
- `ResolveScoped` now refuses a `sl.interposer.dll` that does not export the three
|
||||
SL2-only entry points. No hook is installed, `FL_HOOK_UPSCALER_IDENTITY` is never
|
||||
published, and the record says `FL_UPSCALER_NOT_REPORTED` — true, rather than a guess.
|
||||
- **Scoped to the interposer by name, and the first version got that wrong.** Those three
|
||||
are *interposer* exports; a real `sl.common.dll` is a plugin and exports none of them, so
|
||||
an `sl.*` prefix test refused modules whose generation it had no business judging. The
|
||||
existing decoy fixture caught it.
|
||||
- New fixture `stub_sl_interposer_v1.cpp` — right module name, right symbol name, SL1 ABI —
|
||||
and `ctest fl_sl_abi_guard`. It is the complement of the decoy: scoping catches a wrong
|
||||
module *name*, and cannot see a wrong *signature*. Its own ctest and its own process,
|
||||
because both fixtures are called `sl.interposer.dll` and `GetModuleHandleExW` resolves by
|
||||
name, so sharing one would have the two silently test each other.
|
||||
- Proved red by canary: neutering the check leaves exactly one assertion failing, and it
|
||||
compiles, so it is a canary rather than a build failure wearing one.
|
||||
- The SL2 stub gains the three markers, so it honestly looks like the generation it stands
|
||||
in for. Found because the guard correctly refused it otherwise.
|
||||
|
||||
### Added
|
||||
|
||||
- **`FlWriterState.rtTier` gets a producer, and the vendor enum it copies had a collision in
|
||||
it** — `docs/HANDOFF.md` queue item 4, the one conjunct that needs no hook. `ResolveApi`
|
||||
already obtained an `ID3D12Device*` on the first present of a D3D12 swapchain and released
|
||||
it three lines later without asking it anything; it now asks
|
||||
`CheckFeatureSupport(D3D12_FEATURE_D3D12_OPTIONS5)` first. No hook, no MinHook, no vtable —
|
||||
a capability query on a device DXGI handed us for a swapchain we were called on.
|
||||
- **`D3D12_RAYTRACING_TIER_NOT_SUPPORTED` is 0, and `rtTier`'s 0 already meant NOT
|
||||
QUERIED.** Storing the enum verbatim — the obvious implementation, and the one
|
||||
`fl_shm.h`'s own field comment described — would have published "nobody looked" about
|
||||
every non-RT device: the affirmative-negative collision layout v3 exists to prevent,
|
||||
reached by copying a vendor enum rather than by a guess. New `FlRtTier` carries three
|
||||
states: `NOT_QUERIED = 0`, `UNSUPPORTED = 1`, and the D3D12 value verbatim otherwise.
|
||||
- **Measured against the Windows SDK header rather than remembered:** `NOT_SUPPORTED = 0`,
|
||||
`TIER_1_0 = 10`, `TIER_1_1 = 11`, **`TIER_1_2 = 12`** — the enum is already "tier ×10", so
|
||||
nothing multiplies it and nothing names the individual tiers. A tier newer than the SDK
|
||||
this was built against arrives intact instead of being clamped to what the build knew.
|
||||
- **Both directions are asserted, in `ctest fl_guard`.** The D3D12 case asserts the field
|
||||
holds a legal `FlRtTier` value; the D3D11 case asserts it is exactly `NOT_QUERIED`,
|
||||
because a writer that stored `UNSUPPORTED` unconditionally would pass the first on its
|
||||
own. What the D3D12 case does **not** assert is *which* tier: the fixture's device is
|
||||
WARP, and whether WARP supports DXR is the open question `HANDOFF` item 4 says to check
|
||||
rather than assume — so the value is `CAPTURE`d and the test records the answer instead
|
||||
of depending on it.
|
||||
- **It does not make RT reachable yet, and the consumer comment now says so precisely.**
|
||||
`MeasuredFacts.RayTracingOf`'s two conjuncts both have producers now, but
|
||||
`FL_MEASURED_RT` still has none, so RT is `N/A` on every session. The gap moved; it did
|
||||
not close.
|
||||
- **`hookinventory-check` grows a third pass, over the one failure the other two cannot
|
||||
see** — and the document that already claimed this pass existed is corrected in the same
|
||||
commit. Passes A and B are source checks: they see what the Overlay *resolves*. Neither
|
||||
sees what it *links*. Taking the address of an `SL_API` declaration in evaluated code makes
|
||||
`sl.interposer.dll` a **load-time dependency** of `FrameLedger.Overlay.dll`, which then
|
||||
fails to load in every game that ships no Streamline — in the loader, before `DllMain`,
|
||||
with no message anywhere. **Pass C reads the binary's own dependency list** and fails on
|
||||
`^(sl\.|_?nvngx|libxess|ffx_|amd_fidelityfx)`.
|
||||
- **`src/native/third_party/streamline/README.md` had asserted this gate since
|
||||
2026-08-09.** It did not exist: the script's only mention of `dumpbin` was a comment
|
||||
about a different tool. Found by an audit that went looking for the code instead of
|
||||
trusting the sentence — the shape this project keeps hitting, and worse here because the
|
||||
failure Pass C catches has no symptom to notice.
|
||||
- **It refuses rather than passes whenever it cannot look.** A zero-length import list is a
|
||||
failure, not a clean result — every way that parse can break produces the same empty list
|
||||
as a binary with no vendor imports. The list must also contain `kernel32.dll` before any
|
||||
verdict is formed, the same discrimination rule the oracle probe already follows.
|
||||
- **It runs only under `-RequireBinaries`.** The first version read whatever binary was in
|
||||
the build tree, so `check -SkipNative` printed a skip line *and* ran the pass anyway,
|
||||
against an artefact the run did not produce. Reporting on the wrong binary is worse than
|
||||
saying nothing.
|
||||
- Proven on real PEs as well as fixtures: out of `AlanWake2.exe`'s 47 imports and
|
||||
`Cyberpunk2077.exe`'s 36, it names exactly `sl.interposer.dll` and — for Cyberpunk —
|
||||
`libxess.dll`, `libxess_fg.dll`, `ffx_fsr3_x64.dll`, `ffx_backend_dx12_x64.dll`, and
|
||||
nothing else. Self-test is 17 cases, both directions, including that the match is
|
||||
anchored so an innocent name merely *containing* a vendor prefix passes.
|
||||
- Pass B's stray-literal sweep gains `xefg[A-Z]`, which `xess[A-Z]` does not cover:
|
||||
`libxess_fg.dll`'s 31 measured exports include 28 `xefgSwapChain*` names and no `xess*`
|
||||
name at all. Widened before the FG hooks land rather than after.
|
||||
- **§H5 case 3 gets an answer, and a second finding cost a crash to get** —
|
||||
`fl-probe-interposer` reported INCONCLUSIVE because it never called `slInit`, blaming a
|
||||
licence question over `sl::Preferences`. #64 vendored Streamline under MIT and removed that
|
||||
blocker; the probe now runs the sequence a real title runs — `slInit` →
|
||||
`D3D12CreateDevice` **through the interposer** → `slSetD3DDevice` — with every entry point
|
||||
resolved by `GetProcAddress`, never linked.
|
||||
- **MEASURED: the swapchain class is not ours.** With `slInit` returning `eOk`, the
|
||||
interposer hands back a swapchain whose vtable sits inside `sl.interposer.dll` while
|
||||
`dxgi.dll`'s own route yields `dxgi.dll`'s. Reproduced on Alan Wake 2 (SL 2.7.0) and
|
||||
Cyberpunk 2077 (SL 2.7.1). **It does not follow that we miss the present** — §H5's
|
||||
`--probe-proxy` result stands, a forwarding proxy is caught one layer down — and the
|
||||
probe says so rather than converting a premise into a verdict.
|
||||
- **The Witcher 3 ships Streamline 1.5.6, and it crashed the probe.** A different API
|
||||
generation: `slGetHooks`, `slIsFeatureEnabled`, `slSetFeatureConstants`, and **no**
|
||||
`slSetD3DDevice` or `slIsFeatureLoaded`. `slInit` exists in both with a different
|
||||
`sl::Preferences` layout, so the vendored 2.x struct access-violates. Now version-guarded
|
||||
on the SL2-only exports, skipping with a reason.
|
||||
- **That reaches the hook inventory.** `docs/vendor-exports.json` records one copy per
|
||||
module *name*, so its `sl.interposer.dll` is one machine's 2.7.4 and says nothing about a
|
||||
1.5.6 a title ships. Pass A would accept `slEvaluateFeature` against such a title — the
|
||||
name exists in both generations — while the **signature** differs. Today's hook reads
|
||||
only `feature` and is probably unharmed; **item 2b's `inputs`/`numInputs` walk is not**,
|
||||
and needs its own version guard before dereferencing anything.
|
||||
- **The engagement read was a race first.** Plugin load is deferred: the first run reported
|
||||
both features unloaded while Streamline's own log — flushed after ours — showed six
|
||||
plugins verifying. Now polled for the state, bounded by a wall clock.
|
||||
- `ctest fl_vtable_identity_control` (Part 1, the control) is unchanged and still runs on
|
||||
CI; the probe imports `d3d11.dll` and `KERNEL32.dll` only, so linking Streamline could
|
||||
not have broken it.
|
||||
|
||||
- **The upscaler identity hook, and a fixture that can prove a wrong symbol name wrong** —
|
||||
`docs/HANDOFF.md` queue item 2. `FrameLedger.Overlay` gains **module-scoped symbol
|
||||
resolution** (it had none: `GetProcAddress`/`GetModuleHandle` appeared nowhere in the
|
||||
target) and one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, installed
|
||||
lazily by the existing 1 Hz watchdog so a title that loads Streamline at device
|
||||
creation is still caught without a `LoadLibrary` hook — which keeps §S6 separable.
|
||||
- **`FlWriterState.hooksInstalledMask` gets its first producer anywhere in the tree.**
|
||||
It had none — not even `FL_HOOK_PRESENT`, which the present hook was always entitled
|
||||
to — and `MeasuredFacts.RayTracingOf` already said so in its own comment while
|
||||
reaching `N/A` on every session because of it.
|
||||
- **Never `FL_UPSCALER_NONE`.** A Streamline-only writer cannot see FFX, XeSS or
|
||||
NGX-direct, and `NONE` is the only one of the three states `fl_shm.h` allows to be
|
||||
aggregated as a negative. An unrecognised feature id reports `UNKNOWN` — "a hook ran
|
||||
and could not identify what it saw" — which is a state this codebase could not
|
||||
previously produce. A ctest drives a target evaluating `0xF00D` to prove it.
|
||||
- **Ray Reconstruction's OBSERVED bit is gated on having seen an SL evaluation *this
|
||||
frame*, not on the hook being installed.** Found by an adversarial refuter over the
|
||||
design: the consumer returns `Tri.No` when OBSERVED is set on every record and no
|
||||
record carries the fact bit, so a writer setting OBSERVED whenever the hook was live
|
||||
would publish **"Ray Reconstruction: No" on an NGX-direct DLSS-RR title**, which
|
||||
never calls `slEvaluateFeature` at all. The honest-looking choice was the wrong one.
|
||||
- **`FL_MEASURED_UPSCALER_PARAMS` is deliberately unset, and the reason is a licence.**
|
||||
`17_HOOK_ENGINE` recommended hooking `NVSDK_NGX_Parameter_SetUI` for quality and
|
||||
render size; that needs NGX declarations, and the NGX/DLSS SDK is the proprietary
|
||||
**NVIDIA RTX SDKs License** — verified upstream, hitting three of
|
||||
`18_GPU_VENDOR_APIS` §Checklist step 2's four needles — so step 3 forbids vendoring
|
||||
it **and** re-declaring it. The document recommended a path its own rule forbids and
|
||||
nothing had noticed, because no code had gone near it. Corrected in place.
|
||||
- **NVIDIA Streamline MIT headers vendored** at `src/native/third_party/streamline/` —
|
||||
the nine-file include closure of `sl.h`, one atomic commit with the licence copy, the
|
||||
notices row and both of `license-check.ps1`'s arrays. It buys the vendor's own
|
||||
`PFun_slEvaluateFeature`: five parameters, every one integer-class, so **nothing
|
||||
travels in XMM** — the exact residual hazard nobody could rule out while the signature
|
||||
was a guess, and a guess wrong by one argument corrupts the stack *inside the original
|
||||
function*, where `FL_HOOK_GUARD`'s `__try` cannot reach. `sl_nvperf.h` is excluded (the
|
||||
same `license.txt` carries a second, proprietary NSight Perf block naming it) and all
|
||||
of `external/` is excluded (upstream's `external/ngx-sdk` is the RTX licence, so a
|
||||
recursive copy does the forbidden thing by default). `license-check` asserts all three,
|
||||
proven red in four directions. This also answers the question `spike-notes` §5 recorded
|
||||
as open: §H5 case 3 was *"blocked on a licence decision, not on hardware"*, and the
|
||||
decision is taken.
|
||||
- **`tools/hookinventory-check.ps1`** — every vendor symbol the Overlay resolves by name
|
||||
must exist, **in the module it takes it from**, in `docs/vendor-exports.json`. Wired
|
||||
into `build.ps1` in both halves. **Prevention: it fixed nothing**, and its own docstring
|
||||
says so, because a gate whose write-up implies it caught something cannot be audited
|
||||
later. Five red cases proven; the load-bearing one is an **oracle-discrimination
|
||||
canary that runs before any verdict**, since every failure mode of such a lookup
|
||||
produces the same answer as "absent".
|
||||
|
||||
- **The params half is designed and not built**, and the design is in `docs/HANDOFF.md` §2b
|
||||
rather than here, because it is a sequencing decision and not a change. Recorded because the
|
||||
panel **rejected the route the documents make obvious**: hooking `slGetFeatureFunction` and
|
||||
MinHook-patching the returned `slDLSSSetOptions` would need an "indirect" inventory class that
|
||||
is an unconditional escape hatch from `hookinventory-check` (its oracle would be "a `PFun_*`
|
||||
exists in a vendored header", and `sl_core_api.h:63` declares one for a symbol **zero measured
|
||||
modules export**); it would reopen the install-after-stop window; MinHook has no function-length
|
||||
oracle for a runtime-returned address, so a short thunk gets patched into its neighbour inside
|
||||
vendor code where `FL_HOOK_GUARD` cannot reach; `GetModuleHandleExW` in a detour takes the
|
||||
loader lock on the game's thread; and it structurally misses the game's FIRST
|
||||
`slDLSSSetOptions` call, which for a benchmark configured before launch is often the only one.
|
||||
The chosen route extends the hook the Overlay already owns — a bounded walk of
|
||||
`slEvaluateFeature`'s `inputs` chain, which it already receives and ignores.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **A failed `REQUIRE` terminated the whole native test binary, hiding every test after
|
||||
it.** Catch2 compiled itself with `CATCH_CONFIG_DISABLE_EXCEPTIONS`: the top-level
|
||||
CMakeLists strips `/EHsc` from `CMAKE_CXX_FLAGS` deliberately, and `tests/CMakeLists.txt`
|
||||
re-added it **only to the test binaries**, never to the Catch2 library that decides the
|
||||
mode — a comment whose premise was right and whose effect was not. On a box where WARP's
|
||||
D3D12 path is broken this silently removed the end-to-end injection cases from `ctest`,
|
||||
**including the honesty assertion §S29(a) names as the merge gate's coverage**, which
|
||||
passes when run alone. `ctest` reported "1 test failed" where the truth was "and 2 never
|
||||
ran". Recovered **70 test cases and 1051 assertions**.
|
||||
- **`MeasuredFacts.IsHonest` compared `measuredMask` against a hardcoded constant**, which
|
||||
was correct for a present-only writer and became wrong the moment a feature hook landed:
|
||||
an honest record claiming `FL_MEASURED_UPSCALER` counted as a violation. Widening the
|
||||
constant would have made the check a statement about one build rather than about
|
||||
honesty, so entitlement is now **derived from `hooksInstalledMask`** — a writer may
|
||||
claim a measurement only where it installed a hook capable of taking it — plus the
|
||||
reverse direction that was missing, a *value* set while its mask bit is clear.
|
||||
- **`docs/12_BUILD.md` said the NVAPI SDK "is not vendored yet"** and that
|
||||
`src/native/third_party/` held only `CMakeLists.txt` and `vulkan-headers`. Both false
|
||||
since #55. That sentence was itself a correction of the opposite error, so this file has
|
||||
now been wrong in both directions about one fact — `legal/` is gated bidirectionally and
|
||||
caught its own version, `docs/` is not.
|
||||
- **`docs/HANDOFF.md` item 2 named `NVSDK_NGX_EvaluateFeature`, which no measured module
|
||||
exports**, and said four modules where `NVSDK_NGX_D3D12_EvaluateFeature` has **seven**.
|
||||
The argument survived both errors; the data was wrong in the bullet whose subject is
|
||||
that a wrong symbol name degrades silently.
|
||||
|
||||
- **The consent store, and the first production driver of the guard loop** — `docs/HANDOFF.md`
|
||||
queue item 1. `HookedCaptureGate`'s three inputs (`hook_enabled`, `hook_consent_at`,
|
||||
`hook_blocked_reason`) have a real source for the first time, and
|
||||
`FlControlBlock.guardTicks` is now advanced by a **non-test binary**. Both ends of that
|
||||
field existed and were tested since #46/#50; only the loop was missing, and a missing loop
|
||||
reads as a missing subsystem.
|
||||
- **`FrameLedger.CaptureHost` is a separate project that nothing publishes**, and
|
||||
`tools/package-closure-check.ps1` is what keeps that true rather than remembered. §S27 was
|
||||
closed on the strength of there being no injecting entry point on any shipped binary; the
|
||||
host **is** one, so what keeps §S27 closed is its absence from the package. The gate walks
|
||||
the transitive `ProjectReference` closure of the two roots `12_BUILD` publishes and names
|
||||
the edge that reached anything else. **Proven:** a reference from `FrameLedger.Agent` leaves
|
||||
the build green and turns the gate red with `FrameLedger.Agent → FrameLedger.CaptureHost`.
|
||||
Both halves are wired — the self-test (5 cases, 4 RED) **and** the live pass, because a gate
|
||||
wired self-test-only never reads the repository, which is the defect it exists to prevent.
|
||||
- **`HookRequest` can no longer be synthesised, and that is what actually closed the hole.**
|
||||
It was a `record` with `required`/`init` members, so
|
||||
`new HookRequest { HookEnabled = true, ConsentedAt = DateTimeOffset.UtcNow }` passed every
|
||||
check in the gate and reached `GuardedInjectAsync` — **verbatim the expression §S27 named and
|
||||
rejected**. A store, a record and a provenance flag do not close that; they add an honest path
|
||||
beside it. It is now get-only with a private constructor and one factory, so the dishonest
|
||||
path is a compile error rather than a discouraged idiom. Found by a safety refuter over the
|
||||
design, before any of it was built.
|
||||
- **`GameConsentRecord.Stored` is `internal`**, because `FrameLedger.Domain` is inside both
|
||||
publish closures: a public minting factory there would be a blessed, *shipped* API for
|
||||
producing consent nobody gave, and the closure gate cannot see it — it walks project
|
||||
references, and Domain legitimately belongs to both. The `InternalsVisibleTo` list is the
|
||||
reviewable artifact; a test asserts the public factory does not exist.
|
||||
- **An acknowledgement cannot clear a block.** `RecordOperatorAcknowledgementAsync` takes an
|
||||
`OperatorAcknowledgement`, which carries neither `BlockedReason` nor `PreScanUnverified`, so
|
||||
the store's merge is their only source. Taking a whole record — the first shape — meant
|
||||
`consent grant` on a title the pre-scan had blocked would write `BlockedReason = null` and
|
||||
the gate's `PreviouslyBlocked` branch would stop firing: the "I understand, continue anyway"
|
||||
button CLAUDE.md rule 2 forbids, arrived at by omission.
|
||||
- **The pre-scan's third state gets its own field.** `05_DETECTION` makes "could not verify"
|
||||
neither a hit nor a pass, while `hook_blocked_reason` is two-state by definition. It is
|
||||
refused in the loop, never mapped to `PreviouslyBlocked` and never cleared — routing it
|
||||
through the gate would force one of the two collapses that document forbids.
|
||||
- **A consent record carries a disclosure provenance and a wording version**, neither of which
|
||||
`06_DATA_MODEL` has. A bare timestamp cannot say whether anything was disclosed, and
|
||||
`ConsentProvenance.NotRecorded = 0` means a record nobody filled in refuses. **FR-2.1's value
|
||||
is deliberately not declared**: no `.resx` exists anywhere in this tree, `09_I18N` reviews
|
||||
`Safety_*` keys as legal text, and a declared-but-producerless value is the "reads as
|
||||
sanctioned" shape §S29(c) was raised for. The version is carried from the *first* record
|
||||
because it cannot be added later — retrofitting one means treating unversioned consent as
|
||||
either current or stale, and both are wrong about some record.
|
||||
- **The command surface has no `--pid`, `--payload`, `--force`, `--yes` or `--diag`**, and a
|
||||
test pins it. §S27's gap was a user-named pid on a binary with no consent record; resolving
|
||||
the target from the same normalised path the record is keyed on makes "consent for A,
|
||||
injection at B" inexpressible rather than discouraged. Two processes of one image refuse as
|
||||
ambiguous rather than picking one.
|
||||
- **`consent grant` refuses redirected stdin**, so no script can acknowledge on a human's
|
||||
behalf, and the disclosure states in its first line that it is *not* FR-2.1 consent.
|
||||
|
||||
- **Session end has a signal (§S29(e) closed).** A held process handle, opened before the
|
||||
injection and never re-resolved — pids recycle and the ring is named after one.
|
||||
- **It was first closed on a handle that was never held, and the correction is the
|
||||
interesting part.** The first version used `Process.GetProcessById` and read
|
||||
`HasExited`. **Measured** on .NET 10.0.10 by a probe over the live object:
|
||||
`_haveProcessHandle == false` and `_processHandle == null` both after construction and
|
||||
after reading `HasExited` — `GetProcessById` opens nothing and `HasExited` opens a
|
||||
transient handle and releases it in its own `finally`. Three source comments, a ledger
|
||||
entry and a changelog line all asserted the pid was pinned; nothing checked it, and it
|
||||
was not. `Infrastructure.Io.HeldProcessHandle` now opens `SYNCHRONIZE |
|
||||
PROCESS_QUERY_LIMITED_INFORMATION` and keeps the `SafeProcessHandle`, a pid that
|
||||
cannot be opened is a refusal (`TargetCannotBePinned`) rather than a session, and the
|
||||
test asserts the *property* — it answers about a fully exited process at a pid
|
||||
`Process.GetProcessById` will not resolve, which nothing holding a handle-less object
|
||||
can do. The ninth entry for "measure Windows APIs, don't trust them", and the first
|
||||
where the API misled by doing **less** than its name implies.
|
||||
`SessionEndClassifier` takes no elapsed-time parameter, so **a frozen `writeIndex` can never
|
||||
end a session**, which is the whole of the defect: `ShmRingReader` holds the section open, so
|
||||
an exited game leaves `status` `READY` and `writeIndex` frozen, byte-for-byte a loading screen.
|
||||
§S26 made it strictly worse by dropping `DXGI_PRESENT_TEST`, removing the accidental heartbeat
|
||||
an occluded title used to emit. It also separates the two stops the mapping cannot: `StopObserving`
|
||||
stores `FL_STATUS_UNHOOKED` for the safety stop **and** for supervision loss, so only the side
|
||||
that caused one knows which — and `legal/DISCLAIMER.md` §2 discloses them differently.
|
||||
|
||||
- **A throwaway consumer**: `measuredMask` → rule 7 tri-state, segmentation, and the one number a
|
||||
present-only writer may publish. In the unshipped host, deliberately not in
|
||||
`FrameLedger.Domain.Metrics.*` — P2 owns the real calculators and `coverage-gate` carries a
|
||||
separate 95% floor for that namespace.
|
||||
- **Segmentation is stream-first, settings-second**, and reversing it manufactures a segment per
|
||||
present. Two axes exist and neither document mentions the other: `03_METRICS` §Upscaling
|
||||
splits on a settings change, `fl_shm.h` says the Agent "segments by [`swapchainId`] and reports
|
||||
the dominant stream". One vtable patch sees every swapchain in the process, so a title with a
|
||||
UI or video swapchain interleaves two streams in one ring.
|
||||
- **`frameIndex` is process-global, so it cannot detect a gap within a stream.** The first design
|
||||
excluded any interval whose index did not advance by one — which would have excluded *every*
|
||||
interval in any multi-swapchain title and reported no duration at all, including for Displayed
|
||||
FPS. `dllmain.cpp` assigns `g_frameIndex++` four lines before `swapchainId`; the overflow
|
||||
harness interleaves 17, so the dominant stream's indices step by ~17. Found by a feasibility
|
||||
refuter over the design.
|
||||
- Everything unmeasurable is `null` or `N/A` with **no fallback**: `fg_factor` is never `1.0`,
|
||||
`fgMode` is never `"none"`, the upscale ratio is not computed at all (`renderW/H` are 0), and
|
||||
the retired `FlUpscaler` value 2 is never decoded as `dlss_rr` — `03_METRICS` §Upscaling
|
||||
listed it as an upscaler value until this PR, which removes it and records why. The
|
||||
renderer is asserted too: rule 6 is a rule about
|
||||
*showing* a single inflated number, and a test matches the rendered text against `×N`.
|
||||
|
||||
- **`--present-interval-ms` on `hook-harness`**, because one test could not be written without it.
|
||||
The Agent's drop accounting fires when the writer laps the reader — 8192 records — and at the
|
||||
default ~120/s that is **68 seconds** of a reader deliberately not draining, so the branch
|
||||
`04_CAPTURE` calls "the Agent stalled for over ~16 s" had never run against the real Overlay in
|
||||
either language. Measured: uncapped, the harness does **171,636 presents in 3 s**, so the ring
|
||||
laps in well under a second.
|
||||
|
||||
### Changed
|
||||
|
||||
- **`HookedCaptureGate.ShouldUnhookAsync` is deleted (§S29(c) closed).** It was a second in-session
|
||||
re-scan that published no tick and did not latch — the two properties `GuardSupervisor` exists to
|
||||
guarantee — and it was the *more discoverable* of the two, because a drain loop already holds the
|
||||
gate. Its polarity was inverted from the survivor's, too: `true` meant STOP where
|
||||
`ScanOnceAsync`'s `true` means MAY CONTINUE. Deleted rather than routed: it had **zero production
|
||||
callers**, its body was strictly weaker than `ScanOnceAsync`, and routing would have given the
|
||||
gate per-session state on a class whose contract is that it "adds no judgement of its own".
|
||||
- **The two Facts that covered it are replaced by one that is stronger.** They asserted the
|
||||
boolean and never the tick or the latch, so they certified the API as sanctioned while saying
|
||||
nothing about what was wrong with it. `TheGateExposesNoSecondInSessionRescanPath` pins the
|
||||
gate's public instance surface to exactly `{StartAsync}` and is red on unmodified `main`.
|
||||
|
||||
- **`ShmDrainIntegrationTests`' honesty helper is split.** `AssertRecordsAreHonest` mixed
|
||||
fixture-independent invariants with assertions about attach *timing* and a single swapchain, and
|
||||
a fixture that deliberately stalls the reader satisfies neither — reusing it produced a red test
|
||||
whose failure message was about frame indices, indistinguishable from a real regression.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`ShmRingReader.SetPaused` had no test at all.** Both halves of `pauseRequested` existed —
|
||||
`MayObserve()` has read the flag since #46 — and the managed writer had never been driven in
|
||||
either direction. Now both: a merge-gated round trip proving the byte lands at
|
||||
`ControlOffset + 0` and that `unhookRequested` four bytes away is untouched, plus an integration
|
||||
case proving the Overlay acts on it, **ticking throughout**, because the defect #46 fixed only
|
||||
appeared on frames where `guardTicks` had changed. A pause is invisible in the record stream —
|
||||
`MayObserve()` returns false before `frameIndex` is assigned — which the consumer must not read
|
||||
as one enormous frame time.
|
||||
|
||||
- **`ShmHandshakeValidator` never compared `handshake.Pid`**, so a ring left behind by a finished
|
||||
session, or one under a recycled pid, validated `Ok` on build id, layout and capacity alone.
|
||||
Not an ABI change: `ShmAttachRefusal` is managed-only with no native mirror.
|
||||
|
||||
- `NativeAntiCheatGuard`'s §S21 rationale was attached to `NativeCheckRules` by two stacked
|
||||
`<summary>` blocks while `NativeRulesFilePath`, which it describes, had none.
|
||||
|
||||
### A fifth rate-sized budget, and a correction to what I said about WARP
|
||||
|
||||
`TheGuardInjectsTheOverlayAndTheReaderDrainsRealFrames` — pre-existing, from #51 — drained for a
|
||||
fixed twelve iterations and then asserted a floor sized on "the harness presents at ~120/s". It waits
|
||||
for the record count now, bounded by a wall clock, and gained an assertion that the loop supervised
|
||||
more than once so the shortened path cannot pass vacuously. **This is explicitly not presented as the
|
||||
fix for the one failure observed**: it failed once in twelve runs with its message uncaptured, and
|
||||
after #62 — two rounds of the wrong remedy — the rule is that a defect class is a hypothesis about
|
||||
the next failure, not a diagnosis of it. The budget was removed because that is defensible on its own
|
||||
terms. Ten consecutive full runs clean.
|
||||
|
||||
**And the WARP note in `HANDOFF` §Traps said "a reboot clears it", which is false.** That sentence was
|
||||
written on plausibility and never tested. The machine rebooted at 13:58 and the identical failure
|
||||
reproduced at 14:17. Measured properly this time: `D3D12CreateDevice` on the WARP adapter returns
|
||||
`DXGI_ERROR_DRIVER_INTERNAL_ERROR` at **every** valid feature level, while `D3D11CreateDevice` on the
|
||||
**same adapter object** succeeds at FL 11_0 and D3D12 on the RTX 5080 succeeds; `d3d10warp.dll`,
|
||||
`d3d12.dll` and `D3D12Core.dll` all match the OS build (Windows 11 Insider 26300/29639), so nothing is
|
||||
corrupt. It reads as an Insider-build regression in WARP's D3D12 path and it is persistent. CI is not
|
||||
an Insider build and passes the same suite, so `main` is unaffected — but the native suite has a hard
|
||||
dependency on WARP D3D12 that a dev box can lose on its own, which is now written down.
|
||||
|
||||
### A fourth failure that was not a race at all — an off-by-one wearing a flake's costume
|
||||
|
||||
`APausedSessionStopsRecordingAndResumesWhereItLeftOff` failed roughly one run in five, which is
|
||||
exactly what the three fixed above looked like. It was **`EstablishRecordingAsync`'s loop bound and
|
||||
its assertion disagreeing by one**: the loop ran while `seen < 10` and so exited at *exactly* 10,
|
||||
and the assertion demanded `> 10`. It passed only when a single drain happened to bring in eleven or
|
||||
more at once — so the timing decided whether the off-by-one was visible, and two rounds of budget
|
||||
tuning made it rarer without touching it. One constant now serves both.
|
||||
|
||||
**The lesson is the diagnosis, not the fix.** Having just repaired three genuine races, the fourth
|
||||
failure in the same file was assumed to be a fourth race, and it was treated with the remedy for the
|
||||
previous three. What settled it was reading the failure message instead of the pattern: *"Expected
|
||||
seen to be greater than 10 … but found 10"* names the defect exactly and took one run to obtain.
|
||||
|
||||
Swept alongside it, since the class was the thing under review: the pause test now waits for the
|
||||
writer to **settle** — two reads 100 ms apart with nothing between them — rather than assuming a
|
||||
fixed 250 ms covers a present already in flight, and it keeps ticking throughout, because the pause
|
||||
path is only reachable on a frame where `guardTicks` changed (the defect #46 fixed, and the reason
|
||||
this test exists). The resume-drain budget goes 1 s → 3 s for the contention reason.
|
||||
|
||||
Ten consecutive full runs clean afterwards.
|
||||
|
||||
### Three racy assertions that #60 merged, caught by the post-merge run
|
||||
|
||||
`docs/HANDOFF.md` says to run `./build.ps1 check` with no switches **after** every PR. This is what
|
||||
that found, and all three are the same shape: an assertion that reads a state once, at a moment when
|
||||
the state is legitimately still in transit.
|
||||
|
||||
- **`Status == Ready` read immediately after the first guard tick.** `InitThread` publishes
|
||||
`layoutVersion` at step 2 and sets `READY` at step 6 — after `InstallPresentHooks` creates a
|
||||
throwaway WARP device, tens of milliseconds. `TryAttach` succeeds as soon as `layoutVersion` lands
|
||||
and the host publishes its first tick immediately **by design**, because the Overlay's 65 s
|
||||
supervision clock starts at mapping publish. A tick and `INIT` are therefore a legitimate
|
||||
simultaneous state. Polled now, with `INIT` past the budget still failing — that is
|
||||
`WriterNeverInstalledHooks` and must not read as a passing session.
|
||||
- **`ApiMask` asserted as soon as `Status` became `Ready`.** "Hooked and recording" is two events:
|
||||
`apiMask` is set inside `FindOrAdd`, on the first present the hook actually *sees*, so `READY` with
|
||||
`apiMask == 0` is another legitimate window. Failed once in five full-suite runs and never once in
|
||||
six isolated ones — the signature of a window widened by contention.
|
||||
- **QPC ascending asserted across a deliberate lap, and it is unassertable in EITHER direction.**
|
||||
Measured both ways: under the full suite the drop test's first drained record came back ~148 ms
|
||||
*later* than the second; run alone the same batch was perfectly ascending. `Drain` resumes at
|
||||
`writeIndex - capacity`, the oldest survivor, and whether the writer has overwritten that slot when
|
||||
the copy arrives is a race decided in microseconds — the seqlock catches a tear *during* a copy, not
|
||||
a slot cleanly overwritten *before* it. Ascending qpc is a property of a reader that **kept up**, so
|
||||
it now lives only with the other attach-timing assertions. What matters downstream is enforced where
|
||||
it belongs: `MeasuredFacts` skips non-positive deltas, and `04_CAPTURE` requires a non-zero drop
|
||||
count to be surfaced as a session warning.
|
||||
|
||||
Six consecutive full runs clean afterwards. **Two native cases stay red on this machine for an
|
||||
unrelated reason**, recorded in `HANDOFF` §Traps: `D3D12CreateDevice(WARP)` returns
|
||||
`DXGI_ERROR_DRIVER_INTERNAL_ERROR` (0x887A0020) while the same call on the real adapter succeeds. CI
|
||||
runs the same suite on WARP and passes, and nothing in #60 touches that path.
|
||||
|
||||
### What the adversarial review of this diff caught before it landed
|
||||
|
||||
An adversarial pass over the working tree raised 23 candidates; 17 survived a second agent told
|
||||
to refute them. Beyond the process handle above, the ones that were real defects rather than
|
||||
documentation drift:
|
||||
|
||||
- **"Could not read the executable" passed the fingerprint check instead of refusing.**
|
||||
`observed ?? record.Fingerprint` made `FromConsent`'s mismatch comparison compare the record
|
||||
against **itself**, so an unreadable binary decided as "this is the consented one" — the one
|
||||
polarity everything else here is built to avoid. Now `ExecutableUnreadable`.
|
||||
- **`Enum.TryParse` accepts numeric strings**, so `"provenance": "1"` in the consent file yielded
|
||||
`UnshippedHostOperator` and `"42"` an undeclared value cast to the enum — an end-run around the
|
||||
two-member count a test pins. The comment claimed the opposite in as many words. Now
|
||||
`Enum.IsDefined` plus an ordinal name comparison, with the numeric cases tested.
|
||||
- **An unreadable consent file silently cleared a persisted guard block.** "There is no file" and
|
||||
"I could not read the file" both produced an empty store, and every write is a
|
||||
read-modify-write over that — so the merge that carries `BlockedReason` forward carried nulls,
|
||||
and the write republished a file containing only the new entry, dropping every other game's
|
||||
record. The two outcomes are now distinct and an unreadable store refuses every write.
|
||||
- **A guard exception mid-session discarded every record already drained.** Not advancing the tick
|
||||
is correct and required; losing the session's data with the stack was neither. Now
|
||||
`SupervisionFaulted`, with the final drain still running — and the *first* scan still throws,
|
||||
because there is no session to preserve yet.
|
||||
- **`StreamSegmenter` cut a spurious 0×0 segment** when a stream's first records had no measured
|
||||
size: `w`/`h` were both the "no baseline yet" sentinel and a real resolution, so the split fired
|
||||
on the first measured record — cutting a segment on the writer's silence, which the surrounding
|
||||
comment forbids.
|
||||
- **`TargetResolver` narrowed to a false single match.** Its comment claimed skipping an unreadable
|
||||
process avoided that; skipping is what caused it, because `matches.Count == 1` could not tell
|
||||
"one candidate" from "one readable candidate and others invisible". Skips are counted now.
|
||||
- **`ConsentWriteOutcome.StaleFingerprint` had no producer** — a declared-but-producerless value,
|
||||
the shape this same PR invokes two files away to justify `ConsentProvenance` having no FR-2.1
|
||||
member. It is produced now, and only where it matters: a re-grant against a different binary
|
||||
cannot inherit an existing block, while an ordinary re-consent after a patch still works.
|
||||
- **Three of the new tests could not fail for the property they named.**
|
||||
`ATerminalAttachRefusalIsNotRetriedIntoATimeout` asserted only the final reason, which is
|
||||
identical whether the refusal returns immediately or is retried to the budget — it counts
|
||||
attempts now, and gained the green half. `TheFirstTickIsPublishedBeforeAnyDrain` recorded
|
||||
publishes and drains in two independent lists, so no ordering was observable — one ordered event
|
||||
list now. And the end-to-end refusal case called `File.Delete` on a path whose parent directory
|
||||
only exists once some test has written a record, so on a clean build output it threw and its
|
||||
verdict depended on which sibling ran first — in the very test whose comment says a test whose
|
||||
verdict depends on what ran before it is one this repository does not accept.
|
||||
|
||||
- **`docs/HANDOFF.md` — one file to pick the work up from, and it carries no status.**
|
||||
Sequencing, the decisions that live in no other file, and the traps that cost a wrong
|
||||
diagnosis rather than a build cycle. Status stays in `20_OPEN_QUESTIONS` §S24,
|
||||
`spike-notes`, `15_ROADMAP` and this file, and the handoff points at them.
|
||||
- **The rule is written into the file because the alternative is what keeps
|
||||
happening.** A handoff that summarises status becomes the next stale copy within a
|
||||
day — #45's note did, `15_ROADMAP`'s status block did, and `spike-notes` §8 went
|
||||
stale *in the same file* that was correcting an earlier stale claim. It also would
|
||||
have been a fifth statement of the gate's composition, which `rules-validate` now
|
||||
refuses in the shipped data.
|
||||
|
||||
- **Shared-memory layout v3: the zero value of every enum in the record is now "nobody
|
||||
said", not a fact.** `FL_SHM_LAYOUT_VERSION` 2 → 3, spent deliberately in the last window
|
||||
where it costs nothing — nothing has shipped and no user has a session, and after the
|
||||
first release the same edit is a SemVer MAJOR that makes the Agent refuse to attach and
|
||||
tell the user to restart the game.
|
||||
- **The generator of the defect, not four instances of it.** `FlFrameRecord rec{}`
|
||||
zero-initialises, so whatever 0 means is what a writer publishes when it **forgets**. In
|
||||
v2, 0 meant `FL_UPSCALER_NONE`, `FL_FG_NONE`, and an `rtFlags` with no evidence bits —
|
||||
three measured negatives about a title nobody examined, which `03_METRICS` turns into
|
||||
`upscaler none` and `fg_factor 1.0`, the single inflated number rule 6 forbids.
|
||||
`measuredMask` made that safe **by convention**; v3 makes it safe **by construction**,
|
||||
and the mask becomes corroboration rather than the sole defence. `rtFlags`' polarity is
|
||||
flipped so every bit means *observed*.
|
||||
- **Four answers items 4/6/7 owe had no home.** DLSS super-resolution **and** Ray
|
||||
Reconstruction concurrently — RR was a mutually exclusive `upscaler` *value* while
|
||||
`03_METRICS` makes it an independent tri-state axis — plus `upscalerSharpness`, and, in
|
||||
`FlWriterState` because they are session facts rather than per-frame, the device
|
||||
**RT tier** without which rule 7's definite `No` had no producer at all, with
|
||||
`rtStateObjectsCreated` and `rasterPsoCreated`.
|
||||
- **Paid for by two narrowings that are corrections, not sacrifices.** `vramUsedBytes`
|
||||
(u64 bytes → u32 MiB) carried 64 bits of byte precision that every consumer divided
|
||||
away, to feed a comparison against `vramBudgetMb` — **already MiB** — that was
|
||||
unit-mismatched at the point of use. `fgEvaluations` (u32 → u8): ×4 multi-frame
|
||||
generation is 3, so saturating at 255 would mean 256× frame generation.
|
||||
- **`seq` @56 and `swapchainId` @60 did not move**, so `fl_ring.h`'s two pins hold
|
||||
verbatim, the seqlock's payload spans are unchanged, and the ring needed no edit.
|
||||
- **Three mask bits split producers that do not arrive together** — the same defect three
|
||||
times. `FL_MEASURED_UPSCALER_PARAMS`, because an NGX-direct title exports only the
|
||||
parameter-object *factories* so a writer knowing *which* upscaler ran knows nothing
|
||||
about quality (publishing `0` = "DLSS Performance" as measurement);
|
||||
`FL_MEASURED_PRESENT_ARGS`, because `wglSwapBuffers` and `vkQueuePresentKHR` have no
|
||||
such arguments and `syncInterval = 0` is a *real* DXGI value with no in-band sentinel;
|
||||
and `FL_MEASURED_FG_COUNTS`, because identity and per-present counts are two hook rows
|
||||
and a writer with only the first would publish `fg_factor 1.0` having counted nothing.
|
||||
- `FL_RT_PSO_ALIVE` → `FL_RT_PSO_CREATED_EVER`: creation is observed at
|
||||
`CreateStateObject` and destruction is COM `Release`, which is not in the inventory and
|
||||
must not be added — so the bit latches and could only ever mean "created ever".
|
||||
- **`03_METRICS`' RT `No` is now three conjuncts**, and the second is the one that is easy
|
||||
to drop: `hooksInstalledMask` must contain the **AS-build** hook. A writer with only
|
||||
`DispatchRays` sees nothing on an inline-RayQuery title, and its silence would otherwise
|
||||
be indistinguishable from a real negative.
|
||||
- **`pt_confidence` loses its fourth input rather than substituting one.** "The ratio of
|
||||
RT to raster work" has no cheap denominator — counting raster work means a per-draw hook
|
||||
— and §H6 records that a command-list count measures *recorded* rather than *executed*
|
||||
work anyway. The score may only ever *suggest*, so a weaker score is not a fabrication.
|
||||
- **The design came from a four-way panel, three judges and three refuters**, and the most
|
||||
useful thing the refuters found was not in any proposal: see the `FL_MEASURED_OUTPUT_RES`
|
||||
fix under Fixed. They also killed a claim this entry would otherwise have made — that
|
||||
reserved bytes let a future field skip the version bump. They do not: `recordSize` and
|
||||
`layoutVersion` are compared before a reader looks at anything, so an old reader refuses
|
||||
a new writer and never reaches an unknown field. What the reserve buys is that existing
|
||||
offsets do not move.
|
||||
- **Hook-path cost:** `RecordPresent` gains one comparison of two `uint16`s already in
|
||||
registers, and `Publish`'s two memcpy spans are `offsetof`-derived and byte-identical.
|
||||
**Not carried forward: the 8.4 ns figure.** That is `--probe-cost`'s empty-detour floor,
|
||||
which the tool says of itself; no instrument in the tree measures `RecordPresent`.
|
||||
|
||||
- **NVAPI is vendored, and the capability matrix gets the axis it could not be filled
|
||||
without.** `src/native/third_party/nvapi/` now holds nine headers (`nvapi.h`'s include
|
||||
closure plus `nvapi_interface.h`), `License.txt` and `amd64/nvapi64.lib`, from
|
||||
`github.com/NVIDIA/nvapi` @ `cd6918f6` (MIT). **x64 only** — `x86/nvapi.lib` is 438 KB of
|
||||
material we could never link and would still have to disclose. `NvApiDriverSettings.{c,h}`
|
||||
and the HLSL-extension headers are left behind for the same reason.
|
||||
- **Why that repository and not the SDK installer** is the whole licence argument:
|
||||
`amd64/nvapi64.lib` is a *tracked file in the MIT repo* and `License.txt` names the
|
||||
import libraries as the subject of the grant, so the **binary** is covered. The same
|
||||
file from the SDK installer arrives under NVIDIA's own agreement and could not be
|
||||
vendored into a GPL-3.0 tree.
|
||||
- **The canary came for free, and it ran in the order that makes it evidence.**
|
||||
`license-check.ps1` was made bidirectional after it was found unable to see
|
||||
*claimed-but-absent* material. Vendoring while `THIRD_PARTY_NOTICES.md` still said
|
||||
"Not yet vendored" failed the build — the *present-but-marked-absent* direction, which
|
||||
was structurally invisible before. The notice was flipped afterwards, not before.
|
||||
- **`ctest fl_nvapi_probe` exists because an unconsumed vendored dependency is
|
||||
unverified.** Nothing else compiles against `fl_nvapi` yet, so a short include closure
|
||||
or a wrong-architecture `.lib` would sit there with every gate green. The probe's
|
||||
*compile* is half the test.
|
||||
- **It is green on both kinds of machine, and exiting 0 is not what makes it green.**
|
||||
`nvapi64.lib` is a **static** stub library reaching `nvapi64.dll` through
|
||||
`nvapi_QueryInterface` at first call, so it is not a load-time dependency: a CI runner
|
||||
with no NVIDIA driver loads the binary and `NvAPI_Initialize` returns an error, which
|
||||
is exactly the degradation §L3 requires. Both branches exit 0 — so ctest additionally
|
||||
requires the string `BRANCH: (AVAILABLE|DEGRADED)`. **Canary: a probe gutted to
|
||||
`int main(){return 0;}` compiles, exits 0, and is now RED** at
|
||||
*"Required regular expression not found"*, with the native build and the other 15
|
||||
ctests still green. The alternation has to stay: pinning one branch would turn the
|
||||
other kind of machine red for being itself.
|
||||
- **What that still does not give you, said rather than implied:** ctest prints a
|
||||
passing test's output nowhere, so a CI log shows a branch was reached and **not
|
||||
which**. On a hosted runner it is inferable — no NVIDIA driver exists there, and the
|
||||
probe returns in ~0.01 s against ~1.4 s here — but inferable is not observed, and
|
||||
`18_GPU_VENDOR_APIS` §L3 now separates the two rather than claiming the stronger
|
||||
thing. What the run *does* prove is the load-time claim: a load-time dependency on an
|
||||
absent `nvapi64.dll` would not have started at all.
|
||||
- It refuses a **zero** GPU count rather than letting the name loop run no iterations,
|
||||
because every assertion inside a loop that never runs is vacuous.
|
||||
- **Measured on this machine:** driver `610.88` (branch `r610_85`), 1 physical GPU,
|
||||
"NVIDIA GeForce RTX 5080".
|
||||
- **A doc error the vendoring found and reading vendor documentation would not have:**
|
||||
§L3's function table named `NvAPI_GPU_GetMemoryInfo`. The headers mark it
|
||||
`__nvapi_deprecated_function` ("deprecated in release 520 — use
|
||||
`NvAPI_GPU_GetMemoryInfoEx`"), so under `/W4 /WX` a call to it **fails the native
|
||||
build**. Corrected. This is the class `17_HOOK_ENGINE:128` calls the highest
|
||||
false-confidence risk in the spike, sitting in a document instead of in code.
|
||||
- **The capability matrix is now vendor × layer**, restructured *before* anything was
|
||||
filled in — `18_GPU_VENDOR_APIS:137` said in its own words that the single-axis table
|
||||
"cannot express" the AMD/Intel deferral and that the axis is "a prerequisite of filling
|
||||
it, not a tidy-up afterwards". The legend separates `?` (a to-do, measurable here) from
|
||||
`untested` (a deferral, not measurable here) from `arch` (not available by
|
||||
architecture), which is precisely what the old table could not distinguish and what the
|
||||
UI consults before advertising a capability.
|
||||
- **The D3DKMT probe's two-OS requirement is deferred to Win 11, with a rationale.** One
|
||||
machine, and it is Win 11; Win 10 22H2 **stays a supported floor** and is explicitly
|
||||
unmeasured. Unlike the AMD/Intel gap this one *could* be closed with a VM and is being
|
||||
left open deliberately — so the deferral is conditional on the probe staying
|
||||
non-load-bearing, which the doc now states as the condition rather than as advice.
|
||||
|
||||
> **These five entries were written retrospectively.** PRs #40–#44 changed 8 files,
|
||||
> every one under `src/native/`, and touched no documentation at all — so for a day the
|
||||
> repository's own ledger described an Overlay with no hooks. CLAUDE.md's "any deviation
|
||||
> from a doc updates that doc in the same PR" did not catch it, because none of the five
|
||||
> deviated from a doc: they implemented specifications that were already written, and
|
||||
> the staleness landed in the *status* claims of other files. `legal/DISCLAIMER.md` §Accuracy
|
||||
> audit records the same drift from the user-facing side.
|
||||
>
|
||||
> > **And then it happened again, immediately, seven more times.** #45 — the PR that wrote
|
||||
> > the five entries above and complained about the gap — was followed by #46 through #52
|
||||
> > with **no changelog entry for any of them**, including the C# struct mirror, the ring
|
||||
> > reader, the handshake validator, the closed write-read loop and check 3's call site.
|
||||
> > The entries below were written retrospectively too, on 2026-08-05, from the diffs.
|
||||
> >
|
||||
> > **A retrospective note is not a mechanism, which is the actual finding.** #45 recorded
|
||||
> > the drift in prose and nothing about the repository changed, so the same failure ran a
|
||||
> > second time at greater length. `ci.yml` now carries a `changelog` job that fails a pull
|
||||
> > request touching `src/` without touching this file. Prose asking people to remember is
|
||||
> > what was already tried.
|
||||
> >
|
||||
> > **One of the seven is worse than missing.** `bd6d367` (#48) carries, verbatim, the
|
||||
> > commit body of `bff0f6a` (#47) — a squash whose `--body-file` came from the wrong
|
||||
> > branch. The subject line describes the occlusion-probe fix; every paragraph beneath it
|
||||
> > describes the struct mirror. Its entry below was reconstructed from the diff, because
|
||||
> > the commit message is evidence about a different PR.
|
||||
|
||||
- **Check 3 gets a call site, and the half that cannot have one** (#52). `19_SAFETY` has
|
||||
listed the per-title blocklist as check 3 from the beginning and it had **no call site**:
|
||||
`MatchesBlockedExecutable` was implemented, tested, and asked by nobody, so "check 3
|
||||
passed" read as "this title is not a known online title" while nothing had looked.
|
||||
`CheckBlockedExecutable` now runs inside `EvaluateImpl`, between the module scan and the
|
||||
pre-scan — one `OpenProcess` and a string compare, ahead of the only check that touches
|
||||
the filesystem.
|
||||
- **It needed a new seam.** `Sources::ImageDirectory` deliberately resolves the *install
|
||||
root* — Unreal puts the exe three levels below it, measured on Lies of P — and the file
|
||||
name is exactly what it discards. `ImageFileName` is a different fact, so it is a
|
||||
different seam and a new row in the fail-closed matrix.
|
||||
- **Unresolvable identity refuses** (`kProcessUnreadable`): `kFailed`, `kIncomplete`, an
|
||||
empty name and a null seam all take one path. The narrow conversion uses
|
||||
`WC_ERR_INVALID_CHARS` with **no** default character, so a name that cannot be
|
||||
represented exactly fails rather than becoming a string containing `?` — §S21's ANSI
|
||||
defect was exactly a silent lossy conversion.
|
||||
- **The store-id half cannot be called**, for three independent reasons: nothing produces
|
||||
a `store_id` (the platform metadata extractors were never built), `FlGuardEvaluate`
|
||||
takes a pid and nothing else *by design* (§S3 forbids a caller asserting a safety
|
||||
fact), and "unknown refuses" applied to it would refuse every title on every machine.
|
||||
It stays implemented, tested and uncalled. **Do not "fix" the second by widening the ABI.**
|
||||
- **The list ships empty**, so nothing is refused today; what changed is that populating
|
||||
it would now do something. The acceptance criterion asserts `kBlockedExecutable`
|
||||
*specifically*, because "it refuses" is indistinguishable from the four refusals the
|
||||
guard already makes.
|
||||
|
||||
- **The write-read loop closes, against our own harness and nothing else** (#51). Real
|
||||
guard, real injection, real Overlay, real reader: `ShmDrainIntegrationTests` seeds the
|
||||
rules with the product's own `RulesSeeder`, starts `hook-harness --real --hold-presenting`,
|
||||
injects through `NativeAntiCheatGuard`, and drains records while driving
|
||||
`GuardSupervisor.ScanOnceAsync` and `PublishGuardResult`. A second case proves the safety
|
||||
stop: >10 records flowing, then `unhookRequested`, then `writeIndex` frozen 700 ms later.
|
||||
- **CI found a hard-gate defect the dev box structurally could not.** Running the test,
|
||||
the guard refused our own harness — `SuspiciousUnsigned unknown
|
||||
System.Security.Cryptography.ProtectedData.dll`. §S16 puts the target's **ancestors**
|
||||
in the scan set and the .NET test host is the harness's parent, which is the
|
||||
launch-mode arrangement. A .NET host that loads that assembly poisons its own scan set.
|
||||
**A gate that cannot pass**, and §S19(b)'s "plausible and unmeasured" is superseded.
|
||||
- **So the drain tests are `Category=Integration` and CI runs `-SkipIntegration`.** The
|
||||
skip is loud, names §S19(b) and says how to run them; a developer running
|
||||
`./build.ps1 check` with no arguments still gets everything. Proven both directions —
|
||||
76 Infrastructure tests by default, 73 with the switch.
|
||||
- **What that costs, stated rather than left to be discovered:** the only end-to-end proof
|
||||
of the capture path does not run in the merge gate. See §Known issues.
|
||||
|
||||
- **The Agent can read the ring, and the pointer trap that would have hidden it** (#50).
|
||||
`ShmRingReader` mirrors `fl_ring.h`'s `RingReader::Drain` rather than re-deriving it —
|
||||
where the two disagree the header is right and the C# is the bug.
|
||||
- **Map at offset 0, and this is measured** (.NET 10, Win 11 26300): a view created at a
|
||||
non-zero offset is mapped from the 64 KiB allocation-granularity boundary *below* it,
|
||||
and `AcquirePointer` returns **that** base. So the obvious way to reach the control
|
||||
block — map region 3 at `0x80`, write `*(uint*)(p + 12)` — writes
|
||||
`FlShmHandshake.pid` instead of `FlControlBlock.guardTicks`. It does not fault, and
|
||||
`Read<T>` does not bounds-check it either, because the handle legitimately spans from
|
||||
byte 0. The supervision counter would have landed silently on the field a reader
|
||||
validates first. `Bind` now asserts `PointerOffset == 0` rather than assuming it.
|
||||
- **Seed the read index from the writer.** `fl_ring.h` starts its reader at 0 because it
|
||||
is created alongside its writer; an Agent attaching to a ring already in flight is a
|
||||
different situation. Canary: seeded at 0 against a ring at `writeIndex` 1,000,000 the
|
||||
first drain reports **999,992 drops** — and `04_CAPTURE` defines any non-zero drop count
|
||||
as "the Agent stalled for over ~16 s". It also re-ingests up to `capacity` stale records
|
||||
from a finished session as current frames. Records already published at attach are
|
||||
reported separately as `RecordsBeforeAttach`, which is not a stall.
|
||||
- **Bound the capacity against the mapping.** The validator accepted any power of two —
|
||||
every value up to 2³¹ — and returned `Ok` having never related that claim to the section
|
||||
it describes. The reader indexes by raw pointer arithmetic (the seqlock needs ordering
|
||||
`Read<T>` does not provide) and so gives up that API's bounds check.
|
||||
`CapacityExceedsMapping` is taken from `ByteLength`, never from `DefaultCapacity`.
|
||||
- **Publish order is a safety property and it is the reverse of the natural one** — flag
|
||||
first, tick second, because a fresh tick *resets* the Overlay's supervision clock.
|
||||
**The suite does not verify that order**, and says so: it asserts both values land,
|
||||
which a publisher writing them the wrong way round also satisfies. What holds the
|
||||
property is `PublishGuardResult` being the only writer of either field.
|
||||
|
||||
- **The Agent gets a build id of its own, so refuse-to-attach can run** (#49). `07_IPC`
|
||||
makes a `buildId` mismatch a hard refuse-to-attach and `04_CAPTURE` says the Agent
|
||||
compares it "against its own" — and the Agent had no own value. Two documents specified a
|
||||
check that could not run in either direction (§S23-1).
|
||||
- `FlGuardBuildId` is observation-only and **refuses rather than truncating**: a shortened
|
||||
id is not a partial answer, it is a *different* id, and returning one would produce a
|
||||
permanent mismatch caused by this function rather than by any real version skew.
|
||||
- **Why the guard carries it and not the Overlay:** reaching `FlGetBuildId` means
|
||||
`LoadLibraryW` on `FrameLedger.Overlay.dll`, which starts its init thread and creates a
|
||||
ring under the *Agent's* own pid. The payload is not something its own host may load.
|
||||
- `ShmHandshakeValidator` is the comparison, as a pure function, so every refusal is
|
||||
drivable without a live target. `layoutVersion == 0` is **`Incomplete`, not a mismatch**
|
||||
(it is published last behind a release fence, so zero means "retry", not "restart the
|
||||
game"); the version is checked **before** the fields it vouches for; and the default is
|
||||
`NotEvaluated`, never `Ok`.
|
||||
- **The fail-open, measured.** The naive implementation compares two strings, and with
|
||||
neither side carrying an id `string.Equals("", "")` is **true** — so the gate reported
|
||||
`Ok` for every process on the machine. **The test for it was nearly missed:** the first
|
||||
draft asserted the two halves as separate cases and never put both in one call, which
|
||||
is the only arrangement that reaches the defect.
|
||||
|
||||
- **The C# mirror exists, and the gate that guards it stops being a `Test-Path`** (#47).
|
||||
CLAUDE.md calls the struct mirror the mechanism protecting the shared-memory ABI; nine
|
||||
files described it in the present tense and none of it existed (§R10).
|
||||
- `ShmLayout.cs` is driven by `tools/fl-layout-dump`'s JSON, never a transcribed table —
|
||||
a hand-written offset table is a *second* statement of the layout, and two statements of
|
||||
one fact drift, which would be the defect the mirror exists to catch, reintroduced
|
||||
inside the catcher.
|
||||
- **Blittability is asserted, and that is not decoration.** Measured: swapping the
|
||||
`fixed byte BuildId[32]` for the `[MarshalAs(ByValTStr)] string` idiom this repository
|
||||
already uses correctly elsewhere keeps `Marshal.SizeOf` at 64 with **every offset
|
||||
assertion still passing**, while `Unsafe.SizeOf` collapses to **40**. That mirror looks
|
||||
correct by every obvious check and cannot be read out of a memory-mapped view.
|
||||
- **Both directions**, and the reverse walk caught something on its first run:
|
||||
`fl-layout-dump` was not emitting the `reserved` tails, so the C# declared members the
|
||||
dump could not confirm. Fixed in the dump rather than excluded from the check.
|
||||
- **The gate was the bigger finding.** `build.ps1`'s struct-mirror step was
|
||||
`Test-Path ShmLayout.cs`, then printed "covered by dotnet test" — it never looked for
|
||||
the test. An *empty* `ShmLayout.cs` would have turned an honest loud skip into a silent
|
||||
green, and deleting the test afterwards would have kept it green forever. It now reads
|
||||
the run's `.trx` and requires the named class to have **executed**. `dotnet test` makes
|
||||
a regression red; this makes *deleting the regression test* red.
|
||||
- Three canaries proven red, and **the harness was broken twice before it proved
|
||||
anything** — a renamed class tripped a file-name analyzer and the run died at *build*;
|
||||
a `sed` rewrite gave the file LF endings and the run died at *`dotnet format`*. Both
|
||||
printed a failure, and a failure upstream of the gate proves nothing about the gate.
|
||||
|
||||
- **`api` is resolved per swapchain, and `GetDevice` does not return what the docs imply**
|
||||
(#44). `api` was hardcoded to `FL_API_D3D11` on every record — a guess written into a
|
||||
field `03_METRICS` consumes and `06_DATA_MODEL` persists. One hook on the shared
|
||||
`dxgi.dll` class vtable catches D3D11 and D3D12 alike, so the present call cannot tell
|
||||
them apart; the Overlay now asks the swapchain which device created it, once per
|
||||
swapchain, and caches it.
|
||||
- **Measured, and the obvious implementation was wrong.**
|
||||
`CreateSwapChainForComposition` takes a **command queue** for D3D12, so the first
|
||||
version queried the returned device for `ID3D12CommandQueue` — and every record from
|
||||
a real D3D12 target came back `FL_API_UNKNOWN`. DXGI resolves the queue to its owning
|
||||
device before storing it, so `ID3D12Device` is what answers. The queue query is kept
|
||||
anyway: it costs one failed QI per swapchain, and a DXGI that *did* hand back the
|
||||
queue would otherwise regress to `UNKNOWN` silently.
|
||||
- `apiMask` now records what was **seen presenting**, not what the process loaded — a
|
||||
title can link `d3d12.dll` and present through D3D11.
|
||||
- Both directions, which is what makes either assertion mean anything: a new
|
||||
`--hold-presenting-d3d12` harness mode builds device → command queue → swapchain, and
|
||||
the D3D11 case gained the mirror assertion, so a resolver that always answered D3D12
|
||||
fails there.
|
||||
- **OpenGL is not attempted.** `wglSwapBuffers` is a flat export and the hook is small,
|
||||
but `hook-harness` has no OpenGL mode, and shipping an unexercised hook into a game
|
||||
process is not something this project does. The harness mode is the prerequisite.
|
||||
|
||||
- **The safety stop and supervision loss, on the present path** (#43). `19_SAFETY` calls
|
||||
the mid-session stop the single most important runtime behaviour in the capture layer,
|
||||
and `legal/DISCLAIMER.md` promises both to the user. Until now neither existed —
|
||||
`FlRequestUnhook` set a status field while the hooks kept running.
|
||||
- `unhookRequested` → hooks out, status `UNHOOKED`. `guardTicks` stalled past
|
||||
`FL_GUARD_TICK_DEADLINE_MS` → the same. The clock starts when the **mapping is
|
||||
published**, not at first present, because `07_IPC` is explicit that "never advanced"
|
||||
and "stopped advancing" are the same state.
|
||||
- **Stopping is one-way.** Resuming ticks does not resume recording; a capture side
|
||||
that can un-stop itself is one whose stop is advisory.
|
||||
- **Two of three canaries red, and the third is recorded rather than hidden.** Removing
|
||||
`g_observing = false` and leaving only `MH_DisableHook` kept the suite **green** — so
|
||||
"the flag is necessary" is *not* a property this suite proves. The flag is kept
|
||||
deliberately (it closes the window for a thread already inside the hook body, and it
|
||||
is the only thing that holds if `MH_DisableHook` fails) and the comment now says so.
|
||||
- **Not covered, and stated rather than left to look covered:** the 65-second expiry in
|
||||
its real configuration. The canary proves the comparison fires, not that 65000 is the
|
||||
number on the shipped path.
|
||||
|
||||
- **The present hook, and a harness that presents while we inject** (#42). MinHook on the
|
||||
shared `dxgi.dll` class vtable, read off a throwaway WARP composition swapchain that is
|
||||
released immediately — slots 8 `Present`, 13 `ResizeBuffers`, 22 `Present1`, proved by
|
||||
behaviour in ctest `fl_vtable_indices`, never hardcoded.
|
||||
- **`--hold-presenting` had to exist first.** `--hold` presents 240 frames and *then*
|
||||
sleeps; those are over in milliseconds while `fl_guard_test` injects ~800 ms later, so
|
||||
an Overlay injected into `--hold` observes exactly **zero**. Every "N presents → N
|
||||
records" assertion written against it would have been vacuous — the same shape as the
|
||||
`DXGI_PRESENT_TEST` defect this harness was already fixed for once. The handshake test
|
||||
now asserts `writeIndex == 0` against `--hold` deliberately, so the trap has a test on
|
||||
it instead of a comment.
|
||||
- **Honesty, which is why #36 spent two bytes.** A present-only writer sets
|
||||
`measuredMask = FL_MEASURED_OUTPUT_RES` and `rtFlags = FL_RT_NOT_MEASURED` and claims
|
||||
nothing else. Leaving the mask at 0 with the zero-defaults would assert "no upscaler,
|
||||
no frame generation, no ray tracing" as measured fact ~118 times a second — producing
|
||||
`fg_factor 1.0` (rule 6) and a definite RT `No` (rule 7) about a title nobody looked at.
|
||||
- `FL_HOOK_GUARD` wraps **only our code, never the call to the original** — otherwise a
|
||||
game's own fault inside the trampoline is counted as ours. Three faults →
|
||||
`MH_DisableHook(MH_ALL_HOOKS)` and `status = self_disabled`.
|
||||
- `status` reaches `READY` only when hooks are actually installed; a failed
|
||||
`MH_Initialize` leaves it `INIT`, because `READY` would claim a capture side that does
|
||||
not exist and the Agent's degradation path is what should run.
|
||||
- Four canaries, each proven red: claiming everything measured, asserting a definite RT
|
||||
`No`, a `frameIndex` that stops advancing, and a swapchain never identified.
|
||||
|
||||
- **The DLL gets inside, maps its ring, and publishes a handshake** (#41). The first real
|
||||
code in `FrameLedger.Overlay`, which until then was a 30-line scaffold exporting one
|
||||
function. `DllMain` does **only** `DisableThreadLibraryCalls` and `CreateThread`;
|
||||
everything else runs on the init thread, outside the loader lock (§H2).
|
||||
- The mapping carries a DACL granting only the current user's SID.
|
||||
`BuildUserOnlySecurity` returns false rather than falling back to a default DACL — a
|
||||
mapping the machine can write is not a degraded version of this one, because the
|
||||
Agent's control block is in it and `unhookRequested` is the safety stop.
|
||||
`ERROR_ALREADY_EXISTS` also refuses.
|
||||
- `layoutVersion` is published **last**, behind a release fence, because it is the field
|
||||
a reader validates first: a reader that saw the version while `capacity` was still
|
||||
zero would compute a ring of no slots and read garbage.
|
||||
- **`status` is `INIT`, not `READY`, and that is the point** — nothing was hooked in that
|
||||
slice, so no record could ever arrive.
|
||||
- Three canaries, each proven red: claiming `READY` with no hooks, leaving `capacity`
|
||||
unpublished, and corrupting `buildId`.
|
||||
|
||||
- **The SPSC ring, and an honest account of which half the suite proves** (#40).
|
||||
`fl_ring.h` implements `07_IPC` §Protocol rules and nothing else; where the two
|
||||
disagree the document wins and the header is the bug. Drop accounting lives on the
|
||||
**reader**, the only side that knows what it consumed.
|
||||
- **Two of four canaries came back GREEN, and that is the finding.** *"The payload write
|
||||
steps over `seq`"* and *"the reader re-reads `seq`"* both survive, because the damage
|
||||
is observable only inside a 64-byte memcpy and neither a 1024-slot nor an 8-slot
|
||||
concurrency case lands in it across 200,000 records. **Those two properties are
|
||||
therefore unverified**, and the file header says so rather than letting nine
|
||||
assertions imply coverage.
|
||||
- **One test was wrong in a way that looked like the code was wrong**: "the payload write
|
||||
never touches `seq`" asserted on slot 1 because the record's `frameIndex` was 1 — but
|
||||
the slot is chosen by the publish counter, which starts at 0. It failed against a
|
||||
correct writer.
|
||||
- Claims `FL_MEASURED_HDR` (bit 7) in the last free window. `hdr` had no "not measured"
|
||||
state; #36 fixed that class for five other fields and missed this one. The byte is
|
||||
already written every frame, so it costs no layout change now — and after the C#
|
||||
mirror exists the identical edit is user-visible and a SemVer MAJOR.
|
||||
|
||||
- **`fl-probe-interposer` — the vtable premise, proven, and the Streamline
|
||||
question narrowed to a licence decision** (`20_OPEN_QUESTIONS` §H5 case 3,
|
||||
`spike-notes.md` §5, previously an empty template). It runs in **our own
|
||||
process**: no game, no injection, no guard, and it needs **no vendor headers**,
|
||||
only `GetProcAddress` and DXGI types from the Windows SDK.
|
||||
- **ctest `fl_vtable_identity_control`** asserts both directions of the property
|
||||
the whole hook design rests on — two independently created composition
|
||||
swapchains share one vtable, and a different interface does not. A comparison
|
||||
never shown to detect a *difference* carries no information when it reports
|
||||
"same", so the negative control is not optional.
|
||||
- **The interposer half is INCONCLUSIVE, and that is the result.** Loaded from
|
||||
Cyberpunk 2077 and Black Myth: Wukong, `sl.interposer.dll` forwards to
|
||||
`dxgi.dll` and leaves the factory *and* swapchain vtables untouched until
|
||||
`slInit()` has run. The probe enumerates its own modules, finds no `sl.*`
|
||||
plugin mapped, and exits 2 rather than rendering a verdict.
|
||||
- **Its first version got this wrong and the fix is the interesting part.** It
|
||||
printed *"the vtable is THE SAME — a hook DOES catch Streamline presents"* for
|
||||
both titles, which would have closed §H5 case 3 on a measurement of
|
||||
passthrough. The tell was already in its own output: an interposing
|
||||
Streamline cannot leave the **factory** vtable unwrapped, because wrapping the
|
||||
factory is how it reaches the swapchain. "Could not look" must not read as
|
||||
"looked and it was clean" — the guard's tri-state discipline, applied to a
|
||||
probe.
|
||||
- **The blocker is now named:** reaching the wrapped path needs `slInit`'s
|
||||
`sl::Preferences`, i.e. vendor ABI — the question `THIRD_PARTY_NOTICES.md`
|
||||
answers for Intel IGCL and nobody has asked for NVIDIA. That is a licence
|
||||
decision, not absent hardware. And the exposure is narrower than §H5 implied:
|
||||
NGX-direct titles never wrap the swapchain.
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,61 @@
|
||||
# HANDOFF history — 0.1.0-beta.10
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-27 — the beta.10 train: the display mode, the admin mode, the Unreal Engine version
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.10]`; this is what no other file carries. The approved plan was six PRs:
|
||||
PR-1 the Unreal version (schema 0015), PR-2 the Overlay's display region (shared-memory layout 4), PR-3 the display mode
|
||||
in the Agent and the App (schema 0016), PR-4 the admin mode, PR-5 docs, legal text and the tested-games list, PR-6 the
|
||||
release.*
|
||||
|
||||
**Decisions (owner, 2026-09-27, asked before the plan — do not re-ask):**
|
||||
|
||||
- **D34 — the admin mode asks Windows at EVERY Agent start.** The UAC prompt appears whenever the Agent starts with
|
||||
`capture.run_elevated` on — owned by the App's window when the App starts it, flashing on the taskbar when the logon
|
||||
task does. No "highest privileges" task, no service, no silent path. Games an elevated Agent starts get the desktop
|
||||
shell's token. The elevated Agent is started for one user (`--for-user <SID>`) and exits 11 as any other account.
|
||||
- **D35 — the tested-games list comes from a COPY of the owner's ledger** (scratchpad, Python `sqlite3`; never a
|
||||
FrameLedger binary against the data folder) plus the repository's own evidence, and **the owner reviews it before it
|
||||
is committed** — the repository is public.
|
||||
- **D36 — legal text changes where it would become false** (Privacy 2.5, Disclaimer 2.8; EULA stays 1.3), **and
|
||||
`LIMITATIONS.md` exists**: a user-facing list of what the WHOLE software cannot do, at the repository root and in the
|
||||
App under Help ▸ Limitations — not one of FR-11's accepted documents (the Legal Gate records an acceptance per
|
||||
document, and this is information, not terms).
|
||||
- **D37 — each PR merges when its CI is green**, then the release PR and the GPG-signed tag.
|
||||
|
||||
**What was measured before it was written:**
|
||||
|
||||
- **Unreal versions, ten installed titles, read-only** (`spike-notes` §15): eight read (4.26.1 … 5.5.4), two honestly
|
||||
none (Cronos demo, Rune Factory). Black Myth: Wukong's executable is protected (`.rdata` empty) and its build name sits
|
||||
in `.code` — the whole-file fallback read it in 7.5 s from the owner's USB drive.
|
||||
- **The display region's cost** (hook-harness `--probe-frames`, WARP): `GetFullscreenState` 12.6–13.1 ns, `GetDesc`
|
||||
13.6–14.5 ns per call, at most twice a second per swap chain.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **A test run reseeds the rules file in the REAL data folder** (`RulesSeeder` in the integration tests writes
|
||||
`%LOCALAPPDATA%\FrameLedger\rules`). PR-1's rules `2026.09.6` carry an extractor type (`unreal_build`) the installed
|
||||
beta.9 cannot parse: its detection sweep says "rules unusable" until that Agent restarts — its seeder sees a file it
|
||||
wrote itself (the marker's hash) and puts its own back — or beta.10 is installed. The guard reads the same file and is
|
||||
unaffected (it ignores version extractors). Worth a scratch rules folder for the tests one day.
|
||||
- **`DXGI_SWAP_EFFECT_DISCARD` is 0** — region 4 stores the effect plus one, the vendor-zero trap.
|
||||
- **A minimised game presents only what the hook drops** (occlusion probes): a region-4 sample older than 2 s says
|
||||
nothing about exclusivity now; the Agent keeps its window and drops its exclusive bits.
|
||||
- **The Agent is DPI-unaware**: Windows scales another process's window coordinates for it. The window reader switches
|
||||
its thread to per-monitor-aware (V2) for the calls and back.
|
||||
- **A Tier-2 session never reaches the aggregator** — display columns live on the recorder's skeleton, or a Tier-2 row
|
||||
would carry none.
|
||||
- **`SessionRowColumns` is generated by a script that is not in the repository** — edit it by hand, by name.
|
||||
- **`CreateProcessWithTokenW` needs `SeImpersonatePrivilege`**, which an unelevated (filtered) token does not hold: the
|
||||
shell-token start is testable only on the elevated CI runner, and a runner with UAC off has an elevated shell — so the
|
||||
test compares the child's elevation with the SHELL's, never with "unelevated".
|
||||
- **An elevated token's default DACL omits the user** (again): the ledger's migration lock is now a `SharedMutex` with a
|
||||
stated descriptor; the instance lock and the elevation marker are only probed, and a refused probe reads as held.
|
||||
- **`CA2025` flags a disposable handed to an un-awaited task** even when ownership moves to it; the launcher says so in
|
||||
a suppression with its reason, or splits the method so the analyzer can see it.
|
||||
- **Heredocs mangle backslashes and `\a`** (`D:\another` became `D:<BEL>nother` in a test). Patch scripts are written
|
||||
with the Write tool and run by path; a scan for control characters before the gate catches the rest.
|
||||
|
||||
**Owner-only, added to the list below:** item 7.
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# HANDOFF history — 0.1.0-beta.11
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# HANDOFF history — 0.1.0-beta.12
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,39 @@
|
||||
# HANDOFF history — 0.1.0-beta.13
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# HANDOFF history — 0.1.0-beta.14
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# HANDOFF history — 0.1.0-beta.15
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# HANDOFF history — 0.1.0-beta.16
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# HANDOFF history — 0.1.0-beta.17
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# HANDOFF history — 0.1.0-beta.18
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
# HANDOFF history — 0.1.0-beta.19
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# HANDOFF history — 0.1.0-beta.20
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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.
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# HANDOFF history — 0.1.0-beta.21
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**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 *(struck 2026-10-13: the head is §beta.22 below)*
|
||||
|
||||
*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.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# HANDOFF history — 0.1.0-beta.22
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~**START HERE**~~ — 2026-10-13, 0.1.0-beta.22: a request the capture agent never answered *(struck 2026-10-14: the head is §beta.23 below)*
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.22]`; this is what no other file carries.* The owner, during the beta.21
|
||||
train: "Bạn xử lý chip thành 1 pr mới sau release và thành 1 phiên bản mới nhé" — the chip beta.21's review of Play
|
||||
left (§beta.21's traps): every caller of the pipe, not only Play, as its own PR and its own pre-release. One PR — #306,
|
||||
`AgentConnection.AnsweredAsync` and `AgentAnswers.IsUnanswered`, with deleting sessions, the hooking switch, the anti-cheat
|
||||
exception and Play telling *not sent* from *not answered* — then the release.
|
||||
|
||||
**Decisions:** none new. *Not answered* is said as not known (`Agent_Unanswered`) and never as the old words for *not
|
||||
sent* ("nothing was deleted", "nothing changed"): a request the connection closed under may have been carried out.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **VSTHRD003 rejects awaiting a `Task` a method was handed** ("work that was not started within your context"): a helper
|
||||
that wraps a request's exceptions takes a `Func<Task<T>>` and starts it itself — which also catches what the request
|
||||
throws before it returns a task.
|
||||
- **`ObjectDisposedException` derives from `InvalidOperationException`**: a `catch (InvalidOperationException)` for "not
|
||||
connected" would read a disposed pipe as "nothing was sent". `AgentConnection` turns it into the `IOException` first,
|
||||
so the callers' split holds.
|
||||
|
||||
**Owner-only, added to the list below:** item 18 — **passed 2026-10-13**.
|
||||
|
||||
**After the release (owner, 2026-10-13):** "Tất cả các item đã đạt yêu cầu. Bạn có thể xử lý chip, phiên bản mới (nếu
|
||||
cần), cập nhật, rồi đóng phiên nhé" — items 16, 17 and 18 passed; the chip beta.22's local gate left (`fl_ring`'s
|
||||
hammering-writer guard, red on a correct ring) became beta.23 PR-1, #308: both concurrency cases guard on drains that
|
||||
overlapped the writer (§Traps, the native-test entry). Merged for the next pre-release; no release, since nothing a
|
||||
user runs changed.
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
# HANDOFF history — 0.1.0-beta.23
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` when 0.1.0-beta.24 was cut, 2026-10-19 (owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## **START HERE** — 2026-10-14, 0.1.0-beta.23: a game's artwork, pages that do not freeze, the documents that drifted
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.23]`; this is what no other file carries.* The owner, 2026-10-14: "Bạn phân tích
|
||||
và lên plan cho phần tiếp theo gồm những nội dung sau: 1. Thêm ảnh bìa/hero/cover của game từ các nền tảng đó - Đặt trong
|
||||
detail của game. (Nếu được); Tuỳ chọn: có thể sync màu cùa cover với màu của detail; 2. Cập nhật, sync docs; 3. Kiểm tra
|
||||
hiệu suất khi chuyển giữa các tab (nếu có vấn đề hiệu năng)" — then the whole train to the release without asking again.
|
||||
On top of #308 (PR-1): #309 (the pages, measured first), #310 (the artwork), #311 (the drift), then this release.
|
||||
|
||||
**Decisions:**
|
||||
|
||||
- **D60 — a game's artwork is what is already on the PC.** The image the user chose (*Edit… ▸ Choose image…*), else
|
||||
what the Steam or GOG GALAXY app keeps for the game it installed — found through the stores' own records as Play finds
|
||||
them (`StoreRecords.Owning`, never the row's platform alone). Nothing is downloaded: `privacy.online_metadata` stays
|
||||
reserved. A chosen image is a PNG copy, `<data>\covers\game-<id>-<unix ms>.png`, named relative in `cover_path`; only
|
||||
those names are followed — never a rooted, share or `..` path, never through a junction or a symbolic link, because a
|
||||
viewer's copy of a ledger may come from anywhere (D52).
|
||||
- **D61 — the band takes the artwork's colour as far as every text on it reads**: primary and secondary 4.5:1, tertiary
|
||||
3:1, the pills' and the warning's text 4.5:1 on their own fills; at most 30 % on the dark theme, 22 % on the light. On
|
||||
by default (the owner's choice); never in high contrast; it follows a theme switch by resource reference.
|
||||
- **The pages' speed was judged by a bar written before the first measurement** (`spike-notes` §21): fix what keeps the
|
||||
UI thread busy 50 ms or more, can block on I/O, or grows with each visit. Recorded, not fixed: page builds of 85–370 ms,
|
||||
and **the library grid (275 ms at 48 games) — non-virtualizing by the beta.11 decision; a virtualizing one changes the
|
||||
page's look, which is the owner's call** *(answered 2026-10-15: it stays as it is — §After the release below)*; no
|
||||
`sessions.started_at` index (a schema version locks out every earlier
|
||||
build, and nothing measured asked for it).
|
||||
- `LIST_GAME_TESTED`: the Everhex Demo row and the corrected Vulkan sentence, approved by the owner under D35.
|
||||
|
||||
**Traps met on the way:**
|
||||
|
||||
- **Microsoft.Data.Sqlite completes its "async" calls synchronously**: after a ledger read, `ConfigureAwait(false)` is
|
||||
still on the UI thread — the session decode, the sorts and the stutter detection all ran there (`16_WPFUI_SYNTAX`
|
||||
§Gotchas).
|
||||
- **A transient view model that is `IDisposable` lives until the App exits** (the root container keeps it), and every
|
||||
Dashboard ever opened stayed subscribed. FR-3.8's "Session saved" lived in that view model and reached every page only
|
||||
through the leak — it is `Services.SessionNotices` now.
|
||||
- **A `ui:Image` given a `Style` of its own that is not based on `DefaultImageStyle` has no template** and draws nothing
|
||||
in the place it takes. Only a render showed it; `AccessibilityTests.NoStyleOfAWpfUiControlLeavesOutItsTemplate`
|
||||
refuses it now.
|
||||
- **A page just navigated to is mid-fade**: a `RenderTargetBitmap` of it reads every colour washed out unless the
|
||||
presenter's `Transition` is `None`.
|
||||
- **The Bash tool's heredocs halve backslashes**: `covers\game-` became an invalid C# escape, and `\r\n` in a Python
|
||||
heredoc became real line breaks. Write such files with the editor tools.
|
||||
- **`Directory.Delete(…, recursive: true)` over a junction throws without elevation** (it asks Windows to unmount a
|
||||
volume, and the link is removed anyway): a test deletes its junction itself first.
|
||||
|
||||
**Owner-only, added to the list below:** item 19 — **passed 2026-10-15**.
|
||||
|
||||
**After the release (owner, 2026-10-15):** "Item 19 hiện đã đạt 100% yêu cầu. Phần chip sẽ đi kèm với phiên bản tiếp
|
||||
theo. Bạn có thể cập nhật và đóng phiên, thư viện vẫn giữ như cũ." — item 19 passed; the chip the release tree's local
|
||||
gate left goes with the next pre-release (`fl_guard`'s native-log test, red under load: after the stop, the last
|
||||
`UNHOOK_RESTORED` lines were not in the file within its 10-second wait — known since beta.9, and no native code changed
|
||||
in beta.23; green on the re-run); and **the library grid stays as it is**: the beta.11 decision
|
||||
(`Controls/UniformWrapPanel`, non-virtualizing — cards an equal share of the width, each row as tall as its tallest
|
||||
card) holds, at 275 ms for 48 games (`spike-notes` §21). Recorded with no release: nothing a user runs changed.
|
||||
@@ -0,0 +1,38 @@
|
||||
# HANDOFF history — 0.1.0-beta.3
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 0.1.0-beta.3 (2026-09-21) — what it decided, and the traps it paid for
|
||||
|
||||
*PRs #204-#210. Status is where status lives (`CHANGELOG.md` `[0.1.0-beta.3]`); this is only what no other file carries.*
|
||||
|
||||
**Decisions (owner, 2026-09-21).**
|
||||
- ~~**D18 — the guard has one override, and its shape is fixed.**~~ **Withdrawn 2026-09-22 (D22, below).** Per game, off by default, never global, a two-act
|
||||
disclosure stamped by the Agent, overruling the guard's JUDGEMENT only, never changing HOW FrameLedger injects.
|
||||
`19_SAFETY` §The user's bypass is the specification and CLAUDE.md rule 2 carries it as a rule. The owner chose this
|
||||
over a global switch and over a variant that kept kernel-level families refused. **Do not widen it**: no settings key,
|
||||
no CLI verb (`--console` has none on purpose), no rules-file field. A Vulkan title the guard refuses stays refused.
|
||||
- **D19 — the DLSS preset derived from the render scale is STILL not shown.** `Domain.Metrics.UpscalerNames` names the
|
||||
measured byte only; §7a's decision stands open. The driver-reported rung reached the App, identity only.
|
||||
- **D20 — the bug bundle does not get the machine's hardware.** `sysinfo.json`'s keys are the issue link's prefill;
|
||||
`--diag` and Settings ▸ System (with Copy) carry it instead.
|
||||
|
||||
**Owed by the owner after this release.** `20_OPEN_QUESTIONS` M10 (one elevated session with PawnIO beside a reference
|
||||
tool decides whether `cpu_temp` stays); a look at the light theme's pills ~~, the bypass dialog~~ and Settings ▸ System in the
|
||||
running App — no FrameLedger binary was run against the owner's data folder in the session that built them ~~; the ja
|
||||
review of `Safety_Bypass_*`, which ships as English until signed~~ (moot since 2026-09-22: the strings are gone).
|
||||
|
||||
**Traps.**
|
||||
- **xUnit.net v3 4.x defaults to Microsoft Testing Platform v2.** `build.ps1` is VSTest-shaped (collector, `results.trx`);
|
||||
the projects reference `xunit.v3.mtp-off`. Moving to MTP is a `build.ps1` change, never a version bump.
|
||||
- **4.0.1's scheduler found a race 3.2.2 never did**: test classes that WRITE the static `Strings.Culture` must share
|
||||
`StringsCultureCollection`. A new App test that sets the culture and is not in it will fail one run in N.
|
||||
- **A bash heredoc mangles apostrophes and `\\`, even quoted.** Every patch script in this session that carried C#
|
||||
verbatim strings, `\n` escapes or prose with `'` was written with the Write tool and run by path.
|
||||
- **A WPF page property named `System` does not compile** — the generated `.g.cs` resolves `System.` against it.
|
||||
- **NSubstitute: never build a substitute inside another's `Returns(...)`** (`CouldNotSetReturnDueToNoLastCall`).
|
||||
- **Branch protection requires an up-to-date branch.** A small PR merged in the middle of a train puts every open PR
|
||||
`BEHIND`; `gh pr update-branch N` and a second CI cycle is the price. Merge the train in order and keep side PRs out.
|
||||
- **`guard_test.cpp`'s native-log test slept a fixed 1500 ms** and was read between two lines on a loaded runner; it
|
||||
polls now. Record a flake on the PR BEFORE `gh run rerun --failed` erases it.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# HANDOFF history — 0.1.0-beta.4
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 0.1.0-beta.4 (2026-09-21) — four faults from beta.3's first day
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.4]`; this is what no other file carries.*
|
||||
|
||||
**Decision (D21).** A process an anti-cheat driver protects is `TargetUnreadable`, and nothing FrameLedger offers changes
|
||||
that: it is not, and may not become, a way past another product's protection (rule 3, not rule 2). ~~"the bypass
|
||||
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
|
||||
`git describe`. Both sides of the handshake compile the same string, so nothing breaks; it is a release that calls
|
||||
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
|
||||
and was again at 21:02 (System log 1074), and the owner's external USB drive was failing all evening. The three
|
||||
failed starts are UNEXPLAINED. What is still true and still unbuilt: `Setup.exe` run by hand does not stop the Agent,
|
||||
and only the CHANGELOG says to.
|
||||
- **A GF2 session ended `SafetyUnhook` 35 s in (2026-09-21 21:45) and nothing recorded which finding fired.** ~~read it
|
||||
the next time it happens before guessing~~ **Mostly explained by the owner's report:** the game is on the failing
|
||||
drive, `GF2_Exilium.exe` crashed at 21:45:50 with `0xc0000006` (in-page I/O error, Application log 1000/1005, eleven
|
||||
Ntfs errors in that minute), and the Agent saved the session at 21:45:52. The 30 s re-scan reads the game's directory
|
||||
(check 4) and the process; either failing is a refusal by design, so a dying drive reads as a safety unhook. **Open:**
|
||||
that row says `UnhookedSafety` about a game Windows says crashed — whether a crash witness should outrank the unhook
|
||||
in `ExitStatusMapper` is a decision, not a bug fix. The log line's new `guard=` detail will say which check it was.
|
||||
- **Read Windows' event logs before attributing a symptom** (`Get-WinEvent` System: disk 51/153, UASPStor 129, Ntfs;
|
||||
Application: 1000/1005). On 2026-09-21 the first pass published one cause that was wrong and left one 'unknown' that
|
||||
those two logs answered in a minute.
|
||||
|
||||
**Traps.**
|
||||
- **`CultureInfo.CurrentUICulture` set inside an `async` start does not reach later dispatcher operations.** A resource
|
||||
accessor with no explicit `Culture` follows whichever thread asks. Give every string family its culture explicitly.
|
||||
- **`TargetResolver` counts a process it cannot read, and zero readable + some unreadable is not "ambiguous".** A test
|
||||
against a real protected process exists (`csrss.exe`); it needs no fixture and runs elevated or not.
|
||||
- **`Mutex` is thread-affine**: `SingleInstance` is claimed and disposed on `Main`'s thread; its tests are synchronous
|
||||
on purpose.
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
# HANDOFF history — 0.1.0-beta.5 (2026-09-22)
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-22 — the override withdrawn; a finding turns hooking off; Tier 2 exists; a moved drive is followed
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.5]`; this is what no other file carries.*
|
||||
|
||||
**Decision (D23, owner: "Tier 2 does not work — what does it record, and show it").** Tier 2 is now a held session
|
||||
(`04_CAPTURE` §Tier selection): duration, telemetry and the reason, saved under the same 30 s rule as Tier 1. **Two
|
||||
choices inside it that a later session may want to revisit:** (a) *every* library row is still watched, so a
|
||||
hooking-off game accumulates play-time rows — the documented behaviour (`06_DATA_MODEL` "0 = Tier 2"), kept; the
|
||||
alternative, watching only rows the user enabled or FrameLedger itself disabled, is one predicate in
|
||||
`CaptureOrchestrator` and a doc change; (b) a hooking-off row is decided BEFORE the process is opened, so an
|
||||
elevated utility in the library (the owner's Borderless Gaming) is a quiet Tier-2 row rather than a red notice — and
|
||||
`SteamLibrarySource.KnownTools` keeps the next import from adding one. The owner's existing Borderless Gaming row is
|
||||
theirs to remove.
|
||||
|
||||
**Decision (D24, owner: "handle the drive changing its letter while the data does not").** A row may follow its
|
||||
executable to another drive-letter root when the file is gone from the row's path and exactly one other root holds a
|
||||
file with the same size and mtime — with consent, block and detection kept (`19_SAFETY` §A moved drive is the same
|
||||
executable). Three callers: the 15 s sweep, the watcher's file-name match, the enable-hooking command. The owner's
|
||||
log of the same morning is the case: 46 rows unreadable on `D:` while the drive sat on `H:`, GF2 and ELDEN RING
|
||||
running from `H:` "BY FILE NAME ONLY". ~~**Not done, on purpose:** re-import does not merge a duplicate row an earlier
|
||||
re-scan created at the new path (`LibraryImporter` still dedupes on path); the relocator refuses to move onto a path
|
||||
another row owns and says so in the log.~~ **Done 2026-09-23 (D26/D27, the beta.6 section below):** twins with the
|
||||
same bytes merge, a changed file is followed with hooking off, and the import no longer adds a twin.
|
||||
|
||||
**Trap.** `FakeIdentity` in three test classes answers the same fingerprint for ANY path; a relocation test needs one
|
||||
that answers per path, or the "exactly one candidate" rule reads every root as a match.
|
||||
|
||||
**Decision (D22, owner).** The per-game guard override (D18) is withdrawn entirely — the owner's words: a switch that
|
||||
can be turned on and still does nothing is meaningless. In its place a finding about the game turns that game's hooking
|
||||
off, at the pre-scan (as before), at a session's start and at the 30 s re-scan (new): `19_SAFETY` §What a finding does to the game.
|
||||
Machine-wide drivers and services refuse the session only. D18 and D21's "the bypass stops there" are history; D21's
|
||||
fact stands.
|
||||
|
||||
**Traps.**
|
||||
- **Removing an enum value that is LAST on both sides of the ABI renumbers nothing**, and `GuardMirrorTests` fails until
|
||||
the native DLL in the test output is rebuilt (`./build.ps1 native`) — it looks like a managed defect and is not.
|
||||
- **The first `DROP COLUMN` migration.** SQLite ≥ 3.35 is asserted in `LedgerDatabaseTests`. The test helper
|
||||
`RewindSchemaAsync` deletes `schema_migrations` rows and leaves columns in place; a rewind to below 8 followed by a
|
||||
re-migration would run 0008 against columns that are gone. Today it rewinds to 2 and never re-migrates.
|
||||
- **Meziantou MA0004 fires on the SECOND await of a test method** once a lambda inside it used `ConfigureAwait(false)`.
|
||||
- **A patch script must not carry `\r\n` inside a bash heredoc**; the helper module is written with the Write tool.
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# HANDOFF history — 0.1.0-beta.6
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-23 — the beta.6 train: a file name is not an identity, one entry per executable, Tier 2 shown live
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.6]`; this is what no other file carries. The owner's list and the
|
||||
evidence behind each item are in the approved plan the PRs cite; the decisions it took are D25–D28.*
|
||||
|
||||
**Decision (D25, owner: "HELLO, HELLO WORLD! was recorded as Flower in Us, twice").** A file name is not an identity:
|
||||
a process that matches an entry by file name only starts nothing unless the relocator moves that entry to it, and the
|
||||
relocator accepts only the entry's own path with its drive letter changed. The stranger session is gone (it created a
|
||||
wrongly-named entry through `SessionRecorder`'s `EnsureAsync`); the running table is keyed by executable path; the
|
||||
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. *(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
|
||||
entry's file is gone, the other entry holds the same path on another letter, and the file there has the bytes the
|
||||
stale entry recorded. The entry made first stays; the other's sessions join it; a block or a crash auto-disable in
|
||||
force is kept; no consent moves between them; it waits while a session of either runs or waits to be recovered
|
||||
(`CaptureOrchestrator.IsRecording`, `IPartialSessionStore.PendingGameIds`). `19_SAFETY` §A moved drive has the rules,
|
||||
`06_DATA_MODEL` the writer. The import no longer adds a twin: a store's executable that is a library entry's path on
|
||||
another letter, with that entry's file gone, is shown "in the library under another drive letter" and skipped.
|
||||
**D27 (owner, same day):** when the only file at the entry's path on another letter has other bytes, the entry follows
|
||||
it with hooking off (`ChangeExecutableAsync`, the *Change executable* write). Other bytes under a twin are NOT merged
|
||||
— the log says once which entry to remove.
|
||||
|
||||
**Traps.**
|
||||
- **`IGameMerge` is a second writer that can delete a `games` row.** Only the relocator calls it; a test that removes
|
||||
rows under a running session must expect the merge to wait (busy), not to race it.
|
||||
- **Python patch scripts: `\"` inside a normal triple-quoted string is an escaped quote**, so `@"C:\"` silently loses
|
||||
its backslash and the replace finds nothing (or worse, writes the wrong text). Use raw strings (`r"""…"""`) for C#.
|
||||
- **`FakeIdentity` in `CaptureOrchestratorTests` answers every path with the same bytes — which is exactly the hazard
|
||||
D25 closed**, so it is the right fake for "identical bytes in another folder are another game" and the wrong one for
|
||||
any test that needs a relocation to succeed (use `ExecutableRelocatorTests.DiskByPath`).
|
||||
- **A background service that throws stops the Agent's host, and until 2026-09-23 it said so nowhere.** The Generic
|
||||
Host's default `BackgroundServiceExceptionBehavior` is `StopHost`, and `ServeAsync` never routed
|
||||
Microsoft.Extensions.Logging into Serilog, so the reason reached no file. `WatcherHostedService` runs recovery before
|
||||
the watcher: one `.partial` whose finalize threw would have stopped every start, and the App would have started a new
|
||||
Agent into the same failure each time. `PartialRecovery` never throws now, and the host logs through `AddSerilog`.
|
||||
- **Removing an entry while its game runs used to lose the session.** Both of the owner's GIRLS' FRONTLINE 2 faults
|
||||
were a removal (to clean up an `H:` twin) under a running session. The finalize now resolves the owner; a test that
|
||||
deletes a row mid-session must expect `GameRemoved` or a re-keyed row, never an exception.
|
||||
|
||||
**Tier 2 on the wire (item 4a, owner: "capture still does not show when some titles are launched").** `SessionStarted`
|
||||
is published ONCE per session — at the attach, or at a held session's first tick carrying `hold` — so the card never
|
||||
flickers between tiers; a held session's 1 Hz is `SessionHeld`, never `SessionProgress` (its required fields would put
|
||||
zeros that look measured on the wire); the refusal's event goes out when the hold begins and is not repeated at the
|
||||
end; a faulted session completes with `finalize: faulted`. Every list of running sessions the App keeps is seeded from
|
||||
the status at each connect (`07_IPC` §Client behavior). All fields are additive: `IpcProtocol.Version` stays 2.
|
||||
|
||||
**Traps.**
|
||||
- **Only `hold` means held.** The status lists every session that has not attached yet at tier 2 (beta.5's shape,
|
||||
kept), so a tier-2 `ActiveSession` without `hold` is a session STARTING. The card shows its name and badge and
|
||||
nothing else; "nothing is measured" and "Attached — waiting for the first frames…" would both be false there.
|
||||
- **`sed -i` in this machine's Git Bash writes a CRLF file back as LF.** Twice on 2026-09-23 a one-line `sed -i` turned
|
||||
a test file into `w/lf` (`git ls-files --eol`), which `dotnet format` then fails on for no visible reason. Check
|
||||
`git ls-files --eol -m -o --exclude-standard | grep -v w/crlf` after any shell edit; `unix2dos` repairs it.
|
||||
- **Heredocs that carry C# with nested quotes can fail to parse in the Bash tool** ("unexpected EOF while looking for
|
||||
matching `'`") even when quoted `<<'EOF'` — write the script with the Write tool and run it by path, as the traps
|
||||
above already say for patches.
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# HANDOFF history — 0.1.0-beta.7 (the recording switch)
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-23 (after 0.1.0-beta.6) — the recording switch
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.7]`; this is what no other file carries.*
|
||||
|
||||
**Decision (D29, owner: "the Agent records Borderless Gaming although hooking is off, and it starts with Windows —
|
||||
propose an ignore list, a disable, or something suitable").** Both, as one mechanism: a per-entry **Recording**
|
||||
switch (`games.record_sessions`, schema 0009, FR-1.6) the user owns, and the import's known-tools list
|
||||
(`SteamLibrarySource.KnownTools`) applied once to the entries an earlier import made, which start with it off. Off
|
||||
means the program is not watched at all (the watchlist is the entries whose recording is on), a running session of it
|
||||
stops at the next poll, and `LaunchGame` answers `RecordingOff`. Not chosen: a hard-coded list the watcher consults
|
||||
(no user control, and a list is never complete), and D23's recorded alternative of recording Tier 2 only for entries
|
||||
hooking was once enabled for (it would take back the Tier-2 sessions the owner asked for). The Privacy Policy (2.3) and
|
||||
the Disclaimer (2.6, whose accuracy block also carries #224's correction) were bumped with the owner's leave ("sửa docs
|
||||
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. *(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
|
||||
twin merge reads its own columns — both had to learn `record_sessions`.
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# HANDOFF history — 0.1.0-beta.8
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-25 — the beta.8 train
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.8]`; this is what no other file carries. The owner's list
|
||||
(eight items: the anti-cheat set as large and strict as possible, hiding the hook part for anti-cheat games, more
|
||||
metadata, NVIDIA App overrides, clearer reasons, a working Trend, FPS decimals, chart fixes) is planned as nine PRs in
|
||||
one approved plan; each PR cites it.*
|
||||
|
||||
**Decision (D30, owner, asked before any code: "which strict rules, beyond named tokens?").** Two of three: **any
|
||||
kernel driver (`*.sys`) inside a game's install tree** is a finding (code, not data — `kKernelDriverInTreeFamily`),
|
||||
and **per-title lists** (30 Steam ids, 33 executables across nine families, floored like the families). **Not** the
|
||||
AreWeAntiCheatYet bulk import (~250 Steam ids): community data that keeps listing a game after it drops its anti-cheat
|
||||
would turn hooking off for good, since nothing clears a block. Recorded because the next person to "expand the list"
|
||||
will find that import one search away.
|
||||
|
||||
**Decision (D31, owner): the store half's matrix.** Listed → refuse; no store identity (a loose folder, an Epic
|
||||
install, a Steam folder no manifest names) → not applicable, recorded as nothing; a store layout whose metadata cannot
|
||||
be read → refuse (`PreScanFailed`). §S14's "unknown must never read clean" is kept by the third row; the second is not
|
||||
an unknown — it is the answer "this is not a store title", and refusing it would be the gate that cannot pass.
|
||||
|
||||
**Decision (D32, owner, item 2: "an option to hide the hook part for games with anti-cheat").** Hide **and** scan:
|
||||
the Agent pre-scans every library entry itself (`AntiCheatPreScanSweep`, checks 3 and 4, once per rules version and
|
||||
executable — schema 0010's key), a finding is the same block every other moment writes, and the game's page shows
|
||||
the finding in place of the Hooking card while `ui.hide_anticheat_hooking` is on (default on). Tier 2 is still
|
||||
recorded. **Why not the setting alone:** most entries sat at `hook_prescan_state = 'not_run'` — the pre-scan ran only
|
||||
when someone asked for hooking — so a hide keyed on a finding would have hidden nothing on most libraries. **What it
|
||||
must never become:** a gate. The chokepoint runs checks 1–4 at every session start whatever the sweep wrote; the sweep
|
||||
only answers early, writes through the consent store's block-preserving `UPDATE`, and hides a control that could
|
||||
only be refused, never the finding (FR-2.2).
|
||||
|
||||
**Traps.**
|
||||
- **`Rules` is ~650 KB now** (256 families, 128 per-title rules). `x = Rules{}` builds that on the stack before
|
||||
copying — use `ResetRules`. The Vulkan layer parses on a game's own `vkCreateInstance` thread, and native tests hold
|
||||
it on the heap (two in one test function overflowed the 1 MB default).
|
||||
- **New `anticheat.modules` rows go at the END.** The Overlay's early stop reports a 1-based index into that order, and
|
||||
`sessions.early_stop_family` stores it.
|
||||
- **`sed -i` and the Bash tool's heredocs strike again**: a heredoc halved `\\` in a Python patch (a C# verbatim path
|
||||
still matched by luck), and a one-line `sed -i` turned `layer.cpp` into LF. Scripts go through the Write tool and run
|
||||
by path; `git ls-files --eol -m` after any shell edit.
|
||||
- **`'clean'` is not new.** `AgentCommandHandler` has stamped it on every consented enable since P3; the sweep adds it
|
||||
for entries nobody enabled. Nothing gates on it — a reader that treats `'clean'` as "may hook" is a second gate.
|
||||
- **The sweep's notice is not a refusal.** `HookingTurnedOff` is `SafetyNoticeKind.HookingOff` with Dismiss: a
|
||||
`Refused` kind would offer "record this session without measuring it" with no session running.
|
||||
- **Analyzers on tests:** CA2000 flags a disposable passed into a record's constructor (construct it inside a class
|
||||
that disposes it), MA0023 a regex with numbered groups (name them), CA1062 a `[Theory]` string parameter
|
||||
dereferenced without a check.
|
||||
- **`exe_machine` NULL is stale (schema 0011).** The detection sweep re-reads any row whose executable facts this build
|
||||
has not written — so a test double of `IGameRepository.ApplyDetectionAsync` that drops the new fields makes every
|
||||
sweep test re-scan forever. `unknown` is the stored "looked, could not tell".
|
||||
- **`FileVersionInfo` on a System32 file reads its `.mui`.** `version.dll` read in place said 6.2.x, its copy in a temp
|
||||
folder 10.0.x: compare a version against the file that was read, never against its source.
|
||||
- **`PASS_REGULAR_EXPRESSION` alone makes ctest ignore the exit code.** `fl_nvapi_bridge` passed for weeks with a failing
|
||||
assertion on every GPU machine (CI has no driver, so never took the branch). Any test that must print a line AND
|
||||
pass needs a `FAIL_REGULAR_EXPRESSION` beside it; running the test binary directly is the check.
|
||||
- **A C ABI cannot give a function and a struct one name** (`FlNvDriverProfile` the export, `FlNvDriverProfileRead` the
|
||||
struct): C puts typedefs and functions in one namespace, and MSVC's error names neither clearly.
|
||||
- **The driver profile is a configuration.** `sessions.driver_profile` says what the NVIDIA App set; it never feeds
|
||||
the upscaler ladder or the factor. The bridge has no DRS writer, and a PR that adds one is a different product.
|
||||
- **Present-to-present is not a frame time on a frame-generation title.** DLSS FG submits its generated frames in a
|
||||
burst (measured: half a millisecond apart on the owner's Onimusha capture); anything over `ft_app` — lows, median,
|
||||
σ, stutter, the charts' default line — is application frame to application frame (`FrameTimeSeries.ApplicationFrames`,
|
||||
`SessionSeriesLoader.ApplicationFrames`).
|
||||
- **A gap is neither a frame time nor time** (beta.8): `FrameTimeSeries.MeasuredSeconds` and `FgWindow.Seconds` leave
|
||||
out every interval a gap sat in. A pause is a gap (`CaptureSession.MarkResume`); do not mark one any other way.
|
||||
- **Reading the owner's ledger for evidence: copy it (`ledger.db` + `-wal`) to the scratchpad and read the copy** with
|
||||
plain SQLite — never a FrameLedger binary against the data folder. `capture_tier` is an integer (1 = hooked); the
|
||||
frame flags are Generated = 1, Gap = 4.
|
||||
- **A view model that loads in its constructor raises its events to nobody** until the page subscribes; a page must
|
||||
draw what the view model already holds when it is made (the Trend tab was blank on every first open).
|
||||
- **`Axes.DateTimeTicksBottom()` replaces the bottom axis**: call it before the theme and the label, or both are lost.
|
||||
- **A local property value outranks a style trigger** (Compare's best cell was never accent-coloured): defaults a
|
||||
trigger may change go in the Style as Setters.
|
||||
- **`ui.fps_decimals` is process-wide state** (`FpsDecimals`): a test that moves it belongs to `StringsCultureCollection`
|
||||
with every test that reads FPS text, and restores it.
|
||||
- **A status is not a policy input.** Splitting End task (exit 1) out of `crashed` would have loosened the crash
|
||||
auto-disable had the policy kept reading the status alone; it takes the exit code too. Check every reader of a value
|
||||
whose meaning you narrow.
|
||||
- **The gate's own refusals carry a label in the family slot** (`not enabled`, `no consent`, `kill switch`, `previously
|
||||
blocked`, `HookedCaptureGate`), so "has a family" does not mean "is a finding" — `IsFindingAboutTheGame` is the test.
|
||||
- **`add_strings.py` replaced an existing key in place** (`Exit_Normal`, the Sessions grid's word) — it now refuses
|
||||
without `--replace`; diff the resx for `-.*<value>` before committing new strings.
|
||||
- **A 32-bit refusal is not a block.** `ExecutableNotX64` writes nothing — no `hook_blocked_reason`, no stamp — so a
|
||||
64-bit build of the same game under *Change executable* can be hooked; the sweep's turn-off uses
|
||||
`hook_autodisabled_reason`, which the page does not offer to undo while the file is still 32-bit.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# HANDOFF history — 0.1.0-beta.9
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 2026-09-26 — the beta.9 train: the user-mode exception (D33)
|
||||
|
||||
*Status is `CHANGELOG.md` `[0.1.0-beta.9]`; this is what no other file carries. The approved plan
|
||||
is four PRs: PR-1 the guard's tolerance and the Overlay's channel, PR-2 the Agent (eligibility, gate, records, schema
|
||||
0014, IPC), PR-3 the App, strings, docs and legal text, PR-4 the release.*
|
||||
|
||||
**Decision (D33, owner, 2026-09-26, asked with rule 2 and D22 quoted back).** The beta.8 sweep turned hooking off for
|
||||
GIRLS' FRONTLINE 2: EXILIUM (NetEase Yidun, `AntiCheatFile NEP2.dll`, a documented and unmeasured rule) after it had
|
||||
been measured hooked; the owner asked for an exception list for user-mode anti-cheat games measured at Tier 1 before.
|
||||
Chosen, all four options as recommended: **evidence-bound, per game** (a Settings option off by default, then the user
|
||||
ticks each eligible game); **≥ 2 successful Tier-1 sessions**; **Aniimo stays blocked** (it unpacks `NEPKernel.sys` beside
|
||||
`NEP2.dll` — the D30 `.sys` rule is never excepted); **the legal text changes** (Disclaimer §2A 2.7, EULA 1.3, the
|
||||
accuracy block, SECURITY.md, FR-2.3; Privacy stays 2.4). Eligibility, what is never excepted and every lapse are in
|
||||
`19_SAFETY` §The user-mode exception; the rule-2 amendment is in CLAUDE.md.
|
||||
|
||||
**Evidence it rests on (read from a COPY of the owner's ledger and their logs, 2026-09-26).** GF2: three normal Tier-1
|
||||
sessions under the current entry (474,143 frames; three more from 2026-09-21 went with a removed entry), no `.sys` in
|
||||
its tree. Aniimo: one Tier-1 session stored `crashed` (End task before beta.8, no exit code kept). A randomly named
|
||||
kernel driver (`lyoxztfx.sys`) was installed on 2026-09-21 at 15:38 and is gone now, service and file, by something
|
||||
the logs cannot name — the residual the disclosure states: a driver outside the game folder that no rule names is
|
||||
invisible to every check.
|
||||
|
||||
**Traps met on the way:**
|
||||
- **The ring cannot carry anything the Overlay needs before its detour is armed** — the Overlay creates it. Hence the
|
||||
separate `Local\FrameLedger.Tolerate.<pid>` mapping the Agent creates BEFORE the injection (`fl_tolerance.h`).
|
||||
- **A tolerant scan must keep scanning.** Every sink that used to stop at the first hit returns `true` on a tolerated
|
||||
one, or a second family / a `.sys` further in would pass: the same load-order fail-open §S22(b) closed for the
|
||||
exemption.
|
||||
- **A prefix value of a user-mode family can match a `.sys`**; the tolerant file sink refuses any `.sys` itself.
|
||||
- **CA2101 rejects `[MarshalAs(LPUTF8Str)] string`** on a P/Invoke; the tolerance crosses as NUL-terminated UTF-8
|
||||
`byte[]`, the shape `FlGuardCheckRules` already used.
|
||||
- **The Vulkan branch evaluates strictly**: the layer's self-scan goes inert on any anti-cheat module, so an exception
|
||||
there could only buy a session that measures nothing.
|
||||
- **An elevated Agent's default DACL omits the user** (`PipeAccessControl`'s remarks): a tolerance mapping created with
|
||||
it could not be opened by the Overlay in an unelevated game, and the exception would fail as the Overlay's own stop.
|
||||
`OverlayToleranceChannel` states `O:<user>D:P(A;;GR;;;<user>)`; a test proves the user can read it and nobody can
|
||||
open it to write.
|
||||
- **`hook_enabled` can be 1 on a blocked row now** — only because an exception once applied. `CaptureSession.RunAsync`
|
||||
therefore treats a blocked row whose exception does not apply right now as hooking-off BEFORE the resolver opens
|
||||
anything, or the option off would reopen the Borderless-Gaming problem of 2026-09-22.
|
||||
- **The store applies the eligibility rule itself** (`GrantAntiCheatExceptionAsync` answers `NotEligible`), and the
|
||||
grant and the eligibility are bound in SQL to the block text they were reached about: a block rewritten between the
|
||||
read and the write leaves the row alone. SQLite evaluates every `SET` from the old row, which is what lets
|
||||
`ChangeExecutableAsync`'s `CASE WHEN ac_exception_at IS NOT NULL` record the end of the grant it clears.
|
||||
- **CA1711 rejects a type whose name ends in `Exception`**: the rules class is `UserModeExceptionRules`, the reasons
|
||||
`UserModeExceptionLapse`.
|
||||
|
||||
@@ -0,0 +1,677 @@
|
||||
# HANDOFF history — Where P0 stands; the queue, items 1–6
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## Where P0 actually stands
|
||||
|
||||
**P0 is closed (owner, 2026-09-06).** Both criteria read as met in `spike-notes.md`
|
||||
§Exit criteria — criterion 1 with the quality preset amended to an honest `N/A`,
|
||||
criterion 2 with §S24 counting zero S-items against it (🚫 S23-2 is a GitHub setting
|
||||
outside any PR). **What comes next is P1** (`15_ROADMAP` §P1): the Overlay proper —
|
||||
hook installation for D3D11/12/9/OGL, the `LoadLibrary` detour that §S6's early stop
|
||||
and lazily loaded runtimes both hang on, unhook path, native logging; the Injector's
|
||||
launch mode (§S13(c), §S1's deferred input); the Vulkan layer to `vkQueuePresentKHR`
|
||||
with §S2's in-layer supervision. **P1 item 1 — the `LoadLibrary` detour — landed 2026-09-06
|
||||
(§S6 ✅); item 2, launch mode, landed the same day as "inject late" (§S1 ◐, §S13(c) ✅ —
|
||||
`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~~.** *(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.
|
||||
|
||||
Two exit criteria ~~remain~~ were the gate (`spike-notes.md` §Exit criteria). Do not re-derive them
|
||||
from memory:
|
||||
|
||||
1. **A throwaway build records a real session** from a real offline game reporting
|
||||
*correct* upscaler, quality preset, render→output resolution, FG factor and RT
|
||||
state, verified against the game's own settings menu.
|
||||
2. **Every S-series item resolved, or explicitly deferred with a written rationale.**
|
||||
|
||||
Criterion 2's count is in §S24's summary and is kept current there. Criterion 1 needs
|
||||
the feature hooks below.
|
||||
|
||||
> **What changed on 2026-08-06, in one sentence, because it changes the shape of
|
||||
> criterion 1 rather than its content:** there is now a path from a consent record to a
|
||||
> drained session, driven by a real binary, so "a throwaway build records a real
|
||||
> session" needs feature hooks **and nothing else**. The queue's item 1 is struck
|
||||
> below for that reason.
|
||||
|
||||
---
|
||||
|
||||
## The queue, in dependency order
|
||||
|
||||
Each entry names the acceptance criterion and **what makes it fail on unmodified
|
||||
`main`** — because a criterion already true on `main` is decoration, and this project
|
||||
has shipped three of those.
|
||||
|
||||
> ### Before you start: two things about this machine, neither of them the code
|
||||
>
|
||||
> 1. ~~**`./build.ps1 check` cannot go fully green here.** `fl_d3d12_acquisition` and
|
||||
> `fl_guard`'s D3D12 case fail because WARP's D3D12 path is broken on this Windows
|
||||
> Insider build — measured, persistent across a reboot, and detailed in §Traps.~~
|
||||
> **NO LONGER TRUE, measured 2026-08-20: `./build.ps1 check` is fully green here, 20/20
|
||||
> native tests.** `hook-harness --probe-d3d12` succeeds and `D3D12CreateDevice` on the WARP
|
||||
> adapter returns `S_OK`. **Nothing in this repository fixed it** — the machine moved from
|
||||
> Insider build **26300/29639** to **29648**, and `d3d10warp.dll` / `D3D12Core.dll` are both
|
||||
> `10.0.29648.1000`, so the Insider-build regression §Traps describes was fixed upstream.
|
||||
> Recorded with both build numbers because "it works now" without them is the same
|
||||
> unfalsifiable claim as the untested remedy §Traps already records. **Check it on your own
|
||||
> build before planning around either state.**
|
||||
> 2. **The managed suite is green and was stabilised the hard way.** Ten consecutive full
|
||||
> runs at the time of writing. Five assertions in `ShmDrainIntegrationTests` /
|
||||
> `CaptureHostEndToEndTests` had budgets sized on the harness's measured rate or read a
|
||||
> state once; #61 and #62 fixed them, and §Traps records the shape so the next one is
|
||||
> recognised rather than re-derived.
|
||||
|
||||
### ~~1. Consent store + the first production driver of the guard loop~~ — LANDED 2026-08-06
|
||||
|
||||
**Do not start here.** The whole of this entry is built: `IGameConsentStore` with a
|
||||
file-backed adapter, `FrameLedger.CaptureHost` driving `HookedCaptureGate` →
|
||||
`FlGuardedInject` → `ShmRingReader.TryAttach` → a 10 Hz drain with
|
||||
`GuardSupervisor.ScanOnceAsync` and `PublishGuardResult`, §S29(c) closed by deleting
|
||||
`ShouldUnhookAsync`, §S29(e) closed with a held process handle, the throwaway consumer,
|
||||
and all three test gaps. **The head of the queue is item 2.**
|
||||
|
||||
What it does *not* move: items 4, 6 and 7 still need feature hooks. The writer still
|
||||
records `measuredMask = FL_MEASURED_OUTPUT_RES | FL_MEASURED_PRESENT_ARGS` and nothing
|
||||
else, and the consumer reports `N/A` for upscaler, FG and RT because that is what the
|
||||
data says. What it moves is the *path*: there is now a route from a consent record to a
|
||||
drained session, so exit criterion 1's throwaway build needs hooks and nothing else.
|
||||
|
||||
Status lives where it lives — `CHANGELOG.md` and §S24 — and this entry is struck rather
|
||||
than deleted because **the sequencing claim is what this file is allowed to carry, and
|
||||
the sequencing changed.** Leaving it queued would tell the next session to build what
|
||||
already exists, which is the failure this file's own rule exists to prevent, one level
|
||||
up: it went stale by *not* being touched.
|
||||
|
||||
Two things from it are still open and are the owner's:
|
||||
|
||||
- **Six decisions surfaced by building it**, listed in §S24 — who may clear
|
||||
`hook_blocked_reason`; whether the operator acknowledgement's wording is reviewed like
|
||||
a `Safety_*` string; whether FR-2.4's kill switch is an input to `HookedCaptureGate`;
|
||||
whether FR-11 gates consent; whether §S18 blocker 3 is re-ratified now that a third
|
||||
project imports the guard; and the disclosure/wording version, which was **decided and
|
||||
implemented** because it cannot be retrofitted — reversing it is still the owner's.
|
||||
- **`tools/package-closure-check.ps1` reads `ProjectReference` only.** It is what keeps
|
||||
§S27 closed, and it does not follow `<Import>` or `Directory.Build.props`, so a
|
||||
`.targets` file that stages a foreign binary into a publish root's output is outside
|
||||
what it sees. Stated here because the next person to widen the packaging story needs
|
||||
to know the shape of the hole rather than discovering it.
|
||||
|
||||
<details>
|
||||
<summary>The original entry, kept for the reasoning it carries</summary>
|
||||
|
||||
The layer under everything else, and the answer to §S27.
|
||||
|
||||
- `IGameConsentStore` (Application port) + a file-backed implementation. This gives
|
||||
`HookedCaptureGate`'s three inputs — `hook_enabled`, `hook_consent_at`,
|
||||
`hook_blocked_reason` — a **real source** for the first time. §S27 rejects
|
||||
*synthesising* them; a record written by an explicit user action is not synthesis.
|
||||
- A capture host driving `HookedCaptureGate` → `FlGuardedInject` →
|
||||
`ShmRingReader.TryAttach` → ~10 Hz drain + `GuardSupervisor.ScanOnceAsync` +
|
||||
`PublishGuardResult`. **A separate project, not `FrameLedger.Agent`**: `12_BUILD`
|
||||
publishes only `FrameLedger.App` and `FrameLedger.Agent`, so a project neither
|
||||
references is outside the package *by construction* rather than by a flag. Stage the
|
||||
Overlay and guard beside it for §S22, as `FrameLedger.DrainFixtures.targets` already
|
||||
does for the integration test.
|
||||
- **This is the first production driver of `guardTicks`** — the *sending* half of the
|
||||
30 s re-scan that `19_SAFETY` calls the most important runtime behaviour and that
|
||||
`README` already promises. Both the write path (`ShmRingReader.PublishGuardResult`)
|
||||
and the read path (the Overlay watchdog) exist and are tested; only the loop is
|
||||
missing. **A missing loop reads as a missing subsystem — say "loop".**
|
||||
- **Close `HookedCaptureGate.ShouldUnhookAsync`** (§S29(c)). It is a *second*
|
||||
in-session re-scan path that publishes no tick and does not latch — the two
|
||||
properties `GuardSupervisor` exists to guarantee — it is unit-tested so it reads as
|
||||
sanctioned, and it sits on the object this loop will already be holding. Route it
|
||||
through `GuardSupervisor` or delete it.
|
||||
- **Session-end detection** (§S29(e)): `ShmRingReader` holds the section open, so an
|
||||
exited game leaves `writeIndex` frozen and `status` `READY` — byte-identical to a
|
||||
loading screen.
|
||||
- **A throwaway consumer**, minimum form only: `measuredMask` → rule 7 tri-state,
|
||||
`fg_factor = F_disp / F_app`, and **segmentation** (`03_METRICS` §Upscaling requires
|
||||
a mid-session settings change to split the session; the record was designed for the
|
||||
Agent to segment by `swapchainId`). Not P2's SQLite.
|
||||
- Three cheap test gaps in reach: `SetPaused` has **no test at all** though both halves
|
||||
exist and the harness is staged; the pause round trip is never exercised; the drop
|
||||
path is asserted *absent* (`TotalDropped == 0`) rather than driven against the real
|
||||
native writer.
|
||||
|
||||
*Fails on main because:* there is no consent record, no host, and no path from
|
||||
`HookedCaptureGate` to a drain. Assert `ConsentMissing` with `FlGuardedInject` **never
|
||||
reached**, and `guardTicks` advancing from a non-test binary.
|
||||
|
||||
</details>
|
||||
|
||||
### ~~2. Upscaler hooks + a harness that speaks the vendors' symbol names~~ — IDENTITY LANDED 2026-08-09
|
||||
|
||||
**Do not start here for identity.** `sl.interposer.dll!slEvaluateFeature` is hooked,
|
||||
module-scoped, installed lazily by the watchdog, and proven firing inside an injected
|
||||
target. The stub DLLs, the decoy, `tools/hookinventory-check.ps1` and the Streamline
|
||||
MIT vendoring all landed with it. Status is in `CHANGELOG.md` and §S24.
|
||||
|
||||
**What is still open from this item is the params half, and it is now item 2b below —
|
||||
designed, refuted, and not built.** `FL_MEASURED_UPSCALER_PARAMS` has no producer, so
|
||||
quality and render → output resolution are absent, which is exactly what P0 exit
|
||||
criterion 1 needs. The route this repo documented for years is **licence-blocked**:
|
||||
`NVSDK_NGX_Parameter_SetUI` needs NGX declarations, and the NGX/DLSS SDK is the
|
||||
proprietary RTX SDKs Licence, so `18_GPU_VENDOR_APIS` §Checklist step 3 forbids both
|
||||
vendoring it and re-declaring it. `17_HOOK_ENGINE` §The NGX parameter surface carries
|
||||
that reasoning; **§2b carries which in-policy route to take and, more importantly, which
|
||||
one to refuse.**
|
||||
|
||||
**Two corrections to what this entry used to say**, kept because the entry was the
|
||||
trap it was warning about: it named `NVSDK_NGX_EvaluateFeature`, which **no measured
|
||||
module exports** — the real symbol is `NVSDK_NGX_D3D12_EvaluateFeature` — and it said
|
||||
four modules where the measured answer is **seven** (`nvngx_dlss`, `nvngx_dlssd`,
|
||||
`nvngx_dlssg`, `nvngx_deepdvc`, `sl.common`, `_nvngx`, `nvngx`). The argument was
|
||||
untouched by both errors; the data was wrong in the bullet whose whole subject is that
|
||||
a wrong symbol name degrades silently.
|
||||
|
||||
<details>
|
||||
<summary>The original entry, kept for the reasoning it carries</summary>
|
||||
|
||||
Item 4's primary hook class. **Streamline first** (owner decision); NGX-direct is its
|
||||
own PR with its own rule-4 justification.
|
||||
|
||||
- Stub DLLs exporting the **exact** names from `docs/vendor-exports.json` (measured
|
||||
data, not vendor SDK) + a harness mode that calls them with known values.
|
||||
`17_HOOK_ENGINE` calls a wrong symbol name degrading silently to `unknown` the
|
||||
highest false-confidence risk in the spike, and nothing tests it.
|
||||
- **Module-scoped** resolution. `NVSDK_NGX_EvaluateFeature` is exported by **four**
|
||||
modules on the dev machine (`sl.common.dll`, `nvngx.dll`, `_nvngx.dll`,
|
||||
`nvngx_dlssg.dll`); a name-resolved hook without scoping double-counts FG
|
||||
evaluations, straight into `fg_factor`.
|
||||
- **The vehicle for "the first time their module appears" already exists**: the
|
||||
watchdog thread runs once a second. No `LoadLibrary` hook is needed for P0 — which
|
||||
keeps §S6 genuinely separable. The Overlay has **no** module-resolution machinery
|
||||
today (`GetProcAddress`/`GetModuleHandle` appear nowhere), so that helper is part of
|
||||
the real cost. *(2026-09-06: the detour exists now — P1 item 1 — and it still only
|
||||
WAKES that thread; the installers did not move. `17_HOOK_ENGINE` §DLL entry step 3.)*
|
||||
- `tools/hookinventory-check.ps1`: every symbol the Overlay resolves by name must
|
||||
appear in `vendor-exports.json`. **No drift exists today** — a refuter resolved every
|
||||
inventory symbol against all 34 measured modules — so write it as prevention and do
|
||||
not claim it fixed anything.
|
||||
- Set `FL_MEASURED_UPSCALER` and `FL_MEASURED_UPSCALER_PARAMS` **separately**; that
|
||||
split exists because an NGX-direct title yields identity and nothing else.
|
||||
|
||||
</details>
|
||||
|
||||
### ~~2b. The params half~~ — LANDED 2026-08-15, and one deferral in it was overturned
|
||||
|
||||
**Do not start here.** `FL_MEASURED_UPSCALER_PARAMS` has a producer. Status is in
|
||||
`CHANGELOG.md` and §S24; what belongs here is the **sequencing that changed** and the
|
||||
**decisions that live in no other file**:
|
||||
|
||||
- **`slSetTag` was deferred by the entry below and is IN.** The deferral reasoned that a
|
||||
globally-tagging title "yields nothing from this PR — not a regression, not a fabrication".
|
||||
Measured, that risk is the common case rather than the edge: `sl_core_api.h:258` documents
|
||||
the local tags in `inputs` as merely *allowed*, and **only 4 of the 10** Streamline titles
|
||||
installed here ship `sl.dlss.dll` at all. An inputs-only producer could have shipped with a
|
||||
hit rate of zero, and nothing would have found out until a real-title run.
|
||||
- **Both tag paths are read, and they are alternatives rather than layers.** Global
|
||||
(`slSetTag`) and local (`slEvaluateFeature`'s `inputs`) do not interact — the vendor says so
|
||||
in as many words — so a title using one yields nothing from the other. Local wins when
|
||||
present: it is scoped to the evaluation, so it cannot be older than the frame.
|
||||
- **`sl_dlss.h` is vendored** (ten headers now), so `upscalerQuality` carries the vendor's own
|
||||
`DLSSMode`. **`upscalerSharpness` is `0xFF` permanently** — `DLSSOptions::sharpness` carries
|
||||
`SR_DEPRECATED_SHARPENING` in the header itself. That is the true value, not a placeholder.
|
||||
- **The installer was restructured first, and had to be.** The old expansion ignored
|
||||
`FL_HOOK_INVENTORY`'s `family` column and bound the first resolving row to
|
||||
`Hook_SlEvaluateFeature`. Correct with one row; with two it would have detoured `slSetTag`
|
||||
with a body that reads argument 1 as a feature id.
|
||||
|
||||
**What it does NOT deliver, so nobody plans on it:** a title that tags **whole resources**
|
||||
yields `renderW/H = 0`, the in-band unknown; a title that sets its preset through
|
||||
`slDLSSSetOptions` and never chains `sl::DLSSOptions` yields `upscalerQuality = 0xFF`. Both
|
||||
are honest absences.
|
||||
|
||||
**The hit rate is no longer unmeasured, and it SPLIT** — Cyberpunk 2077, 2026-08-15,
|
||||
`spike-notes.md` §8. The extent half works and is *exact*: `renderW/H = 1485×835` against the
|
||||
title's own `DLSS = Balanced` at 2560×1440, which is a number a writer that hardcoded a
|
||||
plausible resolution could not have produced. The `sl::DLSSOptions` half has a **hit rate of
|
||||
zero on that title** — it never chains the struct, so `upscalerQuality = 0xFF` there is a true
|
||||
property of the title rather than a bug to go hunting for. One title, one configuration;
|
||||
Alan Wake 2 is still unmeasured. **What the same run did find is a defect — §S30, and it
|
||||
belongs to item 3.**
|
||||
|
||||
<details>
|
||||
<summary>The original entry, kept for the reasoning it carries</summary>
|
||||
|
||||
### 2b. The params half — ~~START HERE~~, and the route is already decided
|
||||
|
||||
*(Archived. The live entry is above; this header's "START HERE" is struck so the file
|
||||
does not contain two of them — that ambiguity is the exact class this file exists to
|
||||
prevent, and leaving it verbatim would have been the letter of "kept unchanged" against
|
||||
its purpose.)*
|
||||
|
||||
`FL_MEASURED_UPSCALER_PARAMS` has no producer, which is what P0 exit criterion 1
|
||||
actually needs. Designed 2026-08-09 by a panel plus three refuters; **the obvious route
|
||||
was killed on fatal grounds and the reasoning is the part that lives in no other file.**
|
||||
|
||||
**DO NOT hook `slGetFeatureFunction` and MinHook the returned `slDLSSSetOptions`.**
|
||||
It is the route `17_HOOK_ENGINE` reads as natural, and it fails five ways:
|
||||
|
||||
1. It needs an "indirect" inventory class, which becomes an **unconditional escape hatch
|
||||
from `hookinventory-check` Pass A** — its oracle would be "a `PFun_*` exists in a
|
||||
vendored header", and `sl_core_api.h:63` declares `PFun_slSetTagForFrame` for a symbol
|
||||
~~zero measured modules export~~. Any name the headers declare could be laundered past
|
||||
the gate. *(2026-09-04: `slSetTagForFrame` IS now exported — by `sl.interposer.dll` 2.8.0,
|
||||
which Dying Light: The Beast ships — and it entered the inventory the ordinary way, as a row
|
||||
Pass A checks against the measured oracle. The argument stands: the point was never that
|
||||
this one symbol was fictional, it was that a header-declared oracle cannot tell the two
|
||||
apart. The oracle itself needed a fix to see it: `tools/vendor-exports.ps1` took the FIRST
|
||||
copy of each module name, and with 2.7.1 and 2.8.0 both installed the row's verdict
|
||||
depended on directory order. It unions across copies now and lists every version seen.)*
|
||||
2. A second MinHook install site **reopens the install-after-stop window**
|
||||
`dllmain.cpp:643-646` exists to close.
|
||||
3. MinHook v1.3.4 has **no function-length oracle for a runtime-returned address**, so a
|
||||
short thunk gets patched into its neighbour — a crash inside vendor code where
|
||||
`FL_HOOK_GUARD` cannot reach.
|
||||
4. `GetModuleHandleExW` with a reference is `LdrAddRefDll`, i.e. **the loader lock, on the
|
||||
game's thread, inside NVIDIA's own call.**
|
||||
5. It structurally **misses the game's first `slDLSSSetOptions` call**, which for a
|
||||
benchmark configured before launch is often the only one.
|
||||
|
||||
**DO extend the hook we already own.** `Hook_SlEvaluateFeature` is handed
|
||||
`const sl::BaseStructure** inputs, uint32_t numInputs` and today ignores both;
|
||||
`sl_core_api.h:251` documents `inputs` as carrying *"viewport, tags, constants etc"*. A
|
||||
bounded walk (cap 32 elements, 8 `next` links, match `s_structType` **and**
|
||||
`structVersion >= kStructVersion1`) reaches `sl::ResourceTag`
|
||||
(`kBufferTypeScalingInputColor` extent → `renderW/H`) and `sl::DLSSOptions`
|
||||
(`mode` → `upscalerQuality`). **Zero new inventory rows, zero new MinHook patch sites, no
|
||||
module-lifetime story, no gate changes.** The design sweep compiled and ran the walk in
|
||||
the shipped configuration: tagged extents yield 1280×720, a chained `DLSSOptions` yields
|
||||
`mode=3`, and the whole-resource case yields the honest all-zero.
|
||||
|
||||
**Three fields, three honest answers — and one of them is permanent:**
|
||||
|
||||
| Field | Answer |
|
||||
|---|---|
|
||||
| `renderW/H` | produced from local tags; **0** when the title tags whole resources, which is the in-band unknown `fl_shm.h` already defines |
|
||||
| `upscalerQuality` | from `sl::DLSSMode`, mapped so `eOff`, out-of-range and conflict all become **`0xFF`** and the byte is **never 0** — which retires `fl_shm.h:328`'s "DLSS Performance published as a measurement" worry *at the writer* |
|
||||
| `upscalerSharpness` | **cannot be measured in policy, ever, on this route.** `DLSSOptions::sharpness` is `[[deprecated("Sharpness is not supported")]]`, and `DLSSOptimalSettings::optimalSharpness` is Streamline's *recommendation*, not what the title applied. Ship `0xFF` permanently — that is the true value, not a placeholder |
|
||||
|
||||
**The sample must not latch.** Pack it in one `std::atomic<uint64_t>` consumed with
|
||||
`exchange(0)` in `RecordPresent` beside the existing `g_slSeen.exchange(0)`, so a params
|
||||
sample cannot outlive its frame. Replace the unfalsifiable "the writer must write all
|
||||
four fields" invariant with one a fixture can kill: **bit 8 set implies
|
||||
`upscalerQuality != 0` and `upscalerSharpness == 0xFF`**, asserted natively and in
|
||||
`MeasuredFacts.IsHonest`.
|
||||
|
||||
**Two things to state in the PR body rather than discover:**
|
||||
|
||||
- **The hit rate is unmeasured and it is the largest unknown.** Whether shipping titles
|
||||
chain these structures into `inputs` was not measured — the `ResourceTag` half has a
|
||||
vendor-documented mechanism, the `DLSSOptions` half does not and is likely rarer. The
|
||||
design is built so the unmeasured case is free: nothing chained ⇒ bit 8 clear ⇒ the
|
||||
record is byte-identical to today's and the consumer says N/A. **Alan Wake 2 is the
|
||||
title that settles it** (§Owner-only item 2).
|
||||
- **No gate verifies this walk.** `hookinventory-check`, `license-check` and
|
||||
`struct-mirror` all stay still — which is the route's advantage and simultaneously
|
||||
means the fixtures are the only thing standing between this producer and a silent
|
||||
wrong answer. Weight the harness modes accordingly.
|
||||
|
||||
Vendor `sl_dlss.h` **with its consumer in the same commit** (`18_GPU_VENDOR_APIS`
|
||||
records that an unconsumed vendored dependency can have an incomplete header closure with
|
||||
every gate green), and correct `THIRD_PARTY_NOTICES`' nine→ten headers and the README's
|
||||
"excluded deliberately" line in that same commit.
|
||||
|
||||
Deferred with reasons: `slSetTag` global tags (a globally-tagging title yields nothing
|
||||
from this PR — not a regression, not a fabrication), and the segmenter tuple
|
||||
`03_METRICS:133` wants, so a mid-session settings change currently degrades to N/A rather
|
||||
than cutting a segment.
|
||||
|
||||
</details>
|
||||
|
||||
### ~~3. Frame generation~~ — VALIDATED 2026-09-04 (§S31 row P1), and the item is done
|
||||
|
||||
**Do not start here.** The run landed on P1 — 1.00 / 2.99 / 3.99 on Cyberpunk's own
|
||||
off / ×3 / ×4, 4.00 on Hell Is Us — after run 1 landed on P4 and #105 keyed the count on a
|
||||
NEW frame index. `fg_factor` is published, `none` is reachable by counting, and
|
||||
`tokens/batch = 1.00` answered §S31's own question on the way. Status is in `CHANGELOG.md`
|
||||
and §S24; what belongs here is that **P0 exit criterion 1's FG factor is no longer the
|
||||
blocker** — the remaining gap in that criterion is the quality preset, a title property on
|
||||
Cyberpunk and an unmeasured one on Alan Wake 2 (Owner-only item 2).
|
||||
|
||||
<details>
|
||||
<summary>The entry as it stood while the run was owed</summary>
|
||||
|
||||
**Do not start here.** `sl.interposer.dll!slGetNewFrameToken` is the application-frame
|
||||
producer: an inventory row, a detour that counts distinct tokens between presents, and
|
||||
`fg_factor = presents / tokens` with no batch premise. Chosen **with no oracle behind it** and
|
||||
said so; the pre-committed table is `20_OPEN_QUESTIONS` §S31 and the owner-only run is
|
||||
Cyberpunk 2077 off / ×2 / ×4 plus Hell Is Us ×4. **A ratio near 1 is not published until row
|
||||
P1 lands** — the sequencing consequence, and the reason `none` is the PR after that run, not
|
||||
this one. The entry below is kept for the route reasoning it carries.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>The entry as it stood while the producer was unchosen</summary>
|
||||
|
||||
**Do not start here, and do not build the counter again.** `fgEvaluations`, `fgMode`,
|
||||
`FL_MEASURED_FG` and `FL_MEASURED_FG_COUNTS` all have producers; the drain, the consumer
|
||||
arithmetic, the refusals and the fixtures are in and gated. What is missing is not code.
|
||||
|
||||
> **`slEvaluateFeature(kFeatureDLSS_G)` IS NEVER CALLED.** Measured 2026-08-15, Cyberpunk
|
||||
> 2077 (SL 2.7.1), five 40 s captures at four frame-generation settings: **0 evaluations
|
||||
> across ~14,000 Streamline batches**, while frame generation was demonstrably active. The
|
||||
> owner ruling of 2026-08-14 — count evaluations directly — is correct arithmetic on a route
|
||||
> the vendor does not use. The counter is right and has nothing to count.
|
||||
>
|
||||
> **The zero is corroborated, not assumed.** `UNDECODED` is 0 in the same runs, and that
|
||||
> bucket is now proven capable of reading non-zero (injected
|
||||
> `--hold-presenting-upscaled-unknown`, canaried red), so a vendored `kFeatureDLSS_G`
|
||||
> constant not matching the runtime id is excluded. What is NOT measured is where frame
|
||||
> generation IS driven from: an absence at one export of one module locates nothing, and the
|
||||
> NGX tier — `NVSDK_NGX_D3D12_EvaluateFeature`, **seven** exporting modules — is hooked
|
||||
> nowhere.
|
||||
>
|
||||
> **What DOES work, and it is a proxy.** `presents / batch` reads **1.000 / 2.000 / 4.000**
|
||||
> against the title's own off / ×2 / ×4, three independent runs at ×4. So generated presents
|
||||
> reach our vtable (§H5's central fear does not occur) and the count tracks the multiplier.
|
||||
> **But a "batch" is a present that drained a Streamline evaluation, not an application
|
||||
> frame** — they coincide here only because Ray Reconstruction is evaluated once per
|
||||
> application frame on this title, which no independent oracle has confirmed. Shipping
|
||||
> `presents/batch` as `fg_factor` would be shipping that unverified premise as a measurement.
|
||||
>
|
||||
> **THE PREMISE IS NOW FOUR TITLES WIDE, NOT ONE — 2026-08-20, `spike-notes` §8.** Everything
|
||||
> above rests on Cyberpunk. Five captures across four titles say something stronger and
|
||||
> different: **`kFeatureDLSS_G` is zero on every one**, and two of the four never call
|
||||
> `slEvaluateFeature` *at all* — Black Myth: Wukong, with `sl.interposer.dll` and
|
||||
> `sl.dlss_g.dll` both loaded and DLSS-G demonstrably running, and Rune Factory: Guardians of
|
||||
> Azuma. So the finding is not "DLSS-G avoids that export". On half the titles measured,
|
||||
> **nothing** goes through it, and `upscaler` correctly reads `Unknown` — *a hook ran and could
|
||||
> not identify what it saw*, which is the first time that distinction has mattered outside a
|
||||
> fixture.
|
||||
>
|
||||
> **Two consequences for the routes below.** Any producer reached *via* `slEvaluateFeature`
|
||||
> inherits that coverage hole, so it cannot be the whole answer. And `presents / batch` is
|
||||
> unreadable on those two titles — where a **second proxy**, `presents ÷ RT-active presents`,
|
||||
> read **5,764 / 1,441 = 4.0000 exactly** against a ×4 setting. It carries the *same* unverified
|
||||
> premise (work recorded once per application frame), so it is a proxy and not a producer; what
|
||||
> it adds is coverage, on a disjoint set of titles. On the one run where both were readable they
|
||||
> agreed. **Whichever producer is chosen has to work on a title that speaks no Streamline
|
||||
> features at all.**
|
||||
>
|
||||
> **So the open question is no longer "build a counter". It is: what is the in-policy
|
||||
> producer for DLSS-G on Streamline 2.x?** Candidate routes, none costed and none chosen:
|
||||
> hooking the interposer's swapchain proxy; `slGetFeatureFunction` + `slDLSSGGetState`
|
||||
> (§2b refused a near neighbour on five specific grounds — read them before reaching for it);
|
||||
> vendoring `sl_dlss_g.h` with its consumer; NGX-direct `nvngx_dlssg`; or shipping
|
||||
> `presents/batch` with the premise stated and an oracle attached. **This is the decision to
|
||||
> take before any more code.**
|
||||
>
|
||||
> **STATE AT THE END OF 2026-08-16, so the next session does not re-derive it.** Five
|
||||
> real-title captures across off / x2 / x4 establish that `presents / batch` tracks the
|
||||
> configured multiplier exactly (1.000 / 2.000 / 4.000) and that the presents frame
|
||||
> generation adds ARE visible to our hook. What they do NOT establish is that a drained
|
||||
> Streamline batch IS an application frame: every instrument tried so far either divides by
|
||||
> the same known constant we do, or is another in-process present hook.
|
||||
> **Three oracles were tried and all three fell** — `fl-baseline-probe` (retired by its own
|
||||
> pre-committed falsifier: it reports two mutually exclusive FG implementations both
|
||||
> "loaded"), the x2 overlay reading (one agreement counted twice, by algebra), and the x4
|
||||
> overlay reading (kills the fixed-divisor rival, cannot separate an independent count from
|
||||
> a correct derivation). ~~**The next measurement is PresentMon 2.x `FrameType`**, which
|
||||
> classifies each present from ETW and divides by nothing.~~
|
||||
>
|
||||
> **THE ROUTE IS CHOSEN AND THE MEASUREMENT IS NOW OWNER-ONLY, 2026-08-20.** The decision
|
||||
> below is taken: **measure before hooking.** `§S31` carries the decision table, written
|
||||
> before the run and with two of its six rows retiring PresentMon outright;
|
||||
> `tools/frametype-oracle.ps1` produces the input as two dimensionless ratios. What belongs
|
||||
> here is the sequencing consequence — **the run needs the owner, for two reasons neither of
|
||||
> which is the code:**
|
||||
>
|
||||
> 1. **The console binary will not start a trace session unelevated on this machine.** 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.
|
||||
> 2. **`--track_frame_type` is a BETA option that needs the VENDOR to instrument Intel's
|
||||
> provider**, by its own help text. So "classifies each present from ETW and divides by
|
||||
> nothing" is true of the mechanism and is **not** a promise that the mechanism is available
|
||||
> on a DLSS-G title. It may be as unavailable as `fl-baseline-probe` turned out to be, and
|
||||
> §S31 says so in the row that would retire it.
|
||||
>
|
||||
> **Do not build an FG hook before that run.** Every candidate route below costs more than the
|
||||
> measurement does, and two of §S31's rows change which of them is even worth costing.
|
||||
>
|
||||
> ~~**And a prerequisite with code attached, before `presents / batch` is published anywhere:**
|
||||
> `FgWindow`'s uniformity guard keys on `fgEvaluations`, which is zero on this route, so it
|
||||
> passes vacuously and cannot see a window that mixed frame-generation states. Measured: an
|
||||
> alt-tab mid-capture produced 1.84 instead of 2.00 — an 8% error with no diagnostic. A
|
||||
> published `presents / batch` needs its own per-bucket guard, and the report should be able
|
||||
> to say when the window was not uniform.~~ — **BUILT.** `FgWindow.BatchRefusal` is the
|
||||
> per-bucket `presents / batch` check, `SessionReport` prints its verdict on the line under the
|
||||
> ratio, and the drain tick samples foreground ownership so the report can name an alt-tab as
|
||||
> the cause. **The sequencing consequence, which is what belongs here:** the proxy is no longer
|
||||
> the unguarded number in the report, so a route decision below can be taken on measurement
|
||||
> rather than under time pressure to stop publishing something unsafe. Status is in
|
||||
> `CHANGELOG.md`; the reasoning is in `03_METRICS` §Frame Generation and `04_CAPTURE`
|
||||
> §Ring draining.
|
||||
|
||||
> **One cheap measurement would sharpen it and has not been run**: the game's own frame
|
||||
> counter beside a capture, pre-committed in §S30. **The other one HAS been run and is
|
||||
> retired** — `fl-baseline-probe` at ×4 / ×2 / off reported all seven capabilities `loaded`,
|
||||
> including two mutually exclusive frame-generation implementations, so its own written
|
||||
> falsifier fired in one run. This bullet claimed both were unrun while the block above it
|
||||
> said three oracles had fallen; a file whose whole subject is staleness contradicted itself
|
||||
> inside one entry, which is recorded rather than quietly repaired.
|
||||
>
|
||||
> ~~**And the owner's list for the §S31 run**~~ — **RUN 2026-08-27.** A runbook script drove it
|
||||
> — three legs, three game launches — and it landed on row **P2**: `FrameType` present
|
||||
> and **every row of all three legs `Application`**, while the two instruments agreed on the
|
||||
> present rate to within 0.3% — so PresentMon saw the generated presents and classified none
|
||||
> of them as generated.
|
||||
>
|
||||
> **PRESENTMON IS RETIRED as the application-frame oracle for NVIDIA frame generation.** That
|
||||
> is the fourth oracle to fall, after `fl-baseline-probe` and two readings of Steam's overlay.
|
||||
>
|
||||
> **AND THIS ITEM IS BACK WHERE P1/P2 SAID IT WOULD GO: the hook routes.** What was retired is
|
||||
> the *instrument*, not the question. "Is a drained Streamline batch an application frame?" is
|
||||
> exactly as open as it was, `presents / batch` still reads 2.00 and 3.99 against a title's own
|
||||
> ×2 and ×4 on the same unverified premise, and it is still not publishable as `fg_factor`.
|
||||
>
|
||||
> **So the decision this entry has been waiting on is now unblocked and unmade.** The candidate
|
||||
> routes above are unchanged and none is costed: the interposer's swapchain proxy;
|
||||
> `slGetFeatureFunction` + `slDLSSGGetState`; vendoring `sl_dlss_g.h` with its consumer;
|
||||
> NGX-direct `nvngx_dlssg`; or shipping `presents/batch` with the premise stated. **The
|
||||
> measure-before-hooking rule has been discharged — the measurement was taken and it did not
|
||||
> choose a route for us.** Whoever picks this up is choosing without an oracle, and should say
|
||||
> so in the PR rather than implying one.
|
||||
>
|
||||
> Numbers in `spike-notes` §11. Two loose ends recorded there and not here: our own `off` leg
|
||||
> drained ZERO batches (Ray Reconstruction was off, so there is nothing to divide), and whether
|
||||
> `--track_frame_type` was in effect at all is unmeasured — it changes the reason, not the
|
||||
> action.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
> **§H5 case 3 is MEASURED as of 2026-08-15, and the answer is half of what the entry below
|
||||
> feared.** `fl-probe-interposer` now calls `slInit` (the licence blocker died with #64's MIT
|
||||
> vendoring) and reports: with the interposer engaged, **the swapchain the title holds is not
|
||||
> an instance of the class whose shared vtable we patch** — its vtable is inside
|
||||
> `sl.interposer.dll`. Reproduced on Alan Wake 2 (SL 2.7.0) and Cyberpunk 2077 (SL 2.7.1).
|
||||
>
|
||||
> **It does not follow that we miss the present, and the difference is the whole metric.**
|
||||
> `--probe-proxy` already showed a *forwarding* proxy is caught one layer down, because it
|
||||
> calls `real_->Present(...)` — an ordinary virtual dispatch. **Different class ≠ missed
|
||||
> present.** What is still unmeasured is whether *this* proxy forwards, and whether DLSS-G's
|
||||
> **generated** presents reach the same vtable. That needs presents driven through the proxy
|
||||
> with our hook installed, which is a fixture nobody has built.
|
||||
>
|
||||
> **Two things that change the shape of this item:**
|
||||
>
|
||||
> - **`slEvaluateFeature`'s signature is not stable across Streamline generations.** The
|
||||
> Witcher 3 ships `sl.interposer.dll` **1.5.6**, which exports the same NAME with a
|
||||
> different argument list. `ResolveScoped` now refuses a module that does not speak SL2
|
||||
> (#71), so this item inherits that guard — do not weaken it to reach an older title.
|
||||
> - **`g_slSeen` is a bitmask, and FG needs a COUNT.** A bit collapses two evaluations
|
||||
> between two presents into one. Whatever replaces it must not break 2b's consume block,
|
||||
> which reads the same word — that is why 2b landed first.
|
||||
|
||||
- **§S30 is yours, and it is the first defect a real-title run has produced.** Cyberpunk 2077:
|
||||
every one of **2,461** params-carrying records decoded the upscaler as `UNKNOWN` while the
|
||||
title was demonstrably running DLSS. The mechanism is this item's exact drain — 10,169
|
||||
presents carried only 2,461 `g_slSeen.exchange(0)` batches, and the batches that reached a
|
||||
present held `DLSS_G` / `DLSS_RR` and not `kFeatureDLSS`. **Do not fix it by making the
|
||||
decode prefer DLSS.** Which ids actually arrive was never printed, so that fix converts a
|
||||
wrong answer into a *confident* wrong answer. Print them first.
|
||||
- **`presents / batches = 4.13` was measured, and it is a PROXY rather than this item's
|
||||
number.** Two runs gave 4.13 and 4.12 against the title's own `DLSS_MultiFrameGeneration =
|
||||
x4`. Encouraging, and *not* `presents / fgEvaluations` — nothing counts `kFeatureDLSS_G`
|
||||
evaluations yet, which is the whole of this item. Quoting 4.13 as an FG factor would be
|
||||
reporting the oracle back to itself.
|
||||
- **The arithmetic needs deciding before the hook, not after.** `03_METRICS` defines
|
||||
`F_app = presents − Σ fgEvaluations`, i.e. `fgEvaluations` counts GENERATED frames — but
|
||||
`slEvaluateFeature(kFeatureDLSS_G)` fires once per APPLICATION frame and produces N−1 of
|
||||
them, and N lives in `sl::DLSSGOptions`, set out of band through `slDLSSGSetOptions`: the
|
||||
same refused route as 2b's. **Counting evaluations directly** gives
|
||||
`F_app = Σ evaluations`, `F_disp = presents`, `fg_factor = presents / evaluations` with no
|
||||
multiplier and no new header — at the cost of a `03_METRICS` change in the same PR.
|
||||
Owner-decided 2026-08-14: **count evaluations directly.**
|
||||
- **The other two vendors, measured.** `libxess_fg.dll` proxies the swapchain
|
||||
(`xefgSwapChainD3D12InitFromSwapChain`, `…GetSwapChainPtr`, `…SetEnabled`). `ffx_fsr3_x64.dll`
|
||||
exports `ffxFsr3SkipPresent`. **But the newer `amd_fidelityfx_framegeneration_dx12.dll`
|
||||
(3.1.5, in three installed titles) exports only the five generic `ffx*` entry points** —
|
||||
identity comes from the arguments, not the symbol, so telling FG from upscaling means
|
||||
decoding a vendor struct we have no headers for. Defer with a written rationale rather than
|
||||
guessing.
|
||||
- Oracle: the game's own settings menu and frame counter (owner decision). **Cyberpunk 2077 is
|
||||
the sharpest**: `DLSS_MultiFrameGeneration = x4` in its settings file, so the expected
|
||||
answer is `fg_factor ≈ 4.0` — a number a structurally-1.0 bug cannot fake.
|
||||
|
||||
<details>
|
||||
<summary>The original entry, kept for the reasoning it carries</summary>
|
||||
|
||||
### 3. Frame generation, and the present it may not own
|
||||
|
||||
- `fgEvaluations` / `fgMode` / `FL_MEASURED_FG` + `FL_MEASURED_FG_COUNTS`.
|
||||
- **The swapchain question must be answered here, not deferred past it.** Measured from
|
||||
`vendor-exports.json` and recorded nowhere else until 2026-08-05: **all three FG
|
||||
vendors take over the present.** `libxess_fg.dll` exports
|
||||
`xefgSwapChainD3D12InitFromSwapChain` / `GetSwapChainPtr`; `ffx_fsr3_x64.dll` exports
|
||||
`ffxFsr3SkipPresent`. §H5 case 3 is live for DLSS-G, XeFG **and** FSR3-FG. If it
|
||||
bites, `fg_factor` is **structurally 1.0**, which looks exactly like "FG is off".
|
||||
Minimum: notice a swapchain we did not see created and report *unknown*.
|
||||
- Oracle: the game's own settings menu and frame counter (owner decision). The exit
|
||||
criterion already says "verified against the game's own settings menu", so this does
|
||||
not import P2's ETW source.
|
||||
|
||||
</details>
|
||||
|
||||
### ~~4. Ray tracing~~ — BUILT 2026-08-20, and the trap it hit is the one to carry forward
|
||||
|
||||
**Do not start here.** `FL_MEASURED_RT` has a producer, `rtFlags` carries real evidence, and the
|
||||
tri-state's `Yes` and `No` are both reachable for the first time. Status is in `CHANGELOG.md` and
|
||||
`spike-notes` §6. What belongs here is **the trap**, because it generalises past ray tracing:
|
||||
|
||||
> **A COMMAND LIST'S vtable IS NOT THE ONE YOU READ OFF A FRESH ONE.** The first `Reset()`
|
||||
> replaces it with a **per-object** vtable in which the vendor driver has taken methods over.
|
||||
> Measured on an RTX 5080: `DispatchRays` moves from `D3D12Core.dll` into `nvwgf2umx.dll`, while
|
||||
> `BuildRaytracingAccelerationStructure` stays put. Every game resets its lists every frame, so
|
||||
> the addresses in an unreset list's vtable are ones no title ever calls for the moved methods.
|
||||
>
|
||||
> **The first version of the hook did exactly that.** It installed, published
|
||||
> `FL_HOOK_RT_DISPATCH`, and never fired — `withDispatch = 0` beside `hooks = RT_DISPATCH |
|
||||
> RT_AS_BUILD`, a mask bit with nothing behind it. And because the OTHER hook worked, it read as
|
||||
> a bug in the dispatch detour rather than in the acquisition they share.
|
||||
>
|
||||
> **The rule: put a throwaway object through the same lifecycle the game's objects go through,
|
||||
> or it is not a sample of them.** §H5 says the same thing about swapchains one layer up. The
|
||||
> fix was one call; finding it took an injected fixture, because no probe that reads a fresh
|
||||
> object can see it.
|
||||
>
|
||||
> **And every vendor-specific result here is ONE DRIVER'S.** Nothing says an AMD or Intel UMD
|
||||
> splits the two methods the same way, or leaves either in `D3D12Core`. `--probe-dxr` Q5 prints
|
||||
> the module on each side of the Reset so the next machine answers for itself.
|
||||
|
||||
<details>
|
||||
<summary>The original entry, kept for the reasoning it carries</summary>
|
||||
|
||||
### 4. Ray tracing — ~~**START HERE**~~, and item 3 just took away its denominator
|
||||
|
||||
*(Archived 2026-08-27. The live entry is above; this header's "START HERE" is struck so the
|
||||
file does not contain two of them — the same correction item 2b's header carries, and the
|
||||
exact class this file exists to prevent. **Its question is also answered.** The denominator was
|
||||
chosen on 2026-08-20, in the PR that wrote the hooks: `rt_frame_pct` is a share of PRESENTS with
|
||||
the ×FG dilution written down as a known, quantified limit — at ×4 it reads ~25%, against a `Yes`
|
||||
gate of ≥ 5%, so the verdict is unaffected and only the reported percentage is diluted — while
|
||||
`rays_per_pixel` is taken over RT-ACTIVE presents, is therefore undiluted, and needs no
|
||||
application-frame count at all. `03_METRICS` §RT/PT/RR carries the decision and its falsifier,
|
||||
which did not fire on two independent titles. Kept rather than deleted for the reasoning it
|
||||
carries about why the choice mattered.)*
|
||||
|
||||
> **The dependency you inherited, before anything else.** The plan for this item routed
|
||||
> `03_METRICS`' RT thresholds — `≥ 5% of frames`, `rays_per_pixel`, `rt_frame_pct` — through
|
||||
> **application frames**, using `Σ fgEvaluations` as the denominator, because dividing by
|
||||
> PRESENTS dilutes every one of them by the frame-generation factor: at ×4 a title that
|
||||
> path-traces every application frame reports `rt_frame_pct = 25%`, and `rays_per_pixel`
|
||||
> lands at a quarter of the truth, below the heuristic's own 1.0 threshold. That decision was
|
||||
> taken when `fgEvaluations` was expected to have a producer. **It does not, on the one route
|
||||
> measured** (item 3 above). So this item starts with a choice nobody has made:
|
||||
>
|
||||
> - use `presents / batch`-derived application frames, inheriting item 3's unverified premise;
|
||||
> - divide by presents and write the dilution into `03_METRICS` as a known, quantified limit;
|
||||
> - or accumulate RT evidence to an application-frame boundary **in the writer**, which costs
|
||||
> more in the hook and needs the same boundary signal item 3 could not find.
|
||||
>
|
||||
> Whichever is chosen, say so in `03_METRICS` in the same PR. Do not leave the thresholds
|
||||
> reading as though the denominator were settled.
|
||||
|
||||
### 4. Ray tracing — §S29(f) is ruled, and the cheapest conjunct has landed
|
||||
|
||||
> **The RayQuery contradiction is settled, 2026-08-14 (owner).** AS-build activity proves
|
||||
> **ray tracing is happening** ⇒ `RT = Yes`; *classifying the technique as RayQuery* is what
|
||||
> needs a DXIL scan and stays `N/A`. CLAUDE.md rule 7's `N/A` applies to the **classification**,
|
||||
> not to the yes/no question — so `03_METRICS:170` and `README.md:34` both stand. **Amend rule
|
||||
> 7 in the PR that writes the hook**, and build both hooks: a `DispatchRays`-only writer sees
|
||||
> nothing on a RayQuery-only title and its silence is indistinguishable from a real negative.
|
||||
>
|
||||
> **`rtTier` already has a producer** (#67) — `ResolveApi` queries
|
||||
> `D3D12_FEATURE_D3D12_OPTIONS5` on the device DXGI hands it. Two of the `No` branch's three
|
||||
> conjuncts are therefore live; **what is still missing is `FL_MEASURED_RT`**, so RT is `N/A`
|
||||
> on every session and both `Yes` and `No` remain unreachable. The gap moved; it did not close.
|
||||
>
|
||||
> **And a trap that has now appeared twice in two different vendors' enums.**
|
||||
> `D3D12_RAYTRACING_TIER_NOT_SUPPORTED` is **0**, against `rtTier`'s "not queried";
|
||||
> `sl::DLSSMode::eOff` is **0**, against `upscalerQuality`'s "not measured". Both would have
|
||||
> published an affirmative negative by simply copying the vendor value. **Assume the next
|
||||
> vendor enum has the same shape**, and resolve it at the writer, where the two states are
|
||||
> still distinguishable.
|
||||
|
||||
### 4. Ray tracing, including the path dispatch counting misses
|
||||
|
||||
- `CreateStateObject`, `DispatchRays`, `BuildRaytracingAccelerationStructure`;
|
||||
`dispatchRaysVolume`, `maxTraceRecursionDepth`, `rtFlags`, `FL_MEASURED_RT`, and
|
||||
`FlWriterState.rtTier` + `hooksInstalledMask`.
|
||||
- Harness DXR mode **including a RayQuery-only variant** — that is what makes item 6's
|
||||
actual claim provable: AS-build catches a title `DispatchRays` misses.
|
||||
**Check first:** whether WARP on the CI runners supports DXR. If not, gate the ctest
|
||||
on device support and say so rather than reporting a skip as coverage.
|
||||
- **§S29(f) must be settled before the hook is written.** CLAUDE.md rule 7 and
|
||||
`03_METRICS` §RT disagree about whether inline RayQuery is measurable, and the answer
|
||||
decides whether a RayQuery-only title reports `Yes` or `N/A`.
|
||||
|
||||
</details>
|
||||
|
||||
### 5. Item 4's answer, measured on real titles
|
||||
|
||||
Real-title runs; `spike-notes` §8's empty per-title table, §6 and §9's empty bullets.
|
||||
The README sentence is **not a percentage** — the recorded decision is that the baseline
|
||||
cannot answer four of the five questions at all.
|
||||
|
||||
**Two things nobody has costed** (found by the completeness critic, 2026-08-05):
|
||||
`StaticGameDetector` ~~has **no runnable vehicle** — every construction is in tests~~ *(runs in the Agent's `DetectionSweep` since P4 PR-1, 2026-09-14)* — so
|
||||
item 4's mandated comparison cannot be re-run on the *baseline* side either; and the
|
||||
only candidate title exercising all five required values is a **Streamline** title,
|
||||
i.e. the one class where the hook premise is recorded INCONCLUSIVE.
|
||||
|
||||
### 6. The S-series ledger, audited against the criterion it serves
|
||||
|
||||
Written rationales for whatever is still ❓/⏳/◐ in §S24, and unify the glyphs — one
|
||||
disposition currently wears three (`✅ deferred` / `🅓 deferred` / `🔴 deferred`) in a
|
||||
table whose only purpose is being auditable by counting them.
|
||||
|
||||
@@ -0,0 +1,426 @@
|
||||
# HANDOFF history — The queue, item 7 (7a–7c), Separable, §M5
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
### ~~7. **START HERE**~~ — the three things left once the FG blocker fell (2026-09-04, owner's list) — **CLOSED 2026-09-06; the live head is §P2 below (struck 2026-09-09 so this file holds one START HERE, not two)**
|
||||
|
||||
P0 exit criterion 1 reads **4 of 5** as of 2026-09-04: upscaler identity, render → output,
|
||||
FG factor and RT state are measured against the titles' own menus. What follows is the
|
||||
owner's list for the next session, in the order the dependencies run, each with what makes
|
||||
it fail on unmodified `main` — because a criterion already true on `main` is decoration.
|
||||
|
||||
#### ~~7a. The quality preset — the last value criterion 1 lacks~~ — **CLOSED 2026-09-06 (owner): DLSS / DLSS-G done on every measured title**
|
||||
|
||||
*Closed on the Cronos FG-on capture (`20_OPEN_QUESTIONS` §H5 head, `spike-notes` §9): the trio or a counted
|
||||
`none` on every NVIDIA title through the hooked bodies, DXGI's counter where the hook cannot count (DL:TB —
|
||||
that title's integration, not SDK 2.8.0's), and the driver-reported identity where no hook can see it, with
|
||||
its negative measured. The quality preset itself stays `0xFF` / N/A everywhere — the override fields are
|
||||
the override's, the tags carry no size on D3D12 — and the owner closed the item on that. What follows is
|
||||
the history.*
|
||||
|
||||
|
||||
*Fails on `main` because:* every real title measured reads `upscalerQuality = 0xFF`.
|
||||
Cyberpunk 2077 never chains `sl::DLSSOptions`, so 0xFF there is the title's truth; **Alan Wake
|
||||
2 (SL 2.7.0) is the candidate that may chain it and is unmeasured** (Owner-only item 2).
|
||||
|
||||
- **First, the cheap measurement:** one Alan Wake 2 capture at a known preset, read
|
||||
`quality=` off the `render … quality=… upscaler=…` line. If it reads the preset, criterion 1
|
||||
is 5 of 5 on that title and this item is a spike-notes entry. If it reads 0xFF too, the
|
||||
Streamline options route yields nothing on either measured title, and the decision below is
|
||||
live. *(Runbook title 12 is Alan Wake 2 as of 2026-09-04; Epic may update the executable on
|
||||
launch, so launch first and grant after.)*
|
||||
- **The input to that decision is on the report now** (2026-09-04): `render -> output` prints the
|
||||
two measured sizes, `03_METRICS`' ratio and the render-scale percentage — Cyberpunk reads
|
||||
`1485x835 -> 2560x1440 = 1.72x (58% render scale)` — plus a **SETTINGS MOVED** flag when the
|
||||
window held more than one tuple. It prints **no preset name**; that is the decision below,
|
||||
still the owner's. Every FSR title measured on 2026-09-04 also reads `0xFF` for the quality
|
||||
byte, and on that route it is the true value rather than a gap: the ffx-api dispatch carries
|
||||
no quality mode at all, so the derived label is the only route to a preset name for AMD too.
|
||||
- **The decision, if 0xFF everywhere:** `renderW/H ÷ outputW/H` is *exact* (Cyberpunk: 1485×835
|
||||
at 2560×1440 = 0.58, which IS DLSS Balanced, and the menu agreed), and DLSS's preset ratios
|
||||
are documented constants (DLAA 1.0, Quality 0.667, Balanced 0.58, Performance 0.5, Ultra
|
||||
Performance 0.333). A label **derived** from the measured ratio — printed as *"render scale
|
||||
58% ≈ Balanced"*, never written into `upscalerQuality`, never aggregated as the vendor enum —
|
||||
is an inference over a measurement, and `05_DETECTION`'s rule against static hints setting
|
||||
runtime facts does not forbid it: the input is a runtime measurement. **Whether a derived
|
||||
label may appear beside a measured field is the owner's call**; do not build it before that
|
||||
call, and if built, the byte stays 0xFF and the report says *derived*.
|
||||
- **Do not** reach for `slDLSSSetOptions` via `slGetFeatureFunction`: §2b refused it on five
|
||||
grounds that have not changed, and NGX-direct `NVSDK_NGX_Parameter_GetUI` is licence-blocked.
|
||||
- ~~**Alan Wake 2 did not run on 2026-09-04** (the owner tried every workaround; the title is
|
||||
broken on this machine)~~ **Corrected 2026-09-27 (owner):** it did run late that evening — the run reports
|
||||
`alanwake2-224851` and `alanwake2-230707` hold two captures (DLSS + RR, ray tracing *Yes*, 92.52 FPS; then ray
|
||||
tracing off, Presented 114.52), neither with the quality preset, which is what this item needed. The earlier
|
||||
attempts that day failed, so the measurement moved to **Dying Light: The Beast at DLSS**, the
|
||||
first Streamline title measured whose batches carry `kFeatureDLSS` — identity `Dlss` on 4,575
|
||||
of 4,575 batches. It read `UpscalerParams = 0` on three captures, because DL:TB ships
|
||||
**Streamline 2.8.0, which deprecates `slSetTag` for `slSetTagForFrame`**, and only the
|
||||
deprecated export had a row. The `slSetTagForFrame` row exists as of this entry (#115) —
|
||||
**and the rerun on it still read `UpscalerParams = 0` with both rows live**, so the title
|
||||
tags with a zero extent or not on this route at all. The next build reads the size the
|
||||
tagged `sl::Resource` declares when the extent is zero (`TagSize`, every route); one more
|
||||
DL:TB DLSS capture on it is ~~owed~~ **ran 2026-09-05 00:53 (#116 build): `N/A` stands** —
|
||||
params 0 of 3523 with both rows live and the fallback in. The route yields nothing on this
|
||||
title; the honest answer is `N/A`, and 7a on DL:TB is closed on that. What would reopen it
|
||||
is a tag-route census (calls per export, zero-extent seen, Resource-size seen), which needs
|
||||
a layout bump and is not worth one for a preset byte. The derived-label decision above is
|
||||
unchanged and applies to the titles that do print the line.
|
||||
- **Separately, and more important than the preset:** every DL:TB DLSS run (five, the last at
|
||||
00:53 on the #116 build) had DLSS Frame Generation ON per the owner, and every one read
|
||||
`presents = tokens`, `frame generation: none`. That is `20_OPEN_QUESTIONS` §H5 case 3's
|
||||
candidate title. **Owner decision 2026-09-05: this is its own session and its own PR.** Read
|
||||
§H5 first; the discriminator (the owner's counter beside our `FPS:` line) is pre-committed
|
||||
there and is the first thing that session asks for. Nothing in FG counting changes before
|
||||
that reading. **The reading came the same day and the first PR landed on it** — the owner:
|
||||
the title runs at DLSS ×4, the frames we record are the native ones (§H5, verbatim). The
|
||||
capture host now prints each census-named module's file version and withholds `none` on
|
||||
that shape (`03_METRICS` §Frame Generation; the key is `sl.dlss_g.dll`, not
|
||||
`nvngx_dlssg.dll`). **What is next is the owner's session pre-committed in §H5** — DL:TB with
|
||||
DLSS FG off and ×4, Cyberpunk MFG ×4 as the control, PresentMon elevated beside each, the
|
||||
counter's NUMBER written down — and the row it lands on decides whether the gate stays, a
|
||||
second present sink is costed (§H5 lists the candidates; the route is the owner's), or the
|
||||
gate is withdrawn. Nothing in the hook changes before that row. **The counter half of Leg 1
|
||||
is read (2026-09-05): ~300 against our 76.7, reading (a) with its number; the PresentMon half
|
||||
is still owed.** And the owner's eleven-capture run the same day (`spike-notes` §9) put the
|
||||
remaining NVIDIA gap in one sentence: the COUNT is right on every title and the IDENTITY is
|
||||
what this build cannot say — DLSS on the NGX-direct UE titles, DLSS-G everywhere. **The identity half landed 2026-09-05 from the Streamline docs** (DLSS-G guide §5.0: the HUD-less / UI tags a
|
||||
frame-generating title MUST send, through exports already hooked): `frame generation: DlssG` is expected on
|
||||
Cyberpunk at MFG and on the UE titles at ×4 on the next run, with the new `Streamline tag census:` line saying
|
||||
which route carried the tags — and DL:TB's census line says whether that title feeds DLSS-G through a route
|
||||
this build sees. `slDLSSGGetState` was refused (`03_METRICS` §FG: it resets the plugin's own counter).
|
||||
~~**START HERE next:** `fl-probe-nvapi --ngx-state <pid>` against a running Lies of P, Hell Is Us, DL:TB
|
||||
and Cyberpunk (no capture, no injection) — the super-resolution identity on NGX-direct titles is still the
|
||||
gap the tags cannot close.~~ **RAN 2026-09-06 on Hell Is Us, Expedition 33 and Lies of P (§H5, `spike-notes`
|
||||
§9): `CREATED | EVALUATE` on the SR word without an override on both no-override titles — the identity
|
||||
exists in the driver's bookkeeping; the FG word does not see DLSS-G at ×4; `frameGenerationCount` is the
|
||||
override target, `scalingRatio` is 0 even under an override.** ~~**START HERE next: the owner decides the
|
||||
driver-reported rung (§H5 says exactly what it may claim: `Dlss (driver-reported …)` on a session where
|
||||
every hook says N/A, nothing about quality, ratio or FG), and the negative is owed first — the probe on
|
||||
Lies of P with DLSS switched OFF, expected `CREATED` clear.**~~ **Decided and BUILT 2026-09-06: the capture
|
||||
host probes the driver beside every module snapshot and the `upscaler:` line has the driver-reported rung
|
||||
(`03_METRICS` §Upscaling). START HERE next: the owner's run — §H5 rows N1–N4, and N3 (Lies of P with DLSS
|
||||
OFF) is the one that keeps or withdraws the rung — LANDED 2026-09-06 midday: N3 read `CREATED` clear with
|
||||
upscaling off, N1 prints `Dlss (driver-reported …)` on four NGX-direct titles, N2 prints agreement on two,
|
||||
and the FG word turned out to follow DLSS-G too (identity, never the multiplier). START HERE next: Cronos
|
||||
(a second Streamline 2.8.0 title, UE) with frame generation ON — does the 2.8.0 pacer bypass the patched
|
||||
bodies there too (`DXGI present counter` ≈ 3) or is it Techland's (0)? — ANSWERED 12:17: Cronos FG on reads
|
||||
`86.8 → 172.72 (×1.99 FG)` with `unseen=0`; the bypass is Techland's. Item closed; the next item is the
|
||||
owner's pick from 7b / 7c below.** **The tag route LANDED on the owner's evening run (`spike-notes` §9): `DlssG` on
|
||||
six of six Streamline titles, and DL:TB's census shows its scaling-input tag arrives with no size, which
|
||||
closes 7a's last question.** If the driver's per-process NGX feedback is
|
||||
populated without an NVIDIA-app override, the identity question has a producer that is not a
|
||||
hook and the owner decides whether `03_METRICS` gains a *driver-reported* rung (§H5 says what
|
||||
that rung may and may not claim). If it is not populated, the answer stays `N/A` and the
|
||||
session goes back to the PresentMon leg. **The in-process half of that leg LANDED (2026-09-05,
|
||||
night): DL:TB at DLSS FG ×4 read 2.90 and 2.95 unseen presents per hooked one on the same chain —
|
||||
§H5 row P1-DXGI — while Streamline 2.7.3 (Hell Is Us) and 2.10.3 (the Onimusha demo) read 0.00, so
|
||||
2.8.0's pacer is the one that bypasses the patched bodies. The record now carries `dxgiUnseen` and
|
||||
the window counts `Displayed = hooked + unseen`, labelled DXGI-COUNTED (`03_METRICS`); DL:TB's next
|
||||
capture is expected to print the trio at ≈ ×3.9 with that label and no withheld line — LANDED
|
||||
2026-09-06: `70.52 → 282.08 (×4 FG)`, DXGI-COUNTED 12,387, `DlssG`. Leg 0 the same morning (FG off,
|
||||
twice) showed the plugin is a startup-time load and the report withheld as pre-committed, so the
|
||||
gate is now narrowed to sessions where the DXGI counter was not read; a read counter with zero
|
||||
unseen prints `none` with DXGI's agreement.** The
|
||||
"sl.common must be loaded on 2.8" lead is closed by the 2.10.3 title, which injects and counts like
|
||||
2.7 (§H5).
|
||||
|
||||
#### 7b. Titles whose upscaler or frame generation is compiled into the executable
|
||||
|
||||
*Fails on `main` because:* the census has no module to see, the inventory has no export to
|
||||
resolve, and the report prints *"cannot include in-process generated frames"* — which on a
|
||||
statically linked FSR3-FG title is wrong in the dangerous direction. The sentence names the
|
||||
hole; it does not close it.
|
||||
|
||||
- **Measure before costing.** No installed title has this shape: every FSR title on this
|
||||
machine ships the `ffx_*` / `amd_fidelityfx_*` DLLs (`vendor-exports.json`, 34 modules), and
|
||||
the six-title run found none. The catalogue that links FSR2 statically is mostly
|
||||
2022–2023 UE4/Unity titles that took the source SDK. **Find one first.** A rationale written
|
||||
about a title that does not exist is the kind of deferral §S24 counts against nobody.
|
||||
- **What is and is not possible, so the costing is honest.** Nothing by name: no module, no
|
||||
export. What survives static linking is behaviour on interfaces we already hook or could:
|
||||
FSR3's frame-generation *proxy swapchain* is created through `IDXGIFactory*::CreateSwapChain*`
|
||||
on the shared `dxgi.dll` class vtable — visible **only at creation**, i.e. only in launch mode
|
||||
(§S1, deferred) or on a title that recreates its swapchain on a settings change; and per-frame
|
||||
work on the D3D12 queue (`ExecuteCommandLists` on the FG's async queue) is a cadence signal
|
||||
with no vendor name on it, which is rung 3 at best and needs an application-frame count this
|
||||
title cannot give. **The honest ceiling for a statically linked title in attach mode is
|
||||
Presented FPS with the census's qualifier** — which is what ships today, with the hole named.
|
||||
- **The only cheap improvement is wording**, and it is already in: the qualifier says
|
||||
*statically linked FSR3-FG … outside what this can see*. **Built 2026-09-06, two steps past that
|
||||
(owner's choice over "return native", which rule 6 forbids):** the executable FILE is scanned on
|
||||
disk after the session for the vendor SDK strings, and a frame-generation-capable one flips the
|
||||
clear-census sentence from *cannot* to *MAY*; and the rung-3 line prints its exclusions (the
|
||||
driver's FG word, the tags, the ffx census, the module census, the file's markers). The ceiling
|
||||
for a title that is both compiled-in and token-less stays Presented FPS + that qualifier. **LANDED
|
||||
2026-09-06 14:02: Rune Factory at FSR + FSR FG prints the pre-committed line verbatim (§H11); 7b is at its
|
||||
ceiling and closed.** Hell Is Us at XeSS + XeSS-FG the same run: no token, so Displayed measured (186.47,
|
||||
0 unseen) and Native unknown — the N/A now carries its witnesses, and that is the XeFG ceiling too. If a title is found, the first PR is
|
||||
a `spike-notes` row and a `20_OPEN_QUESTIONS` §Scope entry with the measured shape, not code.
|
||||
- ~~**Measured 2026-09-04: no such title is installed.**~~ **Found the same evening, by running
|
||||
rather than by scanning: Rune Factory: Guardians of Azuma.** The scan was right that every FSR
|
||||
title *ships* its DLLs — Rune Factory ships the 1.1.x monolith — and wrong to read shipping as
|
||||
loading: with FSR frame generation on, the census has **no AMD module at all**, so the plugin's
|
||||
FSR 3 is compiled in. And the ceiling is better than this entry feared: Streamline's frame
|
||||
token is requested on that UE5 title regardless, so the count read `59.99 → 119.95 (×2 FG)`,
|
||||
*technology not identified* — the trio, with the vendor missing. Identity by name stays out of
|
||||
reach; §Scope decisions carries the corrected row. A disk scan cannot find this shape; a
|
||||
capture with the census line can. **Black Myth: Wukong is the second** — its FSR upscaling
|
||||
dispatches to neither the loaded monolith nor the loader, and it offers no FSR frame generation.
|
||||
|
||||
#### ~~7c. AMD and Intel identity, measured rather than inferred~~ — **AMD LANDED 2026-09-04 and re-confirmed complete 2026-09-06 on Lies of P; Intel closed by licence (re-checked 2026-09-06, unchanged)**
|
||||
|
||||
*2026-09-06, 12:46: Lies of P at FSR 3.1 + FSR FG prints `Fsr3` / `FsrFg` / `59.77 → 119.55 (×2 FG)` /
|
||||
`2560x1440 -> 2560x1440` with every count agreeing (`spike-notes` §9) — acceptance step 5 in full, beside
|
||||
the DXGI counter (0 unseen) and the NVIDIA driver's word (nothing created). The owner called the AMD half
|
||||
done. Intel: the licence was re-fetched the same day — Intel Simplified Software License, October 2022,
|
||||
binary-only, "nor any modification", termination; the header banner still forbids copying — so the
|
||||
reversal condition has not fired and the census stays the answer. What is new: Intel's own README says
|
||||
XeSS-FG runs on non-Intel GPUs with SM 6.4, so an XeFG session IS capturable on this box (DL:TB, Hell Is
|
||||
Us, Cronos, Expedition 33 ship `libxess_fg.dll`), and the proposal on the table is identity BY ELIMINATION,
|
||||
labelled — see `20_OPEN_QUESTIONS` §H11's 2026-09-06 note.*
|
||||
|
||||
|
||||
**Do not start here.** The three ffx-api leaves are hooked, the FidelityFX headers are vendored
|
||||
at tag **`v2.3.0`** (not the `v1.1.4` step 1 below names — its own reversal condition fired:
|
||||
installed titles ship SDK 2.x effect DLLs whose `PrepareV2` descriptor 1.1.4 does not declare),
|
||||
the K = 1 / K = 4 pair runs on both vendor shapes, and the acceptance table is pre-committed in
|
||||
`20_OPEN_QUESTIONS` §H11 (rows A1–A3, R1–R5). Status is in `CHANGELOG.md` and §H11. **Three
|
||||
corrections to the entry below, each of which changed what got built:**
|
||||
|
||||
- **Scope to the modules a GAME CALLS — the three leaves AND the SDK 2.x loader — not "the
|
||||
facade", and this bullet reversed itself within the day.** Step 2 says *"module-scope every row
|
||||
to the facade … the plugin modules are called by the facade"*. The morning's build hooked the
|
||||
three leaves only and refused the loader by `static_assert`, arguing that five identical export
|
||||
tables leave the loader no route to a leaf but the leaf's own export, so hooking both would
|
||||
double-count. The UE5 half held — Hell Is Us and Expedition 33 ship the two effect DLLs with
|
||||
**no loader** and their dispatches arrive at the leaves, 1×. **The loader half did not:** Dying
|
||||
Light: The Beast at FSR + FSR FG, KCD2 at FSR and Wukong at FSR produced **zero** dispatches at
|
||||
any leaf export (§H11's run table, row R6). The signed loader reaches its providers through an
|
||||
object, not an export. So the row set is *whatever module the game calls*: four rows, the
|
||||
loader's stub forwards through the leaves' direct entry to model the measurement, and the
|
||||
K = 1 control with all four hooked is what would show a loader that re-entered an export.
|
||||
- **`ffxCreateContext` is not a row.** Identity comes off the UPSCALE dispatch's type — per
|
||||
frame, so it says *running* rather than *created* — and a create-context row's honest family
|
||||
is `UPSCALER_IDENTITY` alone, which collides with `slEvaluateFeature`'s under the installer's
|
||||
equality binding.
|
||||
- **"Extend Pass C's forbidden-import list" was already done** — `^(sl\.|_?nvngx|libxess|ffx_|amd_fidelityfx)`
|
||||
since 2026-08-14, self-tested. Pass C gained the **export** table instead, because `ffx_api.h`
|
||||
declares its entry points `__declspec(dllexport)` unconditionally.
|
||||
|
||||
**Run 2026-09-04 evening, thirteen captures, §H11's table:** A1–A3 landed as pre-committed
|
||||
(`Fsr3` / `FsrFg` / ×2.00 / 1.00 on Lies of P; `none` by count with FG off; `FSR (3.1 or 4 …)` /
|
||||
`FsrFg` / ×2 on Hell Is Us), Expedition 33 showed the mixed-vendor shape (FSR upscale + DLSS FG ×3
|
||||
→ *active, technology not identified* at ×2.97), Cyberpunk at FSR 3 split across two AMD
|
||||
generations, and **Rune Factory turned out to be 7b's statically linked title** with the Streamline
|
||||
token count still reading ×2. **Row R6 ran the same night on #111:** Dying Light: The Beast at
|
||||
FSR + FSR FG printed `FSR (3.1 or 4 …)` / `FsrFg` / `70.49 → 140.9 (×2)` with the counts agreeing
|
||||
at 1.01, KCD2 at FSR printed the identity and `none` by count at 1.00 — the loader row carries
|
||||
both, once. **Wukong at FSR read silent at the monolith AND the loader with the monolith loaded**:
|
||||
FSR upscaling compiled into its UE plugin (Rune Factory's shape) with the monolith loaded and
|
||||
unused — ~~owed: Wukong with FSR frame generation ON~~ **the title has no FSR frame-generation
|
||||
option (owner, same night)**, so Wukong is the second static title and nothing is owed on it. ~~**The FSR 3.0 host route
|
||||
(`ffx_fsr3_x64.dll`, step 3 below) is deferred to its own PR** — ten host headers from `v1.1.4`;
|
||||
Cyberpunk at FSR 3 is its oracle and already prints `FsrFg` from the monolith beside it.~~
|
||||
**BUILT 2026-09-05, and the tag was not `v1.1.4`.** Cyberpunk's module exports exactly
|
||||
`fsr3-v3.0.4`'s twelve `ffxFsr3*` names; 1.1.4 appends fields after `renderSize` and declares
|
||||
three exports the module lacks. One row — `ffx_fsr3_x64.dll!ffxFsr3ContextDispatchUpscale`,
|
||||
the same family and publish point as the ffx-api rows, keyed by module in the installer —
|
||||
reads `renderSize` and nothing else; `ffxFsr3DispatchFrameGeneration` is deliberately not a
|
||||
row (the monolith generates on the one title; §H11 pre-commits the reversal). **What is owed
|
||||
is the owner's acceptance run**, rows B1–B4 in §H11: Cyberpunk at FSR 3 + FG must print
|
||||
`upscaler: Fsr3` with one extent agreeing between the host and the monolith's PREPARE, and
|
||||
`frames/upscale-drained = 1.00`; B2 (facade silent, `upscale-drained = 0`) is the pre-committed
|
||||
condition for adding the `ffx_fsr3upscaler_x64.dll` row instead — never both.
|
||||
|
||||
<details>
|
||||
<summary>The entry as it stood, kept for the reasoning it carries</summary>
|
||||
|
||||
#### 7c. AMD and Intel identity, measured rather than inferred — §H11's deferral has a next step
|
||||
|
||||
*Fails on `main` because:* Lies of P with FSR 3.1 frame generation demonstrably on reads
|
||||
`upscaler: N/A … frame generation: N/A` plus a census WARNING, and Hell Is Us at FSR reads the
|
||||
same as its off run. The three AMD 3.1 modules export the same five generic names
|
||||
(`ffxCreateContext`, `ffxDispatch`, `ffxQuery`, `ffxConfigure`, `ffxDestroyContext`); XeSS
|
||||
exports `xessD3D12Init` / `xessD3D12Execute` and XeFG `xefgSwapChainD3D12InitFromSwapChain`
|
||||
(`vendor-exports.json`).
|
||||
|
||||
1. **The `18_GPU_VENDOR_APIS` §Checklist has been run on both SDKs (2026-09-04) — read the
|
||||
result before assuming the previous sentence, which said both were MIT and was wrong about
|
||||
Intel.** *AMD FidelityFX*: clear. Tag **`v1.1.4`** is MIT at the root and inline in every
|
||||
header of interest; vendor **types-only, with a consumer in the same commit**
|
||||
(`18_GPU_VENDOR_APIS` records why an unconsumed vendoring is worse than none). The files:
|
||||
`ffx-api/include/ffx_api/{ffx_api.h, ffx_api_types.h, ffx_api_loader.h, ffx_upscale.h,
|
||||
ffx_framegeneration.h, dx12/ffx_api_dx12.h, vk/ffx_api_vk.h}` for the 3.1 facade the
|
||||
installed titles call, and `sdk/include/FidelityFX/host/{ffx_fsr3.h, ffx_fsr3upscaler.h,
|
||||
ffx_frameinterpolation.h, ffx_opticalflow.h, ffx_types.h, ffx_error.h, ffx_interface.h,
|
||||
ffx_util.h, ffx_assert.h}` for the FSR 3.0 host API *(2026-09-05: vendored from **`fsr3-v3.0.4`**, not `v1.1.4` — the tag whose declarations match the module Cyberpunk ships; see the banner above)*. Do not take `main`: it is SDK 2.x under
|
||||
a binary-only `docs/license.md` that excepts these headers as MIT only by an 845-line list.
|
||||
Extend `hookinventory-check` Pass C's forbidden-import list with `amd_fidelityfx_*.dll` /
|
||||
`ffx_*.dll` in the same PR — the Streamline lesson, one vendor over. *Intel XeSS SDK*:
|
||||
**rejected.** Intel Simplified Software License (binary-only grant, no reverse engineering,
|
||||
termination), and the headers themselves forbid copying without Intel's permission, so
|
||||
step 3 binds — no vendoring and **no re-declaration** of `xessD3D12Execute` or
|
||||
`xefgSwapChain*`. **Intel stays at the census — decided 2026-09-04, delegated by the owner
|
||||
and taken.** The one route that looked left in policy, a signature-free call counter on a
|
||||
named export, was weighed and refused: the thunk declares nothing, but installing it still
|
||||
inline-patches Intel's code inside the game process, and the same licence forbids *"any
|
||||
modification"*. FrameLedger has never patched a restricted-licence vendor binary — the NGX
|
||||
answer was the census, not a cleverer hook — and Intel gets the same answer. It would also
|
||||
have been the only hook entry outside `FL_HOOK_GUARD` and a second language in the
|
||||
Overlay's build, for `Xess` identity alone with no render extents, on a vendor with no
|
||||
test hardware here. `20_OPEN_QUESTIONS` §Scope decisions carries the row and the reversal
|
||||
condition (Intel relicensing the headers). **So 7c is AMD identity, full stop.**
|
||||
2. **AMD 3.1 (`amd_fidelityfx_dx12.dll`, the facade the game calls):** identity is in
|
||||
`ffxCreateContextDescHeader.type` — `FFX_API_CREATE_CONTEXT_DESC_TYPE_UPSCALE` vs
|
||||
`…_FRAMEGENERATION` — read from the argument of a hooked `ffxCreateContext`, which is the
|
||||
same class of read as `slEvaluateFeature`'s `inputs` (rule 4). `ffxDispatch` with a
|
||||
frame-generation dispatch desc fires **once per application frame** and is this vendor's
|
||||
`slGetNewFrameToken`; an upscale dispatch desc carries `renderSize` / `upscaleSize`, which
|
||||
is `renderW/H` exact. **Module-scope every row to the facade**: three modules export the
|
||||
same five names, and the plugin modules are called by the facade, not by the game — an
|
||||
unscoped hook would count each dispatch twice, straight into `fg_factor`.
|
||||
3. **AMD 3.0 (`ffx_fsr3_x64.dll`, Cyberpunk's copy):** named exports, no struct decode needed —
|
||||
`ffxFsr3ContextDispatchUpscale` for identity and extent, ~~`ffxFsr3DispatchFrameGeneration`
|
||||
once per application frame~~ *(built 2026-09-05 without the FG row: on the one title the
|
||||
monolith generates and the count is Streamline's; the host's FG export fires per generated
|
||||
batch and is not a count producer. §H11 carries the reversal condition.)*
|
||||
4. **Intel — closed at the census (step 1).** No hook on any `libxess*.dll` export. The
|
||||
report line for an Intel title is what the writer already produces: upscaler
|
||||
`NOT_REPORTED`, and if `libxess_fg.dll` is in the census, Presented FPS with the *"MAY
|
||||
include generated frames"* qualifier rule 6's amendment requires. `renderW/H` stays
|
||||
`NOT_REPORTED` for XeSS *by licence, not by ignorance* — the report's wording should say
|
||||
so, which is a string change, not a hook. Note that census presence is not identity:
|
||||
Cyberpunk loads `libxess.dll` at DLSS, so the census must never be read as *"XeSS on"*.
|
||||
5. **Acceptance, against the titles' own menus:** Lies of P at FSR + FG prints
|
||||
`upscaler: Fsr3`, `frame generation: FsrFg`, and the trio at ≈ ×2 with the same
|
||||
`presents / dispatches` arithmetic; Hell Is Us at FSR prints identity where today it prints
|
||||
the off run's line; Cyberpunk at XeSS prints upscaler `NOT_REPORTED` and the census
|
||||
sentence with `libxess.dll` named, and nothing that reads as identity. **A wrong preset name degrades
|
||||
silently** — the histogram and `tokens/batch`-style second count are what make a mistake
|
||||
visible, so build the per-vendor second count before trusting the first.
|
||||
|
||||
**Traps carried from the Streamline work that apply verbatim:** the vendor's zero is not our
|
||||
zero (resolve at the writer); a vendor keeps a NAME and changes a SIGNATURE (`SpeaksExpectedAbi`
|
||||
needs an AMD and an Intel arm); the K = 1 / K = 4 harness pair must exist before the first
|
||||
real-title run, or a writer that counts presents instead of dispatches is green everywhere.
|
||||
|
||||
</details>
|
||||
|
||||
### Separable
|
||||
|
||||
`fl-probe-signer` → §S19(b) → drop `-SkipIntegration`. **Not** a prerequisite of the
|
||||
feature hooks — §S29(a) said it was and was wrong; see below. What it buys is the
|
||||
*managed* drain being in the merge gate.
|
||||
|
||||
> **The price went up on 2026-08-06 and is worth stating before someone budgets it.**
|
||||
> `Category=Integration` was three cases; it is **nine** — the drain loop, the pause
|
||||
> round trip, the drop path against the real writer, and the capture host's four
|
||||
> end-to-end cases including the only assertion anywhere that `guardTicks` advances
|
||||
> from a non-test binary. All nine run on a dev box and none in the merge gate.
|
||||
>
|
||||
> **And §S19(b) alone does not buy them back.** `build.ps1 -SkipIntegration` applies
|
||||
> `--filter 'Category!=Integration'`, which excludes the class *before* the guard is
|
||||
> ever asked — two independent mechanisms produce one absence, and `ci.yml` has to
|
||||
> drop the switch as well. Anyone costing this as "fix the signer half" is costing
|
||||
> half of it.
|
||||
|
||||
**Picked up 2026-09-06 (the owner's next item after item 7).** The sequence, with what
|
||||
each step needs, so nothing here is started out of order:
|
||||
|
||||
1. **The CI leg, made readable** (2026-09-06, this PR): the probe's ctest printed nothing,
|
||||
so `ci.yml` runs `fl-probe-signer` as its own step after the gate and the answers land in
|
||||
the log. Rows G3/G4/G5 are read off the next run on `main`.
|
||||
2. ~~**The adapters-disabled leg — owner-only, a network setting.** Same three subjects,
|
||||
`ctest fl_signer_probe` (or the exe) with every network adapter disabled, compare the
|
||||
verdicts with `spike-notes` §1. Unchanged → G1; any change → G2 and the route retires.~~
|
||||
**RUN 2026-09-06 by the owner: every verdict unchanged — row G1 (§S19(b)).**
|
||||
3. ~~**The allow-widening bound — owner-only, a decision no PR may take (§S19(b)).**~~ **DECIDED
|
||||
2026-09-06: option 1, the compiled-in allowlist `trustedSigners` may only intersect.**
|
||||
4. ~~**Then the PR:** …~~ **BUILT 2026-09-06 (§S19(b) ✅ BUILT):** `ModuleSignerOrganisation` in
|
||||
`fl_guard_sources.cpp`, `IsCompiledTrustedSigner` as the bound, the trusted module keeps the
|
||||
scan looking, every failure refuses, the catalog half deferred with its rationale, both
|
||||
directions proved against the real seams through `hook-harness --load`, and `-SkipIntegration`
|
||||
dropped from `ci.yml`. **The Separable item is closed**: the nine integration cases are in the
|
||||
merge gate, and CI runs the command a developer runs.
|
||||
|
||||
### ~~§M5 — **START HERE**~~ — MEASURED 2026-09-03, row R1, and the head moves
|
||||
|
||||
**Do not start here.** `LhmTelemetrySource` exists, `probe-lhm` ran unelevated and elevated,
|
||||
and both landed on row R1 of the table pre-committed in §M5: eight GPU fields with no
|
||||
elevation and no PawnIO. Status is in §M5, `spike-notes` §10 and `CHANGELOG.md`. What
|
||||
belongs here is the **sequencing consequence**: the three user-facing sentences stand, so
|
||||
nothing in `README`, `legal/EULA.md` or the consent disclosure is waiting on telemetry any
|
||||
more, and the `LibreHardwareMonitorLib` loose end below is closed by having a consumer.
|
||||
|
||||
~~**The live head is now the FPS-display rule, decided by the owner on 2026-09-03 and
|
||||
recorded in no other file until its PR lands:**~~ **LANDED the same day** — `03_METRICS`
|
||||
§Presented FPS and §Rung 0's qualifier, `fl_shm.h` §FlRuntimeCensus, `17_HOOK_ENGINE`
|
||||
§Watchdog observations, CLAUDE.md rule 6's amendment. Status is in `CHANGELOG.md`. ~~**What is
|
||||
still open from it is the owner's:** the two real-title captures that would show the two
|
||||
qualifiers on real games (Cyberpunk 2077 → WARNING naming `nvngx_dlssg.dll`; any D3D11
|
||||
title with no upscaler → "cannot include"), one launch each. The fixtures prove both
|
||||
directions natively; the titles would prove the names.~~ **RUN THE SAME DAY, six titles,
|
||||
`spike-notes` §9.** Both shapes seen; the names are the loader's; one refusal
|
||||
(`TargetAmbiguous`, NW.js) became a scope row; Hell Is Us became the third title where DLSS is
|
||||
on and `slEvaluateFeature` sees nothing. The decision text is kept below
|
||||
because the reasoning lives in no other file. When frame generation is *not measured*
|
||||
(`FL_MEASURED_FG` clear — every non-Streamline title today, and every Streamline title
|
||||
on the measured route), the headline is **Presented FPS** (`presents / D`, the name for the
|
||||
one number that stands alone; "Native" and "Displayed" appear only together), with a
|
||||
mandatory qualifier chosen by a **runtime-module census** run on the Overlay's watchdog
|
||||
and published in `FlWriterState`. **The census never produces `FL_FG_NONE` or
|
||||
`FL_UPSCALER_NONE`** — statically linked FSR has no module to see, and a census-`none` on
|
||||
such a title would print the inflated number rule 6 forbids. It refines the *reason* for
|
||||
N/A and warns loudly when a frame-generation runtime is loaded and nothing was observed.
|
||||
The two cases that motivated it print identically today: a 2D title with no upscaler, and
|
||||
a Streamline title with upscaling switched off in its settings. **`SL loaded + zero calls ≠
|
||||
off`** (Black Myth: Wukong) is why the second may not become `none` either.
|
||||
|
||||
<details>
|
||||
<summary>The entry as it stood while it was the live head, kept for the reasoning</summary>
|
||||
|
||||
**Do GPU sensors work unelevated, without PawnIO?** It used to decide how ADR-9 read to
|
||||
users. It now decides whether a sentence **already in `README`, `legal/EULA.md` and the
|
||||
operator consent disclosure** is true.
|
||||
|
||||
The two-rung ladder says a Tier-2 session records *"session duration and whatever hardware
|
||||
telemetry this machine can provide"*. That hedge is there because **nobody has measured
|
||||
this**. If LHM needs elevation for GPU sensors, the DEFAULT unelevated Agent's Tier-2
|
||||
session is **duration only** — and the honest wording is narrower than what those three
|
||||
documents now carry. The hedge is deliberate and it is also a placeholder: it buys
|
||||
correctness at the cost of telling a user something useful.
|
||||
|
||||
`18_GPU_VENDOR_APIS` §P0 item (b) already specifies the test and the dev box can run it. It
|
||||
needs `LhmTelemetrySource`, which does not exist — so the first slice of P0 item 8 is now
|
||||
the cheapest way to make three user-facing documents say something definite.
|
||||
|
||||
**This heading sits under §Separable on purpose, and it is still the live one.** §M5 is not a
|
||||
prerequisite of any feature hook — nothing in the queue above waits on it. It is here because
|
||||
it is the smallest piece of work that makes an already-shipped claim definite, which is a
|
||||
better place to restart than a decision nobody has taken.
|
||||
|
||||
**Two other things are open and neither is this.** Item 6 — written rationales for every
|
||||
❓/⏳/◐ still in §S24, and unifying the glyphs — is P0 **exit criterion 2** itself and is pure
|
||||
editorial; take it if you want P0 closer to done rather than more correct. And `fl-probe-signer`
|
||||
→ §S19(b) above buys the managed drain a place in the merge gate. Both are real; neither has a
|
||||
claim in a legal document depending on it.
|
||||
|
||||
**Why this and not the frame-generation route.** Item 3's producer decision is unblocked and
|
||||
unmade, and whoever takes it chooses **with no oracle behind the choice** (§S31 row P2, and
|
||||
`14_TESTING`'s cross-validation gate struck the same day). That is a decision to take
|
||||
deliberately, not a task to pick up. §M5 is a measurement with a specified method, a machine
|
||||
that can run it, and a claim already shipped that depends on the answer.
|
||||
|
||||
Rest of P0 item 8 telemetry: `BaselineTelemetrySource` (L1), `NvapiTelemetrySource` (L3 — the
|
||||
material is vendored and `fl_nvapi_probe` proves it works). ~~and the PresentMon binary for
|
||||
`spike-notes` §11~~ — that section is filled and PresentMon is gone.
|
||||
|
||||
~~Also loose: `LibreHardwareMonitorLib` is referenced by `FrameLedger.Infrastructure`
|
||||
and used by **zero lines**, so it ships into the Agent's output — an MPL-2.0 §3.1
|
||||
redistribution obligation incurred for no capability. Either L2 gets written or the
|
||||
reference comes out.~~ — **L2 was written, 2026-09-03.** The obligation now buys eight fields.
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,97 @@
|
||||
# HANDOFF history — P2 — the Agent, the recorder, SQLite (D1–D10)
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## ~~P2 — **START HERE**~~ — CODE COMPLETE 2026-09-10; the live head is §P3 below (struck 2026-09-13 so this file holds one START HERE, not two)
|
||||
|
||||
P1's core is merged (`15_ROADMAP` §P1). What comes next is P2 — the Agent, the recorder,
|
||||
SQLite — and this section carries its **order**, the **decisions that live in no other file**,
|
||||
and what each slice must make fail on unmodified `main`. Status lives where it lives.
|
||||
|
||||
> ### What is left, as of 2026-09-10: **two measurements, no code.**
|
||||
>
|
||||
> All nine slices below are written and their gates are green (PR-0 #143, A #144, B #145, E1 #146,
|
||||
> C #147, D #148, E2 #149, F #150, G #151 — ~~stacked and open~~ **all merged 2026-09-10**). What P2
|
||||
> still owes is what a PR cannot produce:
|
||||
>
|
||||
> 1. **The milestone session** — a real title, Tier 1, its `upscaler` / render→output / `fg_mode` /
|
||||
> `rt_flag` read against the game's own settings menu. The *technical* half is in the merge gate
|
||||
> (`AgentEndToEndTests`: the shipped Agent, `hook-harness`, one hooked row), and the harness has
|
||||
> no upscaler to measure, which is exactly what the real title supplies.
|
||||
> 2. **The ≤ 0.5 % FPS-impact run** (`14_TESTING` §Hook overhead item 2, P1's last debt via §R4).
|
||||
> `tools/fps-impact-runbook.ps1` sequences it; the number it needs is the game's own benchmark
|
||||
> average, which only the operator can read.
|
||||
>
|
||||
> Both have slots, with the exact commands, in `docs/spike-notes.md` §14 — plus §S1's
|
||||
> launcher-fronted election run, whose code is built and whose first real launcher is still owed.
|
||||
> **Nothing in that section has been run.** Do not read an empty table as a passing one.
|
||||
|
||||
**The order, one PR each, merged one at a time** (`main` is `strict: true` — every merge puts
|
||||
the next PR `BEHIND`, and every PR touching `src/` conflicts in `CHANGELOG.md`):
|
||||
|
||||
| PR | Slice | Fails on unmodified `main` because… |
|
||||
|---|---|---|
|
||||
| A | `FrameLedger.Domain.Metrics` + golden tests; the CaptureHost's throwaway consumer re-pointed at it | no type in Domain computes a frame time, and `tools/coverage-gate.ps1` prints `metric calculators none found` — the 95 % floor has never been evaluated against anything |
|
||||
| B | SQLite core: `0001_init.sql`, migrations, blob codecs, `SqliteGameConsentStore`, repositories | `Microsoft.Data.Sqlite` and `Dapper` are referenced by zero lines; `IGameConsentStore` has one adapter and it is a file in an unshipped host |
|
||||
| C | Promote the capture path (`CaptureLoop` → `Application.Capture.CaptureSession` + Infrastructure adapters); the CaptureHost becomes a thin shell | every capture type is `internal` to `FrameLedger.CaptureHost`, and the Agent referencing it turns `package-closure-check` red |
|
||||
| E1 | Telemetry L1 (`BaselineTelemetrySource`), `CompositeTelemetrySource`, the 1 Hz poller | `IGpuTelemetrySource` has one adapter; nothing produces the `l1+lhm+nvapi` descriptor or stamps a sample with the session QPC epoch |
|
||||
| D | Session recorder: state machine, `.partial`, five-step finalize, exit classification, crash auto-disable, recovery | nothing persists a session; no `.partial` is ever written; `exit_status` has no producer |
|
||||
| F | Agent Generic Host: DI, watcher, `DescendantElection`, `--serve` / `--console`, kill switch, consent verb | `Agent/Program.cs` is 61 lines that seed the rules file and exit |
|
||||
| E2 | NVAPI bridge (native `FrameLedger.NvapiBridge.dll`, C ABI) + L3 + the NGX probe in-process | the only NVAPI consumer is `fl-probe-nvapi.exe`, unshipped and spawned |
|
||||
| G | Real-title milestone, kill-and-recover e2e, the ≤ 0.5 % FPS-impact run, doc sweep | no `ledger.db` anywhere holds a hooked session; `14_TESTING` §Hook overhead item 2 has no number |
|
||||
|
||||
**Why A first:** it is pure, it arms the 95 % gate *before* any calculator exists (the gate's own
|
||||
rationale), and every later slice consumes it. **Why D before F:** the orchestrator is thin over the
|
||||
recorder; building F first re-creates the recorder inside the Agent. **Why E2 after F:** the
|
||||
milestone must not wait on a new native target crossing every gate — it lands LHM-only
|
||||
(`telemetry_source = 'l1+lhm'`) and L3 joins afterwards.
|
||||
|
||||
**Decisions taken 2026-09-09 (owner), so nobody re-derives them:**
|
||||
|
||||
- **D4 — the Agent ships `--console consent grant`.** It prints the operator disclosure, requires a
|
||||
typed acknowledgement, and stamps `hook_consent_at` from the Agent's own clock under a new
|
||||
`ConsentProvenance.AgentConsoleOperator` — the stamp `19_SAFETY` §User-facing consent requires and
|
||||
a file store cannot uphold. **This changes the basis §S27 was closed on**: the Agent becomes the
|
||||
shipped injecting entry point *by design* (`01_ARCHITECTURE` always said so); what holds rule 1
|
||||
is the consent store, its provenance and the disclosure, and `package-closure-check` keeps only
|
||||
the CaptureHost out. Restate §S27 and §S18 blocker 3 in the PRs that do it (C, F); the
|
||||
re-ratification is the owner's (below). P3's dialog retires the console provenance.
|
||||
**Built 2026-09-10 (PR-F):** `Agent --console consent grant`, `OperatorDisclosure` moved to
|
||||
`Application.Consent` with an `OperatorSurface`, `ConsentProvenance.AgentConsoleOperator`, the
|
||||
acknowledgement carrying its provenance and the store refusing a nameless one.
|
||||
- **D7 — the FR-2.4 kill switch is the FOURTH input of `HookedCaptureGate`**, not an upstream
|
||||
check: the gate's own remark calls itself *"the ONLY managed logic between the user's intent and
|
||||
the guard"*, and a global switch is intent. `HookRequest.FromConsent` gains the parameter. The
|
||||
Vulkan layer honours it by the Agent **not** setting `FRAMELEDGER_ENABLE_VK_LAYER`; mid-session it
|
||||
is `unhookRequested`. **Built 2026-09-10 (PR-F):** `HookRequest.FromConsent(…, killSwitchEngaged)`,
|
||||
`AntiCheatRefusalReason.KillSwitchEngaged` (27, mirrored natively), `IKillSwitch` read by
|
||||
`CaptureSession` before the request and at every scan boundary, `ProcessLauncher(enableVulkanLayer:
|
||||
false)`, `settings.hooking.kill_switch`, `Agent --console killswitch on|off|status`.
|
||||
- **D8 — FR-11 is NOT a consent precondition in P2.** `ILegalAcceptanceStore` (read-only ~~until P3~~ — the writer exists since P3 PR-3, the gate that calls it is PR-9's) is declared
|
||||
in B so the precondition is one `if` when the owner turns it on.
|
||||
- **D9 — P2 never clears `hook_blocked_reason`.** A tri-state `hook_prescan_state`
|
||||
(`not_run|clean|blocked|unverified`) carries *could not verify* without touching the column
|
||||
(`06_DATA_MODEL` §games' open question stays the owner's).
|
||||
- **No `FlWriterState` field may be added** — it has no slack (every reserved word was taken
|
||||
2026-09-03/05/06), so any new field is a layout bump. P2 needs none: finalize's "stop writing" is
|
||||
`SetPaused`, and every counter to be stored already exists. `FlControlBlock.Reserved[11]` is the
|
||||
Agent-side slack if one is ever needed.
|
||||
- **D1 — `FrameLedger.Application` gains a reference to `FrameLedger.Shared`** (A); Domain still
|
||||
references nothing and mirrors the record enums with a bidirectional test.
|
||||
- **D10 — the pipe (`07_IPC`) is P3**, not P2; `--serve` is watcher-driven and logs. **No `EtwFrameSource`**
|
||||
(§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. *(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.)*
|
||||
|
||||
**What P1 still owes, and where it lands:** the ≤ 0.5 % real-game FPS-impact measurement
|
||||
(`14_TESTING` §Hook overhead item 2, moved to the end of P1 by §R4) needs the drain and the
|
||||
recorder to exist — it runs in **G**; §S1's first real-title launch-mode run and the descendant
|
||||
election are **F** and **G**; the ⏳ feature rows in `17_HOOK_ENGINE` §Hook inventory are not P2 —
|
||||
their columns (`hdr_flag`, `pt_confidence`, `pso_stutter_pct`, `vram_proc*`, `latency_*`) are an
|
||||
honest NULL in P2's schema, never a 0.
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
# HANDOFF history — P3 — the App (D11–D17)
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## P3 — ~~**START HERE**~~ (2026-09-13, owner-approved plan; **code-complete 2026-09-14** — every row below is struck with its PR)
|
||||
|
||||
`15_ROADMAP` §P3 is the UI — and since 2026-09-13 it is **all of `08_UI`**, Settings, Logs, the tray
|
||||
and the first-run Legal Gate included (the owner chose the full surface over a shell-first cut; the
|
||||
roadmap's §P3/§P4 split is amended to say so). Two items P2 deliberately left standing are P3's
|
||||
first, and both are *replacements* rather than new ground:
|
||||
|
||||
1. **The pipe (`07_IPC` §C).** Decision D10 put it here. The P2 Agent has no client: `--serve` logs
|
||||
to `%LOCALAPPDATA%\FrameLedger\logs\agent-*.log` and `--console` prints. `04_CAPTURE`
|
||||
§Threading model already says where the reader joins — one more producer, never a second reader
|
||||
of the ring — and `07_IPC` §Messages is written and unimplemented. `SessionProgress` at 1 Hz is
|
||||
what makes the Dashboard's live card worth having.
|
||||
2. ~~**FR-2.1's consent dialog, which retires `ConsentProvenance.AgentConsoleOperator`.**~~ **LANDED 2026-09-13 (PR-4)** — the dialog, the `Shared` family, `ConsentProvenance.ConsentDialog` and the Agent's stamp; the console verb is not retired but demoted to the developer path (`19_SAFETY` §User-facing consent). The paragraph below is kept as the reasoning that held until then. The console
|
||||
verb exists because the reviewed wording does not: `09_I18N` reviews `Safety_*` strings as legal
|
||||
text in en/vi/ja, and ~~no `.resx` exists anywhere in this tree~~ (the App's shell family exists
|
||||
since PR-2, 2026-09-13, under the audit; `Shared`'s `Safety_*` family is still this item's). The
|
||||
dialog is the first thing that needs a REVIEWED one. When it lands, the enum gains its FR-2.1 member, the console verb becomes the
|
||||
developer path it always said it was, and `19_SAFETY` §User-facing consent stops carrying an
|
||||
exception. **Do not add the enum member before the reviewed text exists** — a declared value no
|
||||
code can produce is the §S29(c) shape, and `GameConsentRecordTests` turns red on purpose.
|
||||
|
||||
Everything else in P3 is `08_UI` and `16_WPFUI_SYNTAX` as written.
|
||||
|
||||
> ### What P2 still owes while P3 runs — measurements, not code
|
||||
>
|
||||
> `spike-notes` §14 holds four empty slots and says in its first line that nothing in it has been run:
|
||||
> the milestone session on a real title against its own menus (§14.1), §S1's launcher-fronted election
|
||||
> (§14.2), the ≤ 0.5 % FPS-impact run (§14.3) and §H7's six overlays (§14.4). All four are the owner's,
|
||||
> none blocks a P3 slice, and a P3 session must not read an empty table as a passing one.
|
||||
|
||||
**The order, one PR each, merged one at a time** (`main` is `strict: true`; every PR touching `src/`
|
||||
conflicts in `CHANGELOG.md` — §Traps). Each row names what makes it fail on unmodified `main`,
|
||||
because a criterion already true on `main` is decoration.
|
||||
|
||||
| PR | Slice | Fails on unmodified `main` because… |
|
||||
|---|---|---|
|
||||
| 0 | P2 sweep: the doc/tool drift PR-G left (`coverage-gate.ps1` prose, `13_CI_CD`'s count and its signer-probe claim, `09_I18N`'s member count, `17_HOOK_ENGINE`'s §H9 cite, this file's D-labels, `ci.yml`'s census comment), this head, the roadmap amendment | `grep -n "exactly two members" docs/09_I18N.md` matched; `§H9` resolved to nothing; two START HEREs |
|
||||
| ~~1~~ | ~~**The pipe, read half**: `Shared.Ipc` contracts + `JsonSerializerContext`; the Agent's `PipeServerHostedService`; `Hello`/`HelloAck`, `GetStatus`/`StatusAck`, `Ping`/`Pong`; the events (`SessionStarted`/`Progress`/`Completed`/`CaptureRefused`/`CaptureDegraded`/`SafetyUnhook`/`CaptureError`); a 1 Hz `SessionProgress` publisher; `Infrastructure.Ipc.PipeClient`~~ **LANDED 2026-09-13** — status in `CHANGELOG.md`; `07_IPC` §C carries what was built and the one deviation (`etwAvailable` struck) | ~~`grep -rn NamedPipeServerStream src` is empty; `FrameLedger.Shared` holds no JSON type; `04_CAPTURE` §Live progress has no producer~~ |
|
||||
| ~~1b~~ | ~~**The pipe, command half**: `SetWatchlist` (identity only), `SetHookEnabled` (the Agent re-scans and stamps), `LaunchGame`, `PauseCapture`/`ResumeCapture`, `StopSession`, `UpdateRules` (a trigger, no payload), `Shutdown`~~ **LANDED 2026-09-13** — status in `CHANGELOG.md`; `07_IPC` §Messages carries each row as built. **One thing stayed with PR-4 on purpose:** `SetHookEnabled true` stamps nothing — the pre-scan runs and a block is recorded, then `Error DisclosureUnavailable` — because the reviewed text it would stamp against does not exist, and a member no code can produce is the §S29(c) shape | ~~the Agent accepts no command from outside; `CaptureOrchestrator` has no stop/pause surface; `SetHookEnabled` has no handler~~ |
|
||||
| ~~2~~ | ~~**resx + the App shell**: `Strings.resx` en/vi/ja for App and Shared, the generated class, `tools/resx-audit.ps1` (+`-SelfTest`) as `build.ps1` step 15; the Generic Host bootstrap, `FluentWindow`, TitleBar/Menu/NavigationView, theme + persistence, `INavigationService`, Serilog `ui-*.log`, five empty pages, the Agent status pill over `Hello`, auto-start of `--serve` on connect failure; `tests/FrameLedger.App.Tests`~~ **LANDED 2026-09-13** — status in `CHANGELOG.md`; `08_UI` §Shell and `16_WPFUI_SYNTAX` §App bootstrap carry what was built and the deviations. **Two things moved on purpose:** `Shared`'s family waits for PR-4 (it would hold only `Safety_*`, and an empty family is what the audit refuses), and the generator is ours (`tools/resx-gen.ps1`, committed output) because the SDK-style WPF project runs no `ResXFileCodeGenerator` | ~~`find . -name '*.resx'` is empty; step 15 prints "skipped loudly"; `App.xaml` uses `StartupUri` and `MainWindow` is a plain `Window`~~ |
|
||||
| 2b *(owner decides)* | `FL_MOCK=1` / `Agent --serve --mock`, `--data-dir` only: a `MockSessionSource` hosted service that emits pipe events and inserts synthesised sessions through `ISessionRepository` — and can never resolve `HookedCaptureGate` (asserted) | CLAUDE.md says "specified but not implemented"; `grep FL_MOCK src` is empty |
|
||||
| ~~3~~ | ~~**Ports the UI reads and writes**: `ISessionRepository.ListByGameAsync` / segments / sensors, `ISessionAnnotationRepository`, `ILegalAcceptanceStore.RecordAsync`, `IGameRepository.UpdateMetadataAsync` / `RemoveAsync`, the **settings registry** (closes §G's row — D16 below), `IRtOverrideRepository` (FR-8.3), `display_res`/`display_hz` producer; tests for the four PR-B adapters that have none~~ **LANDED 2026-09-13** — status in `CHANGELOG.md`; `06_DATA_MODEL` §Settings registry, §Writer ownership and §Migrations (schema 0002) carry what was built. **One deviation on purpose:** there is no `IRtOverrideRepository` — the FR-8.3 per-session overrides are columns on `session_annotations` (the UI's table) written through `ISessionAnnotationRepository`, and the game defaults through `IGameRepository.SetTriStateDefaultAsync`, because an override on `sessions` would have been the UI writing the Agent's table; `Application.TriState.TriStateResolution` is the precedence (manual → measured → inherited → N/A) | ~~no port lists sessions by game; `session_annotations` has no repository; `legal_acceptance` has no writer; `ISettingsStore`'s own doc calls the registry open~~ |
|
||||
| ~~4~~ | ~~**FR-2.1's consent dialog**: `Safety_*` en + vi (ja marked `safety: human review required`, shown as en) in `Shared`, `SafetyDisclosureVersion`; `ConsentProvenance.ConsentDialog` whose only producer is the Agent's `SetHookEnabled` handler; `HelloAck.disclosureVersion` and the App **refusing to open the dialog** on mismatch (§S23-1's shape); the dialog itself per `19_SAFETY` §User-facing consent; FR-2.2's disabled toggle with the reason inline; FR-2.5's InfoBar; `GameConsentRecordTests`, `19_SAFETY`, `09_I18N` and item 2 above updated~~ **LANDED 2026-09-13** — status in `CHANGELOG.md`; `19_SAFETY` §User-facing consent carries what was built. **Two things wait for PR-5 on purpose:** FR-2.2's disabled toggle and FR-2.5's InfoBar are the game page's controls, and the page does not exist yet — their text (`Safety_Blocked_Toggle_Format`, `Safety_AutoDisabled_Format`, `Safety_Refused_*`, `Safety_Unhooked_Format`, `Safety_RecordWithoutMeasuring`) shipped here so the reviewed family is complete before anything renders it | ~~`Enum.GetNames<ConsentProvenance>()` has three names; no `Safety_*` key exists; `19_SAFETY` still carries the console exception~~ |
|
||||
| ~~5~~ | ~~**Games + Dashboard**: the grid, game detail (header, **Supports** vs **Last session measured**, the hooking control → PR-4's dialog, the Sessions tab), Dashboard (Agent status + capability badges, the live card over `SessionProgress`, recent sessions, totals), FR-1.1 add / FR-1.4 remove; `FpsReadout` and `TriStateChip`~~ **LANDED 2026-09-14** — status in `CHANGELOG.md`; `08_UI` §Dashboard and §Games carry what was built. **Deferred on purpose:** the card sparkline and the chip override flyout (PR-6, with the charts), the capability badges and Repair on the Agent card (PR-8, with the Agent section), a dropped `.lnk` (needs the shell-link reader) | ~~no page binds a `SessionRow`; nothing renders `62 → 118 FPS (×1.9 FG)`; `SessionProgress` has no consumer~~ |
|
||||
| ~~6~~ | ~~**Session summary + charts**: `ChartTheme` + `ChartPalette.xaml`, min/max decimation (FR-5.3), frametime timeline with stutter markers, segment ribbon and sensor overlay, distribution, the summary window (stat cards, chips + override flyout, crash InfoBar, tags/notes), CSV/JSON/PNG export, the post-session toast~~ **LANDED 2026-09-14** — status in `CHANGELOG.md`; `08_UI` §Session summary and `16_WPFUI` §ScottPlot theme sync carry what was built. **Two things on purpose:** the override is a `ContentDialog`, not a `ui:Flyout` (a flyout anchored to a chip inside an `ItemsControl` has no reliable placement target across the three places chips appear), and FR-3.8's toast is an in-app notice until the tray exists (PR-8) — the "View" action needs a balloon with an action, which the snackbar has not | ~~no ScottPlot plot exists; no decimator; no exporter~~ |
|
||||
| ~~7~~ | ~~**Trend / Sensors / Latency / Compare**: hardware-change markers (FR-6.3), the mid-session-change exclusion + toggle (FR-6.4), sensors with per-process and adapter VRAM as separate series, the latency tab, Compare 2–5 with the **mixed-tier `ContentDialog` guard** (FR-6.2) and tier legend~~ **LANDED 2026-09-14** — status in `CHANGELOG.md`; `08_UI` §Games (tabs 2–6) and §Compare carry what was built. **One thing on purpose:** the tier grouping is done in memory over the loaded rows (`06_DATA_MODEL` §Comparison safety's rule is that a comparison never crosses tiers unasked — `TrendSeriesBuilder` takes hooked rows only and `CompareViewModel` gates the mix), not as a SQL `GROUP BY capture_tier`; the row's criterion said "query" and the honest statement of what holds the rule is the two classes | ~~no query groups by `capture_tier`; no Compare page~~ |
|
||||
| ~~8~~ | ~~**Settings + safety UI + Logs + tray**: FR-10 with the kill switch first, hook-enabled list + revoke, Vulkan layer state with real `--register-vklayer`/`--unregister-vklayer`, language switch, retention, the Agent section with real `--install-task`/`--uninstall-task`, privacy opt-in; the **safety notices** (`CaptureRefused`/`SafetyUnhook`/auto-disable as persistent InfoBar or dialog, never a toast, with "record this session without measuring it"); the Logs page; the tray with FR-3.9; the App's `--diag`~~ — **struck 2026-09-14: 8a (#162) built Settings, the safety notices, Logs and `--diag`; 8b built the tray (H.NotifyIcon, four states, pause over the pipe, the FR-3.8 balloon only while the window is off screen), the four Agent maintenance flags (the logon task through the Task Scheduler COM API — `schtasks` is denied unelevated; the HKCU layer value) and the Settings buttons over them. Two honest gaps in `17_HOOK_ENGINE` §Vulkan's built note: the register/unregister-on-consent automation needs the "is Vulkan" fact (P4), and a registration buys nothing until background capture sets the enable variable.** | ~~the kill switch has a console verb only; `AgentCommandLine.NotImplementedFlags` still lists five; no Logs page~~ |
|
||||
| ~~9~~ | ~~**First run + Legal Gate (FR-11) + closing sweep**: the four documents from `legal/*.md` through `ILegalAcceptanceStore.RecordAsync`, re-shown on a version increment, the Agent-setup and hooking-explainer screens, D8 unchanged unless the owner turns it on; the docs sweep (`01_ARCHITECTURE`, `07_IPC`, `19_SAFETY`, `09_I18N`, CLAUDE.md, this section struck); NFR-4 measured~~ — **struck 2026-09-14: built (`08_UI` §First-run flow built note carries the gate, the embedded documents, the version rule and the NFR-4 numbers; `06_DATA_MODEL` §legal_acceptance and `20_OPEN_QUESTIONS` §G's versioning row say who writes the version). D8 unchanged.** | ~~no code writes a `legal_acceptance` row; the App has no first run~~ |
|
||||
|
||||
**Why this order:** the pipe (1) first because the Dashboard's live card (5), the consent stamp (4) and
|
||||
the tray's pause (8) all need it; resx (2) before the dialog (4) because the dialog is the first thing
|
||||
that needs a reviewed `.resx`; ports (3) before Games (5) because every page reads through a port;
|
||||
charts (6) after Games (5) because the summary opens from the Sessions tab; Settings and the Legal Gate
|
||||
(8–9) last because nothing depends on them and the roadmap used to place them in P4.
|
||||
|
||||
**Decisions taken 2026-09-13 (owner, with the plan), so nobody re-derives them:**
|
||||
|
||||
- **D11 — the pipe's transport.** `Infrastructure.Ipc.PipeServer` over ~~`NamedPipeServerStream`
|
||||
(`PipeTransmissionMode.Message`, `PipeOptions.Asynchronous | CurrentUserOnly`, remote clients rejected,
|
||||
two instances), the ACL a `PipeSecurity` of the current user's SID plus Administrators~~ **`CreateNamedPipe`
|
||||
itself (CsWin32), so the flags and the DACL are stated in code rather than left to a library default:**
|
||||
message mode, overlapped, `PIPE_REJECT_REMOTE_CLIENTS`, two instances, the SDDL ~~`D:P(A;;GA;;;<user>)(A;;GA;;;BA)`~~
|
||||
`O:<user>D:P(A;;GA;;;<user>)(A;;GA;;;BA)` (the owner stated since 2026-09-17) on every instance, and the client's
|
||||
token user compared to the server's by impersonation on the client's first frame (the kernel refuses it earlier).
|
||||
The CLIENT ~~uses `PipeOptions.CurrentUserOnly`~~ checks the pipe's owner against its own token USER
|
||||
(`PipeAccessControl.RequireOwnedByCurrentUser`, 2026-09-17) — `CurrentUserOnly` compares the token's default owner,
|
||||
which an elevated token sets to Administrators, and refused the same user's Agent across elevation (corrected
|
||||
2026-09-27). *(As built
|
||||
2026-09-13; the wording above was the plan's, kept struck because it named a library path the build did not
|
||||
take.)* Framing is
|
||||
`07_IPC` §C as written: 4-byte LE length + UTF-8 JSON ≤ 1 MB, `Shared.Ipc.IpcEnvelope { type, id?, payload }`,
|
||||
`IpcJsonContext : JsonSerializerContext` on the `RecordingJsonContext` pattern, unknown fields ignored and
|
||||
tested in both directions.
|
||||
- **D12 — commands join as one more producer.** A `Channel<AgentCommand>` with a single consumer
|
||||
(`PipeCommandHostedService`) that calls `CaptureOrchestrator` — which gains `StopSessionAsync(guid)` and
|
||||
`SetPaused(bool)`, the latter reaching `ShmRingReader.SetPaused` on the session loop's own task, never
|
||||
from the pipe thread (`04_CAPTURE` §Threading model; `NoSecondRingReaderTests` stands). `SetHookEnabled true`
|
||||
is: the static pre-scan (`RecordGuardBlockAsync` on a block) → `RecordOperatorAcknowledgementAsync` with
|
||||
`Provenance = ConsentDialog`, the disclosure version from the Agent's own copy of the string, and
|
||||
`AcknowledgedAt` from the Agent's clock. A client can request; it cannot attest (`07_IPC` §The pipe is not a
|
||||
trust boundary). *(As built 2026-09-13, PR-1b: **no `Channel` and no `PipeCommandHostedService`** — the
|
||||
handler runs on the pipe client's reader task and the orchestrator's running-session table gained one lock;
|
||||
two commands did not justify a queue and a second place a start can wait. The pause is `CapturePause`, read by
|
||||
the loop at each tick and told to the ring once per transition. The stop is the session's own token in
|
||||
`RecordRequest`, ending the loop as `StoppedByUser`. The stamp branch is PR-4's, exactly as written above;
|
||||
until then it answers `DisclosureUnavailable`.)*
|
||||
- **D13 — `SessionProgress` is a third `ICaptureObserver`.** `ProgressPublisher` in `AgentRecording`,
|
||||
rate-limited to 1 Hz inside `Tick`, snapshots the live lists there and never holds them; `nativeFps5s` /
|
||||
`displayedFps5s` / `fgFactor` come from Domain's calculators over the last 5 s of records through
|
||||
`FrameSampleMapper`, upscaler and resolutions from the newest record, temperatures and VRAM from the newest
|
||||
`TelemetrySample`. Suppressed when no client is connected. A field that is not measured is null, never 0.
|
||||
- **D14 — `Safety_*` lives in `FrameLedger.Shared`, once.** Both processes reference the same resource;
|
||||
`SafetyDisclosureVersion` is a constant beside it; `HelloAck` carries the Agent's; on a mismatch the App
|
||||
says "restart both" and does not show the dialog — the ring handshake's rule (§S23-1) one layer up.
|
||||
**Built in PR-4 (2026-09-13)** as `Shared.Safety.SafetyDisclosure.Version = consent-dialog/1`; the Agent side
|
||||
also refuses (`Error DisclosureVersionMismatch`) so neither side's check is the only one.
|
||||
- **D15 — the App opens `ledger.db` directly**, under `06_DATA_MODEL` §Writer ownership: it writes `games`'
|
||||
user-editable fields, `session_annotations`, `settings` and `legal_acceptance`, reads everything, and never
|
||||
writes a hook-state column — `IGameRepository` has no method that could, and stays that way.
|
||||
- **D16 — the settings registry** (closes §G's row, written into `06_DATA_MODEL` in PR-3): `ui.language`,
|
||||
`ui.theme`, `ui.start_with_windows`, `ui.minimize_to_tray`, `capture.background`, `hooking.kill_switch`
|
||||
(exists), `capture.min_session_s` (30), `telemetry.interval_ms` (1000; 500–2000), `retention.raw_sessions_per_game`
|
||||
(20), `update.channel`, `privacy.online_metadata` (0), `log.debug` (0). The Agent reads `hooking.*`,
|
||||
`capture.*`, `telemetry.*` and `retention.*` at each session start, so no "setting changed" message is needed;
|
||||
the UI owns the rest. **Built in PR-3 (2026-09-13)** as `06_DATA_MODEL` §Settings registry; two things it
|
||||
settled that this bullet did not say: `retention.raw_sessions_per_game = 0` is unlimited (a sweep that keeps
|
||||
everything, never one that keeps nothing), and an operator's bounded `--seconds N` keeps its bound under any
|
||||
`capture.min_session_s`.
|
||||
- **D17 — `FL_MOCK`, if the owner wants it, is `--serve --mock` under `--data-dir` only** (D6's shape), so a
|
||||
synthetic session can never land in the profile's ledger.
|
||||
|
||||
@@ -0,0 +1,41 @@
|
||||
# HANDOFF history — P4
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 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
|
||||
`--onto origin/main`), reviews the `vi` strings, and signs the `ja` `Safety_*` family when a human can.
|
||||
The owner-only measurements of §P2 (`spike-notes` §14) are still open and still owner-only.
|
||||
|
||||
**P4 is `15_ROADMAP` §P4**, in this order, each a PR that fails on unpatched `main` for a stated reason:
|
||||
~~detection rules engine + `detection-rules.json` validator and fixtures (the anticheat blocklist is already
|
||||
consumed by the guard; the engine/platform/capability halves are not)~~ **LANDED 2026-09-14 (P4 PR-1)** — the
|
||||
engine, validator and corpus already existed; what was missing was a caller and a writer: `DetectionSweep` +
|
||||
`DetectionHostedService` under `--serve`, `IGameRepository.ApplyDetectionAsync` under the provenance rule,
|
||||
schema 0004 for the key's exe half (NOT the consent fingerprint), Tools ▸ Update rules wired, the Supports row
|
||||
filled — status in `CHANGELOG.md`, the decisions in `05_DETECTION` §Caching's built note; ~~store auto-import (Steam / GOG / Epic /
|
||||
itch.io — the first-run flow's step 4 and File ▸ Import library both say "later build")~~ **LANDED 2026-09-14 (P4 PR-4:
|
||||
`LibraryImporter` over four `IStoreLibrarySource` adapters, the review checklist, `ApplyStoreMetadataAsync` under
|
||||
the provenance rule, hooking off for every row — `05_DETECTION` §Platform signatures built note)**, ~~the
|
||||
capability-vs-measured separation in the UI (the game page's Supports row is empty until this)~~ **(PR-1)**, ~~Velopack +
|
||||
the updater (`11_UPDATER`; the Settings channel row is stored and unused)~~ **LANDED 2026-09-14 (P4 PR-5: `App/Update/` — `VelopackUpdateClient` behind `IUpdateClient`, `UpdateService` with FR-12 as its shape, the banner, the install/uninstall hooks in `Program.Main`, `release.yml`, one `VERSION` source — `11_UPDATER` built note)**, ~~the bug-report flow's steps 3–5
|
||||
(`10_LOGGING`: the preview dialog, the GitHub issue link — step 2's bundle exists)~~ **LANDED 2026-09-14 (P4 PR-3:
|
||||
`BugReportFlow`, the preview dialog, the issue link with the form's real field ids, the Markdown clipboard fallback;
|
||||
~~the crash dialog + minidump stay open~~ — they landed 2026-09-15 with PR-9, and the dump is the bundle's opt-in — `10_LOGGING` built notes)**, ~~the "is Vulkan" fact the
|
||||
layer's register/unregister-on-consent automation needs (`17_HOOK_ENGINE` §Vulkan built note)~~ **LANDED
|
||||
2026-09-14 (P4 PR-2): a static PE fact (`PeImports` + the bounded scan) stored as `vulkan` in `capability_flags`,
|
||||
and `VkLayerReconciler` moving the HKCU registration after every consent change and sweep — the built note
|
||||
carries it**, the Help menu's
|
||||
~~Documentation~~ / ~~Check for updates~~ / ~~Report a bug~~ items **(Documentation and Report a bug landed with PR-3;
|
||||
~~Check for updates waits for the updater~~ — PR-5; File ▸ Export became the three-leaf submenu `08_UI` specifies)**, and
|
||||
~~`legal/licenses/` populated by the license-gathering
|
||||
script~~ **LANDED 2026-09-15 (P4 PR-6: `tools/license-gather.ps1` → `legal/licenses/nuget/`, 77 packages, `license-check` §3 both directions; the runtime's notices by `release.yml`)**. Decisions that live only here: D11–D17 below still hold; nothing in P4 may add a third writer to
|
||||
`ledger.db` or a message that carries a safety fact over the pipe.
|
||||
|
||||
`15_ROADMAP` §P4's last two items were not in the list above: ~~DB maintenance~~ **LANDED 2026-09-15 (P4 PR-7:
|
||||
Tools ▸ Database maintenance — the retention sweep on demand is the Agent's, over a new `SweepRetention` command with
|
||||
no payload; integrity check, `VACUUM INTO` backup and compaction run in the App and change no row — `06_DATA_MODEL`
|
||||
§Retention built note)**, and ~~the accessibility pass, which needs `08_UI` §Accessibility written before any code~~ **LANDED 2026-09-15 (P4 PR-8: the section first, then `AccessibilityTests` — Ctrl+1…5, Esc on every dialog, an automation name on every textless input, theme colours only)**.
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# Owner-only items that passed
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` §Owner-only on 2026-10-19 (beta.24, owner decision D66): the items the owner reported passed or took, numbers kept — a number is never reused. The open ones stay in `docs/HANDOFF.md`.*
|
||||
|
||||
3. ~~**Which titles** go in `blockedExecutables` — a product decision with false-refusal
|
||||
consequences. The list ships empty until it is taken.~~ **Taken 2026-09-25 (D30):** per-title
|
||||
lists by Steam id and executable name, seeded and floored (§2026-09-25 — the beta.8 train).
|
||||
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`.
|
||||
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.**~~ **Passed 2026-10-13** — the owner: "Tất cả các item đã đạt yêu cầu" (every item
|
||||
met its requirement). *(The item as written:)* (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.**~~ **Passed 2026-10-13** — the same answer. *(The item as written:)* (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`).
|
||||
18. ~~**beta.22 on real hardware.**~~ **Passed 2026-10-13** — the same answer. *(The item as written:)* (a) The `ja`
|
||||
string marked `review` (`Agent_Unanswered`). (b) Nothing else to run: the change answers a request the agent drops
|
||||
mid-way, which the tests make happen and a person can only meet by chance — if a notice ever says the capture agent
|
||||
did not answer, the page beside it shows what was stored.
|
||||
19. ~~**beta.23 on real hardware.**~~ **Passed 2026-10-15** — the owner: "Item 19 hiện đã đạt 100% yêu cầu" (the item
|
||||
met every requirement). *(The item as written:)* (a) **Artwork:** open the page of a Steam game (one on the D: drive)
|
||||
and of a GOG game — the banner, the cover beside the name, the band's colour; an itch game shows none. With a page
|
||||
open, switch Dark → Light → Dark: the band changes with the theme and every text on it stays readable. (b) **Your own
|
||||
image:** *Edit… ▸ Choose image…* then Save — the page shows it; *Edit… ▸ Use the store's image* — the store's again;
|
||||
choosing an image and pressing Cancel leaves nothing new in `%LOCALAPPDATA%\FrameLedger\covers`. (c) **Settings ▸
|
||||
Games:** *Show game artwork* and *Colour the game page from its artwork* off, then on. (d) **Speed:** open WALTO's
|
||||
page and choose its longest session, switch the page's tabs; visit the Dashboard a few times, then end a session —
|
||||
one "Session saved". (e) The Privacy Policy 2.11 is shown once after the update. (f) The `ja` strings marked
|
||||
`review`.
|
||||
|
||||
@@ -0,0 +1,326 @@
|
||||
# HANDOFF — corrections and traps
|
||||
|
||||
*Moved verbatim from `docs/HANDOFF.md` on 2026-10-19 (beta.24, owner decision D66). Code and documents cite these as `HANDOFF §Traps`.*
|
||||
|
||||
## Two corrections carried forward, because both changed what got built
|
||||
|
||||
- **§S29(a) was wrong and had already re-ordered the work.** It claimed the assertion
|
||||
catching "a mask bit set with no hook behind it" lives only in
|
||||
`ShmDrainIntegrationTests`, which CI skips. It does not: `guard_test.cpp`'s *"the
|
||||
injected Overlay records real presents into the ring"* asserts it, as ctest
|
||||
`fl_guard`, **20.58 s on CI**. `fl_guard_test.exe` is a *native* host and never loads
|
||||
the `protect`-matching .NET assembly — the same §S19(b) mechanism cutting the other
|
||||
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* (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).
|
||||
|
||||
---
|
||||
|
||||
## Traps that cost a cycle each, in this repo
|
||||
|
||||
The mechanical ones live in the toolchain notes; these are the ones that cost a *wrong
|
||||
diagnosis*.
|
||||
|
||||
- **A VERB THAT PRINTS WAS A WRITER UNTIL 2026-09-16, AND THE OWNER'S LEDGER IS NOT A FIXTURE.** `--console
|
||||
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 — 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.
|
||||
- **THE TESTS WRITE INTO THE REAL DATA FOLDER, AND THAT IS NOT A SWITCH TO ADD.** The Overlay's log path is
|
||||
`SHGetKnownFolderPath`, never the environment (§S21), and the tests inject the shipped DLL, so 2492 hook-harness
|
||||
logs had piled up in the owner's `%LOCALAPPDATA%\FrameLedger\logs` by 2026-09-15. Each test binary now sweeps the
|
||||
harness logs it caused (`17_HOOK_ENGINE` §Native logging) and the `test-artifacts` gate is red for one left behind.
|
||||
A new native test executable that starts hook-harness needs the Catch2 listener from `guard_test.cpp`; do not "fix"
|
||||
a red `test-artifacts` by pointing the Overlay somewhere else.
|
||||
|
||||
- **A CHROMIUM-BASED TITLE IS SEVERAL PROCESSES WITH ONE IMAGE PATH.** *Flower in Us* (NW.js /
|
||||
RPG Maker) returned `TargetAmbiguous`, exit 6, on 2026-09-03: three processes match the
|
||||
consented path. The presenting one is the GPU process, which owns no window — so do not "fix"
|
||||
it by picking the windowed one. **Fixed the same day by Chromium's own `--type=gpu-process`
|
||||
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.~~ *(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
|
||||
at 0.22 (§S31 row P4). Key on the frame index, **and on a NEW index only** — frames in flight
|
||||
interleave their requests across threads, so "differs from the last" still over-counts. The stub
|
||||
and harness now reproduce both shapes, so the K = 1 control catches a pointer-keyed writer and
|
||||
a last-index-keyed one.
|
||||
- **THE CENSUS IS A STARTUP PROPERTY ON UE5.** Hell Is Us published the identical census word
|
||||
at off, FSR and DLSS + FG ×4; Lies of P likewise across its three runs. The plugins load at
|
||||
init whatever the settings menu says, so the census can never separate "loaded and off" from
|
||||
"loaded and driven through an unhooked path". It was designed not to try; on 2026-09-03 that
|
||||
stopped being a design note and became a measurement.
|
||||
- **STREAMLINE LOADED + ZERO `slEvaluateFeature` CALLS DOES NOT MEAN "UPSCALING OFF".** Black
|
||||
Myth: Wukong has `sl.interposer.dll` and `sl.dlss_g.dll` loaded, DLSS-G demonstrably running,
|
||||
and never calls the one export this writer hooks. **Hell Is Us made it three of five on
|
||||
2026-09-03**: DLSS on, frame generation ×4, 17,920 records carrying the identity bit, zero
|
||||
batches drained. So a title with upscaling switched off in
|
||||
its settings and a title driving DLSS through an unhooked path produce byte-identical
|
||||
records — every one `UNKNOWN` — and the consumer may not turn that into `none` for either.
|
||||
The 2026-09-03 census can say which vendor runtimes are *present*; it cannot say what the
|
||||
title did with them, and it is written so it never claims to.
|
||||
- **A vendor keeps the SYMBOL NAME and changes the SIGNATURE, and no gate we have can see
|
||||
it.** The Witcher 3 ships `sl.interposer.dll` **1.5.6**: it exports `slInit`,
|
||||
`slEvaluateFeature`, `slSetTag` and `slShutdown`, so every name check passes, and it exports
|
||||
**none** of `slSetD3DDevice` / `slIsFeatureLoaded` / `slGetNewFrameToken`. `slInit`'s
|
||||
`sl::Preferences` has a different layout, so calling it with the vendored 2.x struct
|
||||
**access-violates**. `docs/vendor-exports.json` records **one copy per module NAME**, so
|
||||
`hookinventory-check` Pass A resolves against one machine's 2.7.4 and says nothing about a
|
||||
1.5.6 in a game directory. The guard is `SpeaksStreamline2` in `fl_hook_inventory.h`;
|
||||
**do not weaken it to reach an older title.**
|
||||
- **A vendor enum's zero is not your zero, and this has now happened twice.**
|
||||
`D3D12_RAYTRACING_TIER_NOT_SUPPORTED` is 0 against `rtTier`'s "not queried";
|
||||
`sl::DLSSMode::eOff` is 0 against `upscalerQuality`'s "not measured". Copying the vendor
|
||||
value verbatim publishes an affirmative negative in both cases — and for `upscalerQuality`,
|
||||
0 decodes as "DLSS Performance". **Assume the next one has the same shape**; resolve it at
|
||||
the writer.
|
||||
- **`main` has `strict: true` branch protection, so merging ANY pull request makes every
|
||||
other one `BEHIND`.** A batch of ready PRs cannot be merged in a loop: each needs
|
||||
`gh pr update-branch` after the previous one lands, which re-runs CI (~6–11 min each). And
|
||||
every PR that touches `CHANGELOG.md` under `[Unreleased]` — which is every PR touching
|
||||
`src/` — conflicts with the one before it. Budget the batch accordingly, or merge one at a
|
||||
time and expect to resolve the same conflict repeatedly.
|
||||
- **`gh pr update-branch` can COMMIT literal conflict markers, and GitHub then reports the PR
|
||||
as `BLOCKED` rather than `DIRTY`.** Measured 2026-08-15 on #73: the update-branch merge left
|
||||
`<<<<<<<` / `=======` / `>>>>>>>` inside two source files and pushed them, so CI failed with
|
||||
`error C2059: syntax error: '<<'` and a redefinition. **`DIRTY` is the status that means
|
||||
"conflict", and this was not it** — the PR read as an ordinary red build, so a "re-run CI"
|
||||
reflex would never have reached the cause. After any `update-branch`, grep the branch for
|
||||
markers *before* reading the checks; the whole tree is one command and it is cheaper than
|
||||
one CI round. **Anchor the pattern to the line start** — this very bullet contains all three
|
||||
markers inline, so an unanchored sweep reports this file and teaches you to ignore it.
|
||||
- **Never run a git-manipulating script in the background against the working tree you are
|
||||
working in.** A merge helper doing `git checkout` between branches moved the tree under an
|
||||
in-flight edit, and a documentation commit meant for one PR landed on another branch and was
|
||||
pushed there. Recovery cost a cherry-pick, a `--force-with-lease`, and a re-verification of
|
||||
the *wrong* PR to prove none of its own work had been lost. This is wrong by design rather
|
||||
than by bad luck — the tree has one HEAD, and a background job racing you for it will
|
||||
sometimes win. Use a separate worktree, or keep it in the foreground.
|
||||
- **CI's Integration cases fail on the runner about one run in three, and it is never the code.**
|
||||
Measured 2026-09-10 while merging P2's stack: **three failures in eight gate runs**, every one an
|
||||
`Category=Integration` case, every one green on a re-run of the identical commit. Two shapes were guard
|
||||
scans failing — `GuardedInjectAsync(...).IsAllowed` false (§S19(b)'s fragment/signer shape) and
|
||||
`ProcessTreeUnavailable — could not establish the scan set`, which §S19(b) does **not** cover — and one
|
||||
was a fixture bug this repo owned (a pooled SQLite handle on `ledger.db` outliving `DisposeAsync`, so a
|
||||
recursive `Directory.Delete` threw and xUnit blamed an unrelated test). **Re-run first. If it
|
||||
reproduces, read the module list and the scan-set reason rather than the test.**
|
||||
Two traps inside this one: `ci.yml`'s signer probe — the step that would name the refusing module —
|
||||
runs *after* the gate, so the one run that needed it printed nothing; and `gh run rerun --failed`
|
||||
rewrites the original run's conclusion, so the run history shows those three failures as **successes**
|
||||
and the flake rate reads zero (`13_CI_CD`).
|
||||
- **MA0004 and xUnit1030 are all-or-nothing PER METHOD, in opposite directions.** A test method may
|
||||
not `ConfigureAwait(false)` (xUnit1030) and, once ANY await in it carries a `ConfigureAwait`, MA0004
|
||||
demands one on every other await too — so a helper's `.ConfigureAwait(false)` copied into a test
|
||||
method turns every neighbouring `await` red. Rule: helpers `false`, test methods either none at all
|
||||
or `true` on every await; measured 2026-09-10 across three rebuilds of one test file.
|
||||
- **A Bash heredoc rewrites `\n` inside a Python string even when the heredoc is quoted.** The
|
||||
replacement text arrived with real newlines, the assert that it matched the file failed, and the
|
||||
diagnosis pointed at the file. Write patch scripts with the editor tool and run them by path.
|
||||
- **Anything that writes a file with a script writes LF, and `.gitattributes` hides it until
|
||||
it does not.** `dotnet format --verify-no-changes` is the documented victim, but a Python
|
||||
or PowerShell `write` is the usual cause. `git commit` prints *"LF will be replaced by
|
||||
CRLF"* and then normalises for you — so the COMMIT is fine and the WORKING TREE is not,
|
||||
which is the confusing half. Normalise explicitly after any scripted edit.
|
||||
- **Never run `cmake`/`ctest` directly — always `./build.ps1`.** Without the MSVC
|
||||
environment it imports, configure fails, the build never runs, and ctest executes the
|
||||
**stale binary** and prints `Passed`. Cost two wrong diagnoses in one session.
|
||||
- **Read the build's exit code before the test's**, every time. A canary that fails to
|
||||
compile reports "All tests passed" from the previous binary.
|
||||
- **A canary that dies before reaching the gate looks exactly like a canary that
|
||||
worked.** Check *which* step failed.
|
||||
- **In PowerShell, a backtick inside a double-quoted string is an escape.** A search
|
||||
needle containing `` `blockedExecutables` `` silently became something else, `.Replace`
|
||||
matched nothing, the file was unchanged — and the validator correctly passed. Print
|
||||
the mutated text before validating.
|
||||
- **`./build.ps1 check` with no switches** after every PR. ~~CI runs `-SkipIntegration`,~~ CI runs the same since 2026-09-06,
|
||||
so a green CI is evidence for the managed drain too (§S19(b) BUILT).
|
||||
- **A canary that does not compile is not a canary, and this repo's analyzers make that
|
||||
easy to hit.** Removing a call to prove a gate goes red can leave a constructor
|
||||
parameter unread — `CS9113` under `TreatWarningsAsErrors` — so the build fails, the
|
||||
test run prints "All tests passed" from the **previous binary**, and the canary looks
|
||||
like it worked. Measured this way on 2026-08-06 while proving the consent gate.
|
||||
Add `_ = param;` to keep it compiling, and read the build's exit code first.
|
||||
- **A document can go stale by NOT being touched.** This file's queue item 1 described
|
||||
work that had just landed, in a PR that changed 69 other files — the failure was the
|
||||
edit that was never made. `CHANGELOG.md` and §S24 are gated; this file is not, so it
|
||||
is the one that needs a deliberate pass at the end of every item.
|
||||
- **ONE GAME LAUNCH PER CAPTURE. A capture that ENDS kills the Overlay in that process 65 s
|
||||
later, permanently.** When the capture host exits nothing publishes `guardTicks` any more, the
|
||||
Overlay's watchdog hits `FL_GUARD_TICK_DEADLINE_MS` and calls `StopObserving` — which clears
|
||||
`g_observing` one-way and disables every hook for the life of the process. A second capture
|
||||
against the same running game returns `SupervisionLost` with zero records.
|
||||
|
||||
**This is designed behaviour, not a defect** (`19_SAFETY` §During a session), and it is
|
||||
recorded here because it changes how a measurement sweep has to be planned: §S31's off / ×2 /
|
||||
×4 comparison needs **three game launches**, not three captures in one. Measured 2026-08-20;
|
||||
the second capture of the session hit it within minutes of the first.
|
||||
|
||||
- **A LAUNCHER CAN UPDATE THE GAME BETWEEN THE CONSENT GRANT AND THE CAPTURE, and the refusal
|
||||
then says something false.** Alan Wake 2, 2026-08-20: consent granted at 09:12Z, the executable
|
||||
went from 62,026,752 to 62,304,768 bytes when the title was launched, and the capture refused
|
||||
with `ConsentMissing` — signal *"the per-game consent dialog has not been accepted"*, which the
|
||||
operator had done forty minutes earlier. `HookRequest.FromConsent` is right to null
|
||||
`consentedAt` and right to leave the stored record untouched; the *message* collapses three
|
||||
situations that need three different actions. `Program.WhyConsentMissingAsync` now prints
|
||||
which one it was. **Re-verify the fingerprint after launching a title, before blaming the
|
||||
gate.**
|
||||
|
||||
- **`D3D12CreateDevice(WARP)` can fail on a dev box while the real GPU's D3D12 works, and it takes
|
||||
two ctests down with it — `fl_d3d12_acquisition` and `fl_guard`'s D3D12 case.** The harness prints
|
||||
only `[FAIL] D3D12CreateDevice(WARP)`, which reads like a code regression.
|
||||
|
||||
**Measured on this machine 2026-08-06, and the second measurement contradicted the first
|
||||
write-up.** `EnumWarpAdapter` succeeds and returns *Microsoft Basic Render Driver*;
|
||||
`D3D12CreateDevice` on it returns **`DXGI_ERROR_DRIVER_INTERNAL_ERROR` (0x887A0020)** at **every**
|
||||
valid feature level (12_2 through 11_0; 10_1 and below return `E_INVALIDARG`, which is correct
|
||||
because D3D12 has an 11_0 floor). On the **same adapter object**, `D3D11CreateDevice` succeeds at
|
||||
FL 11_0, and `D3D12CreateDevice(nullptr, …)` on the RTX 5080 returns `S_OK`.
|
||||
|
||||
> **"A reboot clears it" was written here and is FALSE.** I asserted a remedy I had not tested.
|
||||
> The machine rebooted at 13:58 and the identical failure reproduced at 14:17, 19 minutes into the
|
||||
> new boot. `d3d10warp.dll`, `d3d12.dll` and `D3D12Core.dll` are all `10.0.29639.1000` and match the
|
||||
> OS — **Windows 11 Insider Preview build 26300/29639** — so nothing is mismatched or corrupt, and
|
||||
> the system log has no display errors since boot. It reads as an Insider-build regression in
|
||||
> WARP's **D3D12** path, and it is persistent.
|
||||
|
||||
> **AND IT STOPPED REPRODUCING, measured 2026-08-20 — which does not retire the trap, it dates
|
||||
> it.** `hook-harness --probe-d3d12` passes and `./build.ps1 check` is fully green here, 20/20
|
||||
> native tests. **No change in this repository caused that**: the machine moved from Insider
|
||||
> build **26300/29639** to **29648**, and `d3d10warp.dll` / `D3D12Core.dll` are both
|
||||
> `10.0.29648.1000`. So the fix is upstream and the window was 2026-08-06 → some point before
|
||||
> 2026-08-20.
|
||||
>
|
||||
> Both dates are recorded because the useful fact is not "it works now" — it is that **this
|
||||
> dependency broke and healed under the machine without anyone touching the code**, twice
|
||||
> giving a native suite a colour that said nothing about `main`. Do not delete this entry when
|
||||
> it is green; check which state your build is in.
|
||||
|
||||
**What that does and does not mean for the project.** CI (`windows-latest`, not an Insider build,
|
||||
no GPU) runs the same suite on WARP and passes, so `main` was never broken and no code change was
|
||||
indicated. What it does mean is that **the native suite has a hard dependency on WARP D3D12 that a
|
||||
dev box can lose on its own**, and that a red `fl_d3d12_acquisition` is not evidence about the
|
||||
code until the two adapters have been probed separately. That probe is ~40 lines of P/Invoke and
|
||||
settles it in one run; do that before reading the harness's output as a finding.
|
||||
- **A NATIVE test can go red because the RUNNER did not schedule two threads, and it looks
|
||||
like a code regression.** `ring_test.cpp`'s *"a tiny ring, so the writer laps the reader
|
||||
constantly"* ends with `CHECK(dropped > 0)` — an **anti-vacuity** assertion, not a property
|
||||
of the ring. Its own comment says why: *"with 8 slots the writer MUST have lapped us, so a
|
||||
run reporting no drops means the threads never actually overlapped and the case proved
|
||||
nothing."*
|
||||
|
||||
It fired on CI on 2026-08-28, on a pull request that **touched no native source and no
|
||||
test** — `ctest` reported `1 tests failed out of 23`, `build.ps1` threw `ctest failed (exit
|
||||
8)`, and the run before and the run after were both green. Eleven of the twelve CI runs
|
||||
around it passed, two of them on `main` within minutes.
|
||||
|
||||
**The tell is which assertion fired.** A ring defect fails `CHECK_FALSE(mixed)` or
|
||||
`CHECK_FALSE(poisonAccepted)` — the properties. A hosted runner that did not overlap the
|
||||
threads fails only the guard at the end. Read the assertion before reading the diff: this
|
||||
is the integration-budget trap (*"no budget may be sized on the harness's measured rate"*)
|
||||
one layer down, in the **native** suite, where §Traps did not have it.
|
||||
|
||||
Do **not** relax it to `>= 0`. The guard is what stops the case passing while proving
|
||||
nothing, and `ring_test.cpp`'s own header already records that two of its four properties
|
||||
have never been shown red.
|
||||
|
||||
> **Amended 2026-10-13 (beta.23 PR-1, #308): both guards now measure overlap.** The hammering case's own guard,
|
||||
> `accepted > kTotal / 2`, failed 5 of 40 runs and then 5 of 200 on the owner's hybrid i7-14700KF — `mixed` clean every
|
||||
> time — and once made a full local gate red. A share of the stream measured the scheduler: a reader on an efficiency
|
||||
> core keeps less than half, and one the OS does not run until the writer is done keeps one lap (accepted 1024). The
|
||||
> tiny ring's `dropped > 0` was weaker the other way: a reader made to wait for the writer to finish drops nearly
|
||||
> everything (1.6 million over eight attempts) and passed it. Both cases now start the writer only once the reader
|
||||
> is about to loop, count the drains that copied records while the writer was still writing, and repeat — every
|
||||
> attempt checked for its properties — until one attempt made 100 such drains, at most eight times; the tiny ring
|
||||
> also holds that attempt's own `dropped > 0`. A start barrier alone left 1 of 200 (one overlapping drain). Measured:
|
||||
> 1,000 runs, no failure, at most 3 attempts; with the waiting reader, both guards fail in every run.
|
||||
|
||||
- **A self-test's cases can all pass while testing nothing, and their NAMES will not tell
|
||||
you.** Found 2026-08-27 in a PowerShell gate's `-SelfTest`: removing the fail-closed guard
|
||||
from a hash comparison left **all ten cases green**. `[string]::Equals` already refuses
|
||||
empty-vs-present, so three cases named *"an empty hash fails closed"*, *"a null hash fails
|
||||
closed"* and *"an empty EXPECTATION fails closed too"* were testing `Equals`, not us.
|
||||
|
||||
**The case the guard actually carried was the one nobody wrote:** `Equals('','')` is
|
||||
**`true`**. That is the §S23-1 shape — two empty build ids compared equal and
|
||||
`ShmHandshakeValidator` reported `Ok` for every process on the machine — arriving in a
|
||||
different language.
|
||||
|
||||
*"A gate never observed failing is a comment"* applies to a gate's **own tests**. Plant the
|
||||
canary in the thing under test, not in the caller, and check that it fails on exactly one
|
||||
case: if it turns several red, the cases are coupled and none of them is pinning what its
|
||||
name claims.
|
||||
- **A failing `REQUIRE` used to END THE WHOLE BINARY, so one red test hid every test
|
||||
after it.** Fixed 2026-08-09, and recorded because the symptom was invisible: `ctest`
|
||||
reported *"1 test failed"* when the truth was *"and 2 never ran"*.
|
||||
|
||||
Catch2 compiled itself with `CATCH_CONFIG_DISABLE_EXCEPTIONS` — the top-level
|
||||
`src/native/CMakeLists.txt` strips `/EHsc` from `CMAKE_CXX_FLAGS` deliberately, and
|
||||
`tests/CMakeLists.txt` added it back **only to the test binaries**, never to the
|
||||
Catch2 library that decides the mode. Measured off the generated command line:
|
||||
`... -std:c++20 -MT -Zi` with no `/EH` flag at all. In that mode a failed `REQUIRE`
|
||||
calls `std::terminate`.
|
||||
|
||||
On this box, where WARP's D3D12 path is broken, that meant `fl_guard`'s D3D12 case
|
||||
killed the run and took the end-to-end injection cases with it — **including the
|
||||
honesty assertion §S29(a) names as the merge gate's coverage**, which passes fine
|
||||
when run on its own. `target_compile_options(Catch2 PRIVATE /EHsc)` recovered
|
||||
**70 test cases and 1051 assertions**. If you see a suspiciously small assertion
|
||||
count next to a failure, this is the shape to look for.
|
||||
- **No budget in the integration tests may be sized on the harness's measured rate.** Five were, and
|
||||
every one went red under load while nothing was wrong: the suite runs four test assemblies in
|
||||
parallel, each spawning a harness and injecting an Overlay that creates a WARP device, so the
|
||||
presenting thread is descheduled far longer than a rate-derived constant allows. Wait for the
|
||||
**state**, bounded by a wall clock generous enough to be about the state rather than about the
|
||||
machine.
|
||||
- **When one of those fails, capture the MESSAGE before changing anything.** #62 spent two rounds
|
||||
applying the remedy for a race to what turned out to be a loop bound and its assertion disagreeing
|
||||
by one — the loop exited at exactly 10 and the assertion demanded more than 10, so timing decided
|
||||
whether the off-by-one was visible. **A defect class is a hypothesis about the next failure, never
|
||||
a diagnosis of it.** One run with the message printed settles what four runs of pattern-matching
|
||||
cannot.
|
||||
- **A test that reads a writer state ONCE is racing `InitThread`.** `layoutVersion` is published at
|
||||
step 2 and `status` becomes `READY` at step 6, with a WARP device creation in between; `apiMask` is
|
||||
set later still, on the first present the hook sees. So `TryAttach` succeeding, `guardTicks`
|
||||
advancing, `status == INIT` and `apiMask == 0` are all legitimate simultaneous states. Poll for the
|
||||
state you mean, and keep the timeout failing — `INIT` past the budget is
|
||||
`WriterNeverInstalledHooks`, not slowness.
|
||||
- **Files written with LF fail `dotnet format --verify-no-changes`** even though the diff
|
||||
looks identical: `.editorconfig` mandates CRLF and `.gitattributes` normalises on
|
||||
checkout, so the working tree disagrees with both. Run `dotnet format` (no switch)
|
||||
before `check`, and normalise `.csproj`/`.ps1` by hand — the formatter does not touch
|
||||
those.
|
||||
- **GPG can stall.** `git commit` fails with `signing failed: Timeout`, and `git push`
|
||||
then reports success while pushing only the old HEAD. Never pass `--no-gpg-sign`; just
|
||||
retry the commit and read *its* exit code.
|
||||
- **The squash trap.** After a squash-merge the branch you were on is not an ancestor of
|
||||
`main`; a PR from it reports CONFLICTING and runs **no CI at all**. Read "no checks
|
||||
reported" as a symptom of that. Always `git fetch origin` then branch from
|
||||
`origin/main`; capture old base SHAs *before* merging a stacked pair.
|
||||
- **Do not pass `--delete-branch`**: `main` is checked out in the primary worktree,
|
||||
which blocks it. GitHub deletes the remote branch anyway.
|
||||
- **A control that compiles, binds and passes its view-model tests can still draw nothing.** WPF UI 4.3.0's
|
||||
`InfoBar` has no `ContentPresenter`, so every action button this repo placed as an InfoBar's child — the one
|
||||
dismissal of a safety notice — was silently dropped, and the owner met a red bar with no exit (2026-09-14).
|
||||
`SafetyNoticesTests` was green throughout: it asserted the model, and nothing instantiated the template.
|
||||
When a control's affordance matters, render it (`PagesLoadTests` has the STA harness) and walk the visual
|
||||
tree for the element — `16_WPFUI_SYNTAX` §Gotchas carries the fix and the test that retires it.
|
||||
- **A test that finds a file by pid finds the wrong one on a machine that has run the tests before.** The native
|
||||
log test looked up `overlay-<pid>-*.log` in the real `%LOCALAPPDATA%\FrameLedger\logs`, which keeps every run's
|
||||
log (2130 on the dev box by 2026-09-14). A reused pid read a stale log and failed on the STOP line; the re-run
|
||||
drew a new pid and passed, so it was called a flake four times while the failure output printed the September 6
|
||||
path. **Read the path in a failure before calling it a flake**, and select by creation time, not by name.
|
||||
|
||||
---
|
||||
|
||||
@@ -63,6 +63,47 @@ are kept because they record what each version changed and why (owner decision D
|
||||
>
|
||||
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
|
||||
|
||||
### What version 2.11 of the Privacy Policy changed (0.1.0-beta.23)
|
||||
|
||||
A game's page shows its artwork (beta.23 PR-3, owner decisions D60/D61; the wording approved with the plan). §1 adds the
|
||||
images a user chooses for a game, kept as a copy in the data folder's `covers` folder and deleted when the store's image
|
||||
is chosen again or the game is removed with its sessions. §4 adds the cover and banner images the Steam and GOG GALAXY apps
|
||||
keep on the disk for a library game, read to show them on its page and never copied or sent, and says that Steam's and
|
||||
GOG GALAXY's lists of installed games are now also read when a game's page opens, to find that artwork. §2 is unchanged:
|
||||
nothing is downloaded, and the software still looks nothing up on any store. 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
|
||||
|
||||
@@ -0,0 +1,525 @@
|
||||
# Open questions — closed H-series entries
|
||||
|
||||
*Moved verbatim from `docs/20_OPEN_QUESTIONS.md` on 2026-10-19 (beta.24, owner decision D66): the entries §S24 marks resolved (✅), with their reasoning, in their original order — never deleted. The table at the end of the H-series series there lists each one. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
### H5 ✅ · Proxy swapchains defeat the dummy-vtable assumption — **the DLSS / DLSS-G question closed 2026-09-06 (owner)**
|
||||
|
||||
> **CLOSED 2026-09-06, 12:17, on Cronos: The New Dawn demo with frame generation ON (`spike-notes` §9).**
|
||||
> The second Streamline 2.8.0 title, UE: `Native FPS: 86.8 -> Displayed FPS: 172.72 (x1.99 FG)`,
|
||||
> `unseen=0 over samples=10063`, `frame generation: DlssG — the NVIDIA driver agrees`, `upscaler: Dlss
|
||||
> (driver-reported)`, RT Yes. **So the pacer that bypasses the patched `Present` bodies is Dying Light:
|
||||
> The Beast's integration, not SDK 2.8.0's** — 2.8.0 on UE presents its generated frames through the body
|
||||
> the inline patches cover, exactly as 2.7.x and 2.10.x do. Every measured title now prints the rule-6 trio
|
||||
> or a counted `none`, on NVIDIA through one of three producers: the hooked bodies (Cyberpunk, Hell Is Us,
|
||||
> Expedition 33, Wukong, Rune Factory, Onimusha, Cronos), DXGI's own counter where the hook cannot count
|
||||
> (DL:TB), or a withheld `N/A` only when that counter was never read. Identity comes from the tags (DLSS-G)
|
||||
> and the hooks, and from the driver's per-process word where no hook can see it (the NGX-direct titles),
|
||||
> with the negative measured. **What stays unlocalised and is not needed for any number the report
|
||||
> prints:** which body DL:TB's pacer reaches. The owner closed the item on this reading; the sub-items
|
||||
> below are its history.
|
||||
|
||||
> ### CASE 3 HAS A CANDIDATE TITLE — Dying Light: The Beast, Streamline 2.8.0, DLSS Frame Generation ON, 2026-09-05
|
||||
>
|
||||
> **The numbers.** Five 58 s captures at DLSS with DLSS Frame Generation on (the owner's
|
||||
> setting, confirmed after the runs): `presents = tokens = batches` on every one —
|
||||
> 4706 / 4258 / 4560 / 4311 / 3441 — so the report printed `FPS: 80.41 / 72.73 / 77.69 /
|
||||
> 73.64 / 58.87` and **`frame generation: none`**, with `sl.dlss_g.dll` and `nvngx_dlssg.dll`
|
||||
> (310.6) in the census. The fifth ran on the #116 build, 2026-09-05 00:53. **Owner decision
|
||||
> the same night: a separate session and a separate PR own this; nothing below is started
|
||||
> until the discriminator has a reading.**
|
||||
> **The same title with FSR frame generation on** read presents 8255 against 4129 tokens
|
||||
> (×2, the loader row, §H11 R6). **Cyberpunk 2077 on Streamline 2.7.1 with the same DLSS-G
|
||||
> generation (310.8), same GPU,** read presents 13706 against 3439 tokens (×3.99) on 2026-09-03.
|
||||
>
|
||||
> **What that means, stated as the two readings the record cannot separate.** Either (a)
|
||||
> Streamline 2.8's DLSS-G presents its generated frames on a path the class-vtable hook on
|
||||
> `Present`/`Present1` does not see — case 3 of this entry, realised, with the application
|
||||
> frames still counted by `slGetNewFrameToken` and the generated ones simply absent — or (b)
|
||||
> the title was not generating in those runs despite the setting. **The discriminator is the
|
||||
> owner's counter reading**: an in-game or Steam frame counter near 2× our `FPS:` line is (a);
|
||||
> one near our line is (b). It is pre-committed here so the next run answers it rather than
|
||||
> being read into whichever reading is more comfortable.
|
||||
>
|
||||
> **Why this is a rule-6 exposure and not a curiosity.** `none` there is computed —
|
||||
> `presents == application frames` — and under reading (a) that equality holds *because*
|
||||
> the generated presents are missing, so the report states the absence of frame generation on
|
||||
> a title that is generating. The consumer cannot tell this from a real off. Until the
|
||||
> discriminator runs, a `none` on a Streamline 2.8 title with DLSS-G in the census is a
|
||||
> **count**, not a verdict, and `03_METRICS` §FG has no wording for that case yet. This is the
|
||||
> §H5 outcome the entry was written to fear, on a newer Streamline than the one that measured
|
||||
> it not happening; whether the fix is a wording, a census-version gate (the interposer's file
|
||||
> version is ours to read — it is a module in our process, not game memory), or a second
|
||||
> present sink is the owner's decision after the reading. **What is NOT in doubt:** the
|
||||
> Streamline tag row (`slSetTagForFrame`, #115) is unrelated — this is about presents.
|
||||
>
|
||||
> ### THE READING, 2026-09-05 — reading (a), and what landed on it
|
||||
>
|
||||
> The owner, verbatim: *"Trong game là DLSS X 4, steam đã hiện dlss, frame ghi nhận được
|
||||
> native/frame gốc chưa frame gen."* — the title is at DLSS ×4 (multi-frame generation), the Steam
|
||||
> overlay shows DLSS, and the frames this hook records are the native ones, before frame
|
||||
> generation. That is reading **(a)**: case 3 realised on Streamline 2.8.0. The numeric counter
|
||||
> value was not part of the reading and is the first thing the session below writes down.
|
||||
>
|
||||
> **The record already corroborated it, in a field nobody had read for this purpose.** The RT
|
||||
> census on the DLSS ×4 runs reads **97.1 % of all presents RT-active**; the same title with FSR
|
||||
> frame generation ×2 reads **54.6 %** — generated presents carry no ray-tracing work, so at ×2
|
||||
> half of them are RT-silent. A window in which every present carries RT work is a window that
|
||||
> holds no generated presents. Both readings of the count predicted that; only the owner's
|
||||
> reading says which.
|
||||
>
|
||||
> **What landed (PR-A1, C# only, nothing on the present path):**
|
||||
>
|
||||
> - The capture host takes an **out-of-process module snapshot** beside every guard scan —
|
||||
> `Process.Modules`, the loader's list through documented PSAPI, the same read the guard
|
||||
> already performs on every target — and the file's version resource on the path it names.
|
||||
> The report prints one `module:` line per census-named module (version, path). The census
|
||||
> cannot carry a version without a layout change; this can, at no cost in the hook.
|
||||
> - `MeasuredFacts` **withholds `none`** when `sl.dlss_g.dll` is in the census beside an
|
||||
> interposer whose file version is ≥ 2.8.0 or could not be read, and the report prints
|
||||
> `Presented FPS` with a qualifier: the number counts APPLICATION frames; whether frames were
|
||||
> generated, and the Displayed rate, are unknown. **The key is the Streamline plugin, not
|
||||
> `nvngx_dlssg.dll`:** every validated `none` on this machine — Cyberpunk off / ×3 / ×4 at 2.7.1
|
||||
> (census `0x5793D`), Expedition 33 and Lies of P with frame generation off — has the NGX
|
||||
> module loaded and the plugin bit CLEAR; every DL:TB run (`0x25F0F` / `0x25F4F`) has it SET.
|
||||
> The gate leaves each validated result byte-identical, and eight consumer cases pin that.
|
||||
> - **Cost, pre-committed:** DL:TB at DLSS with frame generation **off** also reads withheld if
|
||||
> the plugin is a startup-time load on this title. Leg 0 below measures which.
|
||||
>
|
||||
> **The session, pre-committed before it runs.** One owner session, one launch per leg, the
|
||||
> capture host as built plus **PresentMon 2.5.1 console, elevated, concurrently** (it is retired
|
||||
> as a shipped rung — §S31 row P2 — and is still the one instrument on this box that counts
|
||||
> presents from the kernel's side; on Cyberpunk it counted every generated present at the same
|
||||
> rate as this hook), plus the title's own FPS counter and the Steam overlay counter read by
|
||||
> eye mid-capture and written down **as numbers**. Read off our report: `FPS:` / `Presented FPS`,
|
||||
> `FG counts` (`presents=`, `tokens=`, `streams=`), the `module:` lines. Read off PresentMon:
|
||||
> rows over span, the number of distinct `SwapChainAddress` values, `PresentRuntime` and
|
||||
> `PresentMode`.
|
||||
>
|
||||
> | Leg | Title / setting | What it settles |
|
||||
> |---|---|---|
|
||||
> | 0 | DL:TB, DLSS, DLSS FG **off** | whether `sl.dlss_g.dll` is in the census with FG off (per-setting vs startup); ours ≈ PresentMon ≈ counter ≈ 1× |
|
||||
> | 1 | DL:TB, DLSS, DLSS FG **×4** | the discriminating leg |
|
||||
> | 2 | Cyberpunk 2077, DLSS, MFG ×4 (Streamline 2.7.1) | control on the same build: ours ≈ PresentMon ≈ 4× tokens, `x3.99 FG` printed, `module: sl.interposer.dll 2.7.1.0`, plugin bit clear |
|
||||
>
|
||||
> **Leg 1, the counter half, READ 2026-09-05** (owner's run on #118, `dyinglightbeast-141045`):
|
||||
> DLSS FG ×4, our line `Presented FPS: 76.7` with `none` withheld exactly as built, the title's own
|
||||
> counter **~300** — 3.9× ours. Reading (a) now has its number. The same day's `-105050` run read
|
||||
> 93.24 on the same shape. **Still owed from this table:** the PresentMon leg beside it (which
|
||||
> decides P1 against P3, i.e. whether the generated presents are kernel-visible at all), Leg 0
|
||||
> (whether `sl.dlss_g.dll` is a startup load), and Leg 2's control. Also the same day, Cyberpunk
|
||||
> at DLSS + RR + MFG ×3 read `62.86 → 187.49 (×2.98 FG)`, `frame generation: Active (technology not
|
||||
> identified)` — the count is right and the technology is unnamed, because `kFeatureDLSS_G` is
|
||||
> never evaluated through the export this build hooks; and the four UE titles at DLSS read
|
||||
> `upscaler: N/A` (Lies of P, Hell Is Us, Expedition 33, Wukong: NGX-direct super-resolution, the
|
||||
> Streamline interposer loaded and idle for it). **These three shapes — hidden presents on SL 2.8,
|
||||
> an unnamed DLSS-G, and an unnamed NGX-direct DLSS — are one question with one candidate answer
|
||||
> that is not a hook:** `NvAPI_NGX_GetNGXOverrideState` (NVAPI, MIT, vendored; R570+) takes a
|
||||
> PROCESS ID and returns the driver's own feedback bits per feature — SR / RR / FG each with
|
||||
> `DLL_LOADED`, `CREATED`, `EVALUATE`, `FG_MODE`, `FG_MULTI_FRAME` — plus `scalingRatio`,
|
||||
> `performanceMode` (the quality mode), `renderPreset`, `frameGenerationCount` and
|
||||
> `frameGenerationMode`. Out of process, from the driver's bookkeeping, whatever route the title
|
||||
> took to NGX. **Unmeasured, and measured before anything is built on it:** whether the bits are
|
||||
> populated for a process with no NVIDIA-app override configured (the API's name says "override"),
|
||||
> and whether `frameGenerationCount` is the title's multiplier or only an override target.
|
||||
> `fl-probe-nvapi --ngx-state <pid>` prints the raw words and every decoded bit; the owner runs it
|
||||
> against Lies of P (DLSS, no FG), Hell Is Us (DLSS + FG ×4), Dying Light: The Beast (DLSS FG ×4)
|
||||
> and Cyberpunk (MFG), each while the title runs — no capture, no injection, no consent needed.
|
||||
> **The decision it opens is the owner's:** a driver-reported fact is neither a hooked argument
|
||||
> (rule 4) nor a static hint (`05_DETECTION`); if the probe answers, `03_METRICS` needs a
|
||||
> *driver-reported* rung with its own wording ("reported by the NVIDIA driver, not counted"), and
|
||||
> the rule-6 pair on the hidden-presents shape could then read *application frames counted ×
|
||||
> multiplier reported* — labelled as such, never as a measured Displayed.
|
||||
>
|
||||
> **MEASURED 2026-09-06 morning, three titles, driver 616.64 (`spike-notes` §9): the bits ARE populated
|
||||
> without an override, for super resolution only.**
|
||||
>
|
||||
> | Title (override?) | SR feedback | RR feedback | FG feedback | ratio / mode / preset / fgCount |
|
||||
> |---|---|---|---|---|
|
||||
> | Hell Is Us (none), DLSS + **DLSS-G ×4 running** | `0x80605` INITIALIZED DLL_EXISTS **CREATED EVALUATE** ERR_NOT_FOUND | INITIALIZED DLL_EXISTS ERR_NOT_FOUND | `0x5` INITIALIZED DLL_EXISTS — **no CREATED / EVALUATE / FG_MODE** | 0 / 0 / 0 / 0 |
|
||||
> | Expedition 33 (NVIDIA-app override ON), FG off | `0x8067F` … ENABLED DLL_LOADED DLL_SELECTED PRESET PERF_MODE **CREATED EVALUATE** ERR_NOT_FOUND | INITIALIZED DLL_EXISTS ERR_NOT_FOUND | `0x1F` INITIALIZED ENABLED DLL_EXISTS DLL_LOADED DLL_SELECTED | 0 / **2** / **11** / 0 |
|
||||
> | Lies of P (none), DLSS, no FG | `0x605` INITIALIZED DLL_EXISTS **CREATED EVALUATE** | INITIALIZED ERR_FAILED ERR_NOT_FOUND | INITIALIZED ERR_FAILED ERR_NOT_FOUND | 0 / 0 / 0 / 0 |
|
||||
>
|
||||
> Four readings. **(1) `CREATED | EVALUATE` on the SR word is set on both no-override titles** — the
|
||||
> driver keeps per-process bookkeeping of the NGX super-resolution feature whatever route the title took,
|
||||
> which is exactly the identity `upscaler: N/A` lacks on the NGX-direct titles (all three print it). **(2)
|
||||
> The FG word does NOT reflect DLSS-G activity:** Hell Is Us was generating at ×4 through Streamline
|
||||
> (`83.21 → 332.82 (×4 FG)`, `DlssG`, the same session) and its FG word says INITIALIZED | DLL_EXISTS and
|
||||
> nothing more — the word tracks the override machinery's DLL, not the plugin's evaluations. Frame
|
||||
> generation stays with the tags and the count. **(3) `frameGenerationCount` is 0 on every title,
|
||||
> including the one at ×4 — it is the override target the header names, never the title's multiplier**,
|
||||
> so the "application frames counted × multiplier reported" pair above has no producer and is dropped.
|
||||
> **(4) `scalingRatio` is 0 everywhere, override included; `performanceMode` / `renderPreset` are
|
||||
> populated only under the override (E33: 2 / 11) and are then the OVERRIDE's values, not the title's** —
|
||||
> so this route gives an identity and nothing about the render size or quality. `ERR_NOT_FOUND` sits
|
||||
> beside CREATED | EVALUATE on two titles and is absent on the third; the header does not say what it
|
||||
> refers to (a DRS profile, most likely), and it is not read as anything.
|
||||
>
|
||||
> **What a driver-reported rung may therefore claim — the owner's decision, not yet built:** on a
|
||||
> session where every hook says `upscaler: N/A`, `Dlss (driver-reported: the NVIDIA driver reports an
|
||||
> NGX super-resolution feature created and evaluated in this process — not counted by this hook)`. It
|
||||
> may name the vendor and the feature; it may not state a quality, a ratio, a render size, a frame
|
||||
> generation mode or a multiplier. On a hooked-identity session (Cyberpunk, DL:TB, Onimusha) the word
|
||||
> is a consistency check the report prints beside the hooked name. **Owed before it is built — the
|
||||
> negative:** the probe on Lies of P or Hell Is Us with DLSS switched OFF in the menu, expected
|
||||
> `CREATED` clear; a rung that has only ever seen the positive would be the census's mistake again.
|
||||
> Plumbing when decided: the probe already builds against `fl_nvapi`; the capture host would call it
|
||||
> beside each module snapshot (out of process, no consent needed) or, if it goes in-process, through
|
||||
> `Infrastructure` only (CLAUDE.md: no P/Invoke elsewhere).
|
||||
>
|
||||
> **In-process since 2026-09-10 (P2 PR-E2):** the same words through `FrameLedger.NvapiBridge.dll`
|
||||
> (`Infrastructure.Telemetry.NvapiNgxStateProbe`, the `INgxDriverProbe` the Agent will take from DI);
|
||||
> the spawn below is retired and `fl-probe-nvapi.exe` is no longer staged beside the host. The readings,
|
||||
> the merge and the printed block are unchanged, and `NvapiNgxStateProbeTests` maps the bridge's three
|
||||
> answers to the three outcomes the machine line used to carry.
|
||||
>
|
||||
> **BUILT 2026-09-06, on the owner's decision ("nối probe để bắt đầu").** The capture host spawns
|
||||
> `fl-probe-nvapi --ngx-state <pid>` beside every module snapshot (the probe prints one machine line,
|
||||
> `NGXSTATE status=… sr=0x… …`, and is staged beside the host by the project file), merges the readings
|
||||
> (the last answered word is the state; a change between readings is printed, never averaged) and
|
||||
> prints `NVIDIA driver NGX state:` in the runtime block. `03_METRICS` §Upscaling carries the rung and
|
||||
> its limits. **Pre-committed, read off the next run:**
|
||||
>
|
||||
> | Row | Title / setting | Expected | Else |
|
||||
> |---|---|---|---|
|
||||
> | **N1** | Lies of P, Hell Is Us, Expedition 33 at DLSS | `upscaler: Dlss (driver-reported: …)` | a `CREATED \| EVALUATE` word beside `N/A` is a parser or plumbing defect — localise |
|
||||
> | **N2** | Cyberpunk, DL:TB, Onimusha (hooked `Dlss`) | `upscaler: Dlss — the NVIDIA driver agrees …` | a disagreement WARNING is printed as such; it is not resolved by preferring either |
|
||||
> | **N3** | **the negative, still owed:** Lies of P with DLSS switched OFF in the menu | `CREATED` clear → `upscaler: N/A (…) — the NVIDIA driver reports no NGX super-resolution feature created …` | `CREATED \| EVALUATE` still set with DLSS off → **the rung is withdrawn** (the bit is a session-lifetime latch, not a state) and the line goes back to N/A |
|
||||
> | **N4** | a title at FSR / XeSS with no NGX feature | `Fsr3` / `N/A` with the driver's negative beside it | `CREATED` set on a title with no DLSS in its menu → withdraw |
|
||||
>
|
||||
> Lies of P has no DLSS Frame Generation (owner, 2026-09-06), which is why its FG word reads
|
||||
> `ERR_FAILED ERR_NOT_FOUND`: nothing to load.
|
||||
>
|
||||
> **LANDED 2026-09-06, 10:39–11:36 (`spike-notes` §9): N1, N2 and N3 as pre-committed, N4 in a shape the
|
||||
> row did not foresee, and one correction.** N3 first, because it decides: the standalone probe on Lies of
|
||||
> P with upscaling OFF read `SR 0x5` — `CREATED` clear — and with DLSS on `0x605`; **the rung stands.** N1:
|
||||
> Lies of P, Expedition 33, Hell Is Us and the new Cronos: The New Dawn demo all print
|
||||
> `upscaler: Dlss (driver-reported: …)` where they printed `N/A`. N2: Onimusha and DL:TB print
|
||||
> `upscaler: Dlss — the NVIDIA driver agrees`. N4 arrived as DL:TB at **FSR upscaling + DLSS Frame
|
||||
> Generation**: `upscaler: FSR (3.1 or 4 …)`, `2560x1440 -> 2560x1440`, `SR 0x205` — CREATED without
|
||||
> EVALUATE, so the driver's word correctly does NOT claim DLSS beside FSR (the rung needs both bits).
|
||||
> **The correction:** the FG word is NOT blind to DLSS-G. It read `CREATED | EVALUATE` on Hell Is Us,
|
||||
> Onimusha and DL:TB at ×4, and *"the words CHANGED between readings"* on all three — the morning's
|
||||
> `INITIALIZED | DLL_EXISTS` on Hell Is Us was a first reading taken before the feature came up.
|
||||
> `FG_MODE` / `FG_MULTI_FRAME` stay clear and `fgCount` is 0 at ×4, so it names the feature and never the
|
||||
> multiplier: printed beside `frame generation:` as agreement, promoted to `DlssG (driver-reported)` only
|
||||
> where the count is active and no tag named the technology. Also on this run: Cronos is a **second
|
||||
> Streamline 2.8.0 title** (UE, FG off, `sl.dlss_g.dll` absent from its census — per-setting there — `FPS
|
||||
> 105.01`, `none` with DXGI agreeing); its FG-on capture would say whether the 2.8.0 pacer bypass is the
|
||||
> SDK's or Techland's. And the FSR + DLSS-G session's factor was refused (bucket 8 of 8 at 1.96 against
|
||||
> 2.85 — the guard working) while the qualifier said *"no evaluation was observed"* beside 4,415 tokens; the
|
||||
> qualifier now says the factor was counted and refused, and that DXGI counted 8,174 presents this hook
|
||||
> never saw so the Displayed rate is above the printed one.
|
||||
>
|
||||
> **The last row, 12:17 — Cronos with frame generation ON: `86.8 → 172.72 (×1.99 FG)`, `unseen=0`, `DlssG`
|
||||
> with the driver agreeing.** The 2.8.0 pacer bypass is Techland's, not the SDK's. Closed above.
|
||||
>
|
||||
> ### THE STREAMLINE DOCS, READ 2026-09-05 (v2.8.0 and main), AND WHAT THEY CHANGED
|
||||
>
|
||||
> The owner asked for the vendor's own guides before any rewrite. Three things in them decide this item.
|
||||
>
|
||||
> 1. **DLSS-G presents through the "SL pacer"** (DLSS-G guide §14.1): an asynchronous presentation
|
||||
> mechanism, with *"specialized hardware to delay the image after Present() has been called"* and a
|
||||
> note that `MsBetweenPresents` in third-party tools *"indicates when the internal Present() call has
|
||||
> happened"*. So the generated frames ARE presented by internal `Present()` calls on 2.7.1 — which is
|
||||
> what this hook counts on Cyberpunk — and whether 2.8's pacer on Blackwell still reaches the body we
|
||||
> patch is exactly what Leg 1's PresentMon half measures. The docs do not say; they say FrameView 16.1
|
||||
> is the recommended tool because it reads `MsBetweenDisplayChange`, i.e. the display side.
|
||||
> 2. **`slDLSSGGetState` is the documented way to get the presented count** (§14.0: `actualFPS = myFPS *
|
||||
> state.numFramesActuallyPresented`) — and it is **refused here**, with the reason in `03_METRICS` §FG:
|
||||
> the header defines the field as *"number of frames presented since the last `slDLSSGGetState` call"*,
|
||||
> so every call RESETS the plugin's counter, and a title that reads it for its own FPS display would
|
||||
> read our calls' remainder. It is also marked *"NOT thread safe"*. A measurement that alters the
|
||||
> host's measurement is not observing.
|
||||
> 3. **§5.0 "Tag all required resources": DLSS-G requires the HUD-less and UI buffers to be tagged every
|
||||
> frame** through `slSetTag` / `slSetTagForFrame` / `slEvaluateFeature`'s inputs — the three routes this
|
||||
> build already hooks and read ONE tag type from. **Built the same day:** every tag's type is recorded
|
||||
> (`FlWriterState.slTagCensus`, per route), a HUD-less or UI tag drained by a present marks it
|
||||
> `FL_FG_DLSS_G`, and the consumer names `DlssG` beside an active count. Identity, not a count: the
|
||||
> count still decides `none`, so a title tagging the inputs with the feature off prints `none` with the
|
||||
> inputs noted, and the withheld shape keeps its N/A.
|
||||
>
|
||||
> **Pre-committed for the next run, per title:** Cyberpunk at DLSS + MFG → `frame generation: DlssG`,
|
||||
> tag census `global=[depth, mvec, hudless, ui-color-alpha, …]` (2.7.1 tags globally; the scaling input
|
||||
> arrives locally). Hell Is Us / Expedition 33 / Wukong at DLSS + FG ×4 → `DlssG` **if** the UE Streamline
|
||||
> plugin tags through the exports (their `UpscalerParams = 0` says no scaling-input tag arrived, which is
|
||||
> consistent with NGX-direct super-resolution and says nothing about the DLSS-G inputs); if the census
|
||||
> reads `global=[-] frame=[-] local=[-]` on those titles, they tag through neither export and the identity
|
||||
> stays `Active (technology not identified)` honestly. DL:TB at DLSS FG ×4 → the census line says whether
|
||||
> the title feeds DLSS-G through a route this build sees; the qualifier then says *"FEEDING frame
|
||||
> generation"* beside the withheld count. Lies of P at DLSS (no Streamline tokens at all) → unchanged:
|
||||
> the super-resolution identity on NGX-direct titles is what the NVAPI probe above is for.
|
||||
>
|
||||
> **LANDED 2026-09-05 evening, on the owner's run on #121 (`spike-notes` §9):** `frame generation: DlssG` on
|
||||
> Hell Is Us (×4, twice), Expedition 33 (×1.97), Wukong (×4), Rune Factory (×3.98) and Cyberpunk — every
|
||||
> Streamline title tags the DLSS-G inputs through a route this build hooks (the UE plugin and Cyberpunk 2.7.1
|
||||
> globally, DL:TB 2.8 through `slSetTagForFrame`), so the identity is measured six of six and *"technology
|
||||
> not identified"* is gone from all of them. DL:TB's withheld line now says *"FEEDING frame generation"*
|
||||
> beside the count it cannot make; its census also shows a `scaling-in` tag on the frame route with
|
||||
> `UpscalerParams` still 0 — the tag carries no size on this title, which closes 7a's last question without
|
||||
> the layout bump it was thought to need. Cyberpunk's factor was refused on that run (bucket 1 at 3.0 against
|
||||
> 1.67 overall, `tokens/batch 2.97`): a mixed session, refused as designed rather than averaged. **What is
|
||||
> left on NVIDIA is one thing: `upscaler: N/A` on the NGX-direct titles** — the probe above.
|
||||
>
|
||||
> **BUILT 2026-09-05, late — A1.7 promoted from "not in A1" to the in-process half of Leg 1.** The owner
|
||||
> read that Streamline ≥ 2.8 "needs `sl.interposer.dll` and `sl.common.dll` loaded before an injection
|
||||
> succeeds". Checked against the source, not the claim: the interposer's DXGI proxy
|
||||
> (`source/core/sl.interposer/d3d12/dxgiSwapchain.cpp`) is **byte-for-byte the same file at v2.7.32 and
|
||||
> v2.8.0** — plugins' before-hooks receive `m_base` and may `skip` the base call, exactly as before — and
|
||||
> 2.8's `sl.common` gains `resourceTaggingForFrame.cpp` (the `slSetTagForFrame` route #121 already hooks).
|
||||
> Injection into DL:TB already succeeds (every capture there has `streams=1`, a full `runtime census`, a
|
||||
> tag census), so "loaded before injection" is a launcher's problem, not this hook's. What 2.8 does NOT
|
||||
> show is where its closed `sl.dlss_g` pacer presents. So the Overlay now asks DXGI itself: on every hooked
|
||||
> present it reads `IDXGISwapChain::GetLastPresentCount` on the chain it just saw (rule 4: the same object
|
||||
> `FindOrAdd` already calls `GetDesc` on) and publishes two words on the 1 Hz watchdog —
|
||||
> `dxgiPresentSamples` (hooked presents that read it) and `dxgiPresentsUnseen` (presents DXGI counted
|
||||
> between two hooked ones, beyond the one seen). The report prints
|
||||
> `DXGI present counter: unseen=M over samples=N (r unseen per hooked present)` and the withheld qualifier
|
||||
> carries the reading. The harness's own presents are the negative control (`fl_guard` `[fg]`:
|
||||
> `unseen == 0`, `samples >= drained`); the positive cannot be fixtured — nothing in this repo presents
|
||||
> through a body the inline patches miss — which is why the rows below are written before the run.
|
||||
> Cost: one virtual call per hooked present, measured by `hook-harness --probe-frames` (number in the PR
|
||||
> body); `--probe-cost` is the empty-detour floor and does not include it.
|
||||
>
|
||||
> Leg 1's in-process rows, read off the new line on a DL:TB DLSS FG ×4 capture (r = unseen / samples):
|
||||
>
|
||||
> | Row | Reading | Meaning | Action |
|
||||
> |---|---|---|---|
|
||||
> | **P1-DXGI** | r ≈ 3 (×4) — `unseen ≈ 3 × samples` | the pacer presents on the SAME chain through a body the inline patches do not cover; the generated presents ARE DXGI presents | the next PR promotes `Displayed = hooked + unseen`, labelled **DXGI-counted** (a count DXGI made, not this hook), `presents/batch` from it, and `none` withdraws by count; the pacer's entry is then localised (a second `CDXGISwapChain` class, or a path that bypasses `Present`'s body) at leisure |
|
||||
> | **P3-DXGI** | r ≈ 0 | DXGI counted nothing this hook did not: the generated frames are displayed below DXGI (driver pacing / flip metering) or on an object this hook never saw | the withheld wording stays; no in-process sink exists; only PresentMon (kernel) and the NVAPI corroboration remain, and if PresentMon also reads 1× the frames never were kernel presents |
|
||||
> | **P5-DXGI** | 0 < r < 2.5, or r ≠ 0 with `streams > 1` | a mixed path or a second chain | stop and localise; the number is printed, never averaged into a factor |
|
||||
> | **P2/P4** | r ≈ 0 with ours ≈ 4× tokens, or the count itself moved | as the kernel rows say: not generating, or the title changed | the kernel rows above decide |
|
||||
>
|
||||
> **LANDED 2026-09-05 night, on the owner's run on #124 (`spike-notes` §9): row P1-DXGI, twice.** DL:TB at
|
||||
> DLSS FG ×4 read `unseen=12204 over samples=4136 (2.95)` at 21:56 and `unseen=12741 over samples=4392
|
||||
> (2.90)` at 22:06 — DXGI counted 3.9× the presents this hook did, on the SAME chain, which is the owner's
|
||||
> ~300 against ours ~75 from the afternoon, now measured in-process. The two controls read 0.00: Hell Is Us
|
||||
> (Streamline **2.7.3**, `79.89 → 308.14 (×3.86)` through the patched bodies, 18,207 samples) and the
|
||||
> owner's new title, the **Onimusha: Way of the Sword demo on Streamline 2.10.3** (`60.04 → 220.33
|
||||
> (×3.67)`, `DlssG`, `upscaler: Dlss`, 12,914 samples, 0 unseen). So **2.8.0's pacer is the odd one** —
|
||||
> 2.7.x before it and 2.10.x after it present the generated frames through `Present`'s body — and the
|
||||
> "`sl.interposer.dll` + `sl.common.dll` must be loaded on ≥ 2.8" lead is closed by 2.10.3, which injects,
|
||||
> tags on the frame route and counts exactly like 2.7. **The pre-committed action is built:** the record
|
||||
> carries `dxgiUnseen` (@52, `FL_MEASURED_DXGI_PRESENTS`), the window counts `Displayed = hooked +
|
||||
> unseen` and prints *"Displayed is DXGI-COUNTED"* on its own line, `presents/batch` takes the same
|
||||
> numerator, and `none` withdraws on DL:TB by count (`03_METRICS` §Displayed may be DXGI-COUNTED). Expected
|
||||
> on DL:TB's next capture: the trio at ≈ ×3.9 with the label, no withheld line, `frame generation: DlssG`.
|
||||
> Which body the 2.8.0 pacer reaches stays unlocalised, as the row said.
|
||||
>
|
||||
> **LANDED 2026-09-06 morning, on the owner's run on #125 (`spike-notes` §9): the promotion, and Leg 0.**
|
||||
> DL:TB at DLSS FG ×4 (07:31): `Native FPS: 70.52 -> Displayed FPS: 282.08 (x4 FG) over 16516 present(s)`,
|
||||
> *"Displayed is DXGI-COUNTED: 12387 of those present(s)"*, `unseen=12483 over samples=4202 (2.97)`,
|
||||
> `frame generation: DlssG`, uniform across every bucket, no withheld line — the trio rule 6 asks for, on
|
||||
> the title that could not print it. **Leg 0, twice (07:45, 07:55): frame generation OFF**, census still
|
||||
> `0x25F0F` — `sl.dlss_g.dll` is a **startup-time load**, the cost paragraph's fear measured true —
|
||||
> presents = tokens, `unseen=0 over samples=3659` and `4519`, tag census `0x23600` (depth, mvec,
|
||||
> scaling-in, scaling-out, other: **no hudless / UI tag with FG off**, so the DLSS-G identity is
|
||||
> per-setting on this title too), and the report withheld `none` exactly as pre-committed. **The gate is
|
||||
> narrowed rather than withdrawn:** DXGI's counter is the discriminator it lacked — the 2.8.0 pacer's
|
||||
> presents are DXGI presents on this chain (P1-DXGI), so a counted 1.0 beside a READ counter with zero
|
||||
> unseen is `none`, printed with DXGI's agreement; withheld only when the counter was not read. Control:
|
||||
> Expedition 33 FG off (Streamline 2.7.30) reads `FPS: 85.86`, `none` by count, tag census `0x0` — the UE
|
||||
> plugin sends no tags at all with FG off.
|
||||
>
|
||||
> Leg 1's rows (ours = `presents / span`; PM = PresentMon rows / span; C = the counter; ≈ = within 5 %):
|
||||
>
|
||||
> | Row | Reading | Meaning | Action |
|
||||
> |---|---|---|---|
|
||||
> | **P1** | PM ≈ 4× ours, C ≈ PM | generated presents reach the kernel on a path **outside** the `CDXGISwapChain::Present/Present1` bodies the Overlay inline-patches — case 3 realised | gate stays; a second present sink is costed (candidates below) and the route is the owner's; PresentMon's `SwapChainAddress` count says whether it is a second chain (2 addresses against our `streams=1`) or the same chain by another entry (1) |
|
||||
> | **P2** | PM ≈ ours ≈ C ≈ 1× | the title was not generating despite the setting | **withdraw the gate** (keep the `module:` lines); `none` was right; case 3 stays unrealised; the owner checks the setting |
|
||||
> | **P3** | PM ≈ ours ≈ 1×, C ≈ 4× | frames displayed without a kernel-visible present per frame (driver pacing / flip metering), or the counter reports a target rather than a measurement | keep the wording ("Displayed unknown"); no in-process or kernel sink would help; only a vendor read could corroborate |
|
||||
> | **P4** | ours ≈ 4× tokens on the rerun | the five earlier runs were not generating, or the title changed — compare the `module:` versions and the exe fingerprint against the 00:53 run | withdraw the gate; localise what changed |
|
||||
> | **P5** | PM ≈ 2×, or two `SwapChainAddress` values with ours `streams=1` | a second chain or a mixed path | stop and localise before deciding |
|
||||
> | **P6** | elevation refused / a leg unrun | nothing measured | not a result — P2 is not inferred from silence |
|
||||
>
|
||||
> Leg 0's own row: if `sl.dlss_g.dll` is **absent** with FG off, the census bit is per-setting on
|
||||
> this title and the gate is sharper than its cost paragraph feared (consider dropping the version
|
||||
> conjunct); if present, the interim cost stands as written. **Landed 2026-09-06: PRESENT, twice** —
|
||||
> and the cost stood for one morning, because the DXGI counter (above) narrowed the gate the same day.
|
||||
>
|
||||
> **Second-present-sink candidates for P1 / P5, one line each, none chosen:** MinHook inline
|
||||
> patches on the `gdi32.dll` D3DKMT thunks (`D3DKMTPresent`, `D3DKMTPresentMultiPlaneOverlay3`,
|
||||
> `D3DKMTSubmitPresentToHwQueue`) — in-process, no elevation, argument reads only, but
|
||||
> semi-documented structs that move between Windows builds and more patched bytes on the most
|
||||
> anti-cheat-sensitive path; an ETW `Microsoft-Windows-DxgKrnl` consumer in the capture host
|
||||
> (what PresentMon reads) — exact per-pid kernel count, costs **elevation**, which is §G's Tier-2
|
||||
> question re-entering; an `IDXGIFactory2::CreateSwapChain*` hook (`17_HOOK_ENGINE` ⏳) — sees a
|
||||
> second chain at creation only, i.e. launch mode (§S1); in-hook `IDXGISwapChain::GetLastPresentCount`
|
||||
> sampling — a same-chain localiser only, and a hot-path virtual call with two reserved words
|
||||
> behind it. NVAPI has no present count outside present barrier; `NvAPI_NGX_GetNGXOverrideState`
|
||||
> (R570, by PID) reports the driver's DLSS override state and multi-frame target, which is
|
||||
> corroboration rather than a count — an optional `fl-probe-nvapi --ngx-state <pid>` reading on
|
||||
> Legs 2 then 1, never a gate input.
|
||||
|
||||
> ### NARROWED, NOT CLOSED — five real-title captures, 2026-08-15
|
||||
>
|
||||
> **What is now measured.** Cyberpunk 2077, SL 2.7.1, RTX 5080, D3D12, 2560×1440, DLSS
|
||||
> Balanced, Ray Reconstruction on. Five 40 s captures at four frame-generation settings,
|
||||
> Overlay payload hash-verified against the just-built DLL before each run:
|
||||
> **off → `presents/batch` 1.000 · ×2 → 2.000 · ×4 → 4.000** (×4 three times independently).
|
||||
> Every run: one identified swapchain, one segment, 0 gaps, 0 dropped.
|
||||
>
|
||||
> **What that settles.** The presents a multi-frame-generation configuration adds are
|
||||
> **visible to a hook on `dxgi.dll`'s shared class vtable**. The ratio tracks the configured
|
||||
> MULTIPLIER, not merely the on/off state — which a two-point sweep could not have shown,
|
||||
> and which is why §S30's oracle paragraph pre-committed three points. `fg_factor`
|
||||
> structurally 1.0 on every Streamline title, the outcome this entry exists to fear, does
|
||||
> **not** occur here.
|
||||
>
|
||||
> **What it does NOT settle, and the distinctions are load-bearing:**
|
||||
>
|
||||
> - **Case 3 is narrowed, not answered.** Nothing went missing *in aggregate*, but these
|
||||
> runs cannot separate "the interposer forwards through the chain we already see" from
|
||||
> "the interposer presents on its own chain that our shared-vtable patch also catches".
|
||||
> One identified stream in every run is what makes the second reading unlikely rather than
|
||||
> excluded.
|
||||
> - **Case 2 is made WORSE by this result, not resolved by it.** If three of every four
|
||||
> presents at ×4 originate in the vendor's swapchain, then ~75% of records carry
|
||||
> `syncInterval` / `presentFlags` that **no application call produced** — and `dllmain.cpp`
|
||||
> sets `FL_MEASURED_PRESENT_ARGS` on every one of them unconditionally, as "the one thing a
|
||||
> DXGI present hook always has". Nothing has compared observed present args against what
|
||||
> the title passed. Any consumer of those two fields inherits this.
|
||||
> - **`presents/batch` is a PROXY and its denominator is unverified.** A batch is "a present
|
||||
> that drained a Streamline evaluation". It equals an application frame here only because
|
||||
> Ray Reconstruction is evaluated once per application frame on this title, which no
|
||||
> independent oracle has confirmed — `fl-baseline-probe` at the three settings and the
|
||||
> game's own frame counter are both pre-committed in §S30 and both **unrun**.
|
||||
> - **Scope.** One title, one SL build, one GPU, D3D12, RR **on**, MFG only. Says nothing
|
||||
> about RR-off, about other SL 2.x builds, about SL 1.x titles (refused before any hook is
|
||||
> installed), or about XeFG and FSR3-FG.
|
||||
>
|
||||
> **A separate finding from the same runs, which belongs to HANDOFF item 3 rather than
|
||||
> here:** `slEvaluateFeature(kFeatureDLSS_G)` is **never called** — 0 across ~14,000 batches.
|
||||
> `UNDECODED` is also 0, and that zero is now meaningful rather than merely observed: the
|
||||
> injected `--hold-presenting-upscaled-unknown` case asserts the bucket reads non-zero for an
|
||||
> id outside the decoded set, proven red. So a vendored `kFeatureDLSS_G` constant not matching
|
||||
> the runtime id is excluded, and the honest statement is that the id does not reach the
|
||||
> hooked export. **Where frame generation IS driven from was not measured** — an absence at
|
||||
> one export of one module does not locate a mechanism, and the NGX tier
|
||||
> (`NVSDK_NGX_D3D12_EvaluateFeature`, seven exporting modules) is hooked nowhere.
|
||||
|
||||
**Partly answered, and the news is better than expected.** `hook-harness
|
||||
--probe-proxy` builds a real forwarding `IDXGISwapChain` wrapper — what
|
||||
`sl.interposer` and ReShade hand the application — and presents through it with
|
||||
our hook on the **real** vtable. The hook still fires: the proxy forwards via
|
||||
`real_->Present(...)`, an ordinary virtual dispatch, so patching the real vtable
|
||||
catches it one layer down. A proxy having its own vtable does *not* by itself
|
||||
make us miss the present.
|
||||
|
||||
> **Case 3 is now probed, bounded, and blocked on a LICENCE rather than on
|
||||
> hardware** (2026-08-05, `fl-probe-interposer`, `spike-notes.md` §5). Loading a
|
||||
> real `sl.interposer.dll` — Cyberpunk 2077 and Black Myth: Wukong — into our own
|
||||
> process shows it forwards to `dxgi.dll` and leaves both the factory and the
|
||||
> swapchain vtable untouched **until `slInit()` runs**, which the probe proves by
|
||||
> enumerating its own modules and finding no `sl.*` plugin mapped. So the
|
||||
> comparison is currently measuring passthrough, and the probe reports
|
||||
> **inconclusive** rather than a verdict.
|
||||
>
|
||||
> Recorded because the first version of that probe did **not**: it printed "the
|
||||
> vtable is THE SAME — a hook DOES catch Streamline presents" for both titles,
|
||||
> which would have closed §H5 case 3 on a measurement of nothing. The tell was in
|
||||
> its own output — an interposing Streamline cannot leave the *factory* vtable
|
||||
> unwrapped, since wrapping the factory is how it reaches the swapchain.
|
||||
>
|
||||
> ~~Reaching the wrapped path needs `slInit`'s `sl::Preferences`, i.e. vendor ABI,
|
||||
> i.e. the question `legal/THIRD_PARTY_NOTICES.md` answers for Intel IGCL and
|
||||
> nobody has asked for NVIDIA.~~ **Unblocked by #64 and MEASURED 2026-08-14.**
|
||||
> Streamline is MIT and `sl::Preferences` is vendored, so `fl-probe-interposer` now
|
||||
> calls `slInit` → `D3D12CreateDevice` *through the interposer* → `slSetD3DDevice`,
|
||||
> every entry point resolved with `GetProcAddress`. **The premise holds:** with
|
||||
> `slInit` returning `eOk`, the interposer hands back a swapchain whose vtable is
|
||||
> inside `sl.interposer.dll` while `dxgi.dll`'s own route yields `dxgi.dll`'s.
|
||||
> Reproduced on Alan Wake 2 (SL 2.7.0) and Cyberpunk 2077 (SL 2.7.1), RTX 5080.
|
||||
> **The risk is also narrower than the entry
|
||||
> implies:** NGX-direct titles never wrap the swapchain, so the vtable premise is
|
||||
> only in question for Streamline-shimmed ones.
|
||||
>
|
||||
> > **What that does and does not settle, because the difference is the whole
|
||||
> > metric.** It settles that the game's swapchain is **not** an instance of the
|
||||
> > class whose shared vtable we patch. It does **not** settle whether we miss the
|
||||
> > present: §H5's own `--probe-proxy` result stands — a *forwarding* proxy calls
|
||||
> > `real_->Present(...)`, an ordinary virtual dispatch, caught one layer down.
|
||||
> > **Different class ≠ missed present.** Deciding which needs presents driven
|
||||
> > through this proxy with our hook installed. No feature plugin reported loaded in
|
||||
> > these runs, so the DLSS-G question — whether GENERATED presents reach the same
|
||||
> > vtable — is untouched.
|
||||
> >
|
||||
> > **A second finding, which cost a crash to get.** The Witcher 3 ships
|
||||
> > `sl.interposer.dll` **1.5.6**, a different API generation: it exports
|
||||
> > `slGetHooks`, `slIsFeatureEnabled` and `slSetFeatureConstants`, and exports
|
||||
> > **neither** `slSetD3DDevice` nor `slIsFeatureLoaded`. `slInit` exists in both
|
||||
> > with a **different `sl::Preferences` layout**, so calling it with the vendored
|
||||
> > 2.x struct access-violates (`0xC0000005`). The probe now version-guards on the
|
||||
> > SL2-only exports and skips with a reason.
|
||||
> >
|
||||
> > **That generalises past the probe and touches the hook inventory.**
|
||||
> > `docs/vendor-exports.json` records **one copy per module name**, so its
|
||||
> > `sl.interposer.dll` is one machine's 2.7.4 and says nothing about a 1.5.6 a title
|
||||
> > may ship. `hookinventory-check` Pass A would pass `slEvaluateFeature` against
|
||||
> > such a title — the **name** exists in both generations — while the **signature**
|
||||
> > differs, so a detour typed with the 2.x `PFun_slEvaluateFeature` would read 1.x
|
||||
> > arguments. Today's hook reads only `feature`, the first argument, and is
|
||||
> > probably unharmed. **Item 2b's plan to walk `inputs`/`numInputs` is not**, and
|
||||
> > needs a version guard of its own before it dereferences anything.
|
||||
>
|
||||
> What the probe *did* settle is the premise underneath everything else, and it
|
||||
> is now ctest `fl_vtable_identity_control`: two independently created swapchains
|
||||
> share one vtable, and a different interface does not — both directions, so a
|
||||
> regression in either fails the build.
|
||||
|
||||
**What still has to be measured on a real title:**
|
||||
|
||||
1. A forwarding proxy is the easy case. DLSS-G presents *interpolated* frames
|
||||
the application never submitted — whether those reach a real-vtable hook is
|
||||
what actually matters for the FG counting in `03_METRICS` §Frame Generation,
|
||||
and the harness cannot simulate it.
|
||||
2. We observe the post-proxy call, so parameters the proxy rewrote are what we
|
||||
see, not what the game passed.
|
||||
3. A proxy that owns a *different* swapchain, rather than wrapping ours, would
|
||||
still be invisible.
|
||||
|
||||
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 — **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
|
||||
never executed. `17_HOOK_ENGINE` §Ring writer keeps per-frame counters in "a
|
||||
small struct updated by the feature hooks and *read* by the present hook" with no
|
||||
synchronisation specified — a data race as written, and semantically it counts
|
||||
recording rather than execution.
|
||||
|
||||
**Needs:** a specified concurrency model (per-thread counters aggregated at
|
||||
present is the obvious one) and an explicit statement that RT activity means
|
||||
"recorded this frame", with the accuracy budget in `03_METRICS` adjusted to say
|
||||
so.
|
||||
|
||||
### H7 ✅ · Vtable restore on unhook clobbers later hookers — **closed**
|
||||
|
||||
Fixed and specified in `17_HOOK_ENGINE` §Compare-and-restore, never
|
||||
unconditional restore. Verified by `hook-harness --probe-unhook`, ctest
|
||||
`fl_unhook_preserves_foreign`.
|
||||
|
||||
The "cleaner uninstall" claim was backwards: a later hooker saves **our detour**
|
||||
as its original and chains through it, so writing the pristine address back
|
||||
removes their hook silently. Both halves of the contract are asserted — we
|
||||
decline to restore when the slot changed, **and** we do restore when it did not,
|
||||
because a compare-and-restore that never restores is not a fix.
|
||||
|
||||
Simulated rather than depending on RTSS being installed, so it is deterministic
|
||||
and runs on CI. Confirming against the six overlays actually resident on the dev
|
||||
machine (`spike-notes.md` §Environment) is still worth doing once the Overlay has
|
||||
real hooks, but the mechanism no longer rests on that.
|
||||
|
||||
### H8 ✅ · "Never crash the game" — **closed**
|
||||
|
||||
NFR-3 reworded in `02_SPEC` to what the mechanism can actually support: faults
|
||||
*originating in our own hook bodies* are contained, counted and self-disable
|
||||
after three. The absolute promise is gone, and stays out of user-facing text —
|
||||
the Disclaimer's existing "injection carries risk" wording is the honest one.
|
||||
|
||||
Recorded alongside it, because it is the sharpest instance: `-D_HAS_EXCEPTIONS=0`
|
||||
turns a would-be STL throw into `__fastfail`, which SEH cannot intercept
|
||||
(`spike-notes.md` §H3). The "no throwing STL in hook paths" rule is therefore
|
||||
load-bearing rather than stylistic.
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
+27
-2612
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,59 @@
|
||||
*Moved verbatim from `docs/spike-notes.md` on 2026-10-19 (beta.24, owner decision D66); `docs/spike-notes.md` is the index of every section, cited as `spike-notes §N`. Nothing below was edited, so its "below" and "above" point inside the original file.*
|
||||
|
||||
## 0 · Licence checks *(no hardware needed — do these first)*
|
||||
|
||||
Answers `20_OPEN_QUESTIONS` §M3, §M4. Both can invalidate a whole telemetry
|
||||
layer, and neither needs a GPU.
|
||||
|
||||
### ✅ M4 · LibreHardwareMonitor MPL-2.0 Exhibit B — **CLEAR** (2026-08-02)
|
||||
|
||||
- Pinned version: `LibreHardwareMonitorLib` **0.9.6**, nuspec
|
||||
`<license type="expression">MPL-2.0</license>`, repo commit `3d331e33`.
|
||||
- **The LICENSE file is not the evidence.** MPL-2.0's own text *contains*
|
||||
Exhibit B as a template (at lines 369–372 of the licence), so grepping the
|
||||
licence file finds the string in every MPL-2.0 project ever published and
|
||||
proves nothing. What matters is whether a **source file applies** the notice.
|
||||
- Authenticated code search across the whole repository for
|
||||
"Incompatible With Secondary Licenses": **total_count = 1, and the single hit
|
||||
is `LICENSE` itself** — the template, not an applied notice.
|
||||
- Every file we depend on carries **Exhibit A**, the permissive form:
|
||||
`Computer.cs`, `Sensor.cs`, `Gpu/NvidiaGpu.cs`, `Gpu/AmdGpu.cs` all begin
|
||||
"This Source Code Form is subject to the terms of the Mozilla Public License,
|
||||
v. 2.0" with no Exhibit B sentence.
|
||||
- The shipped 0.9.6 `.nupkg` was unpacked and scanned: **no Exhibit B notice in
|
||||
any of its 46 entries.**
|
||||
- **Result: MPL-2.0 §3.3 Secondary Licenses applies → GPL-3.0 compatible.**
|
||||
L2 telemetry is safe to build on.
|
||||
|
||||
Two things this turned up that are *not* blockers but are now known:
|
||||
|
||||
- **The package ships no licence file at all** (`<license>` is an SPDX
|
||||
expression). MPL-2.0 §3.1 therefore makes shipping the text **our**
|
||||
obligation — `legal/licenses/mpl-2.0.txt` is now committed, and the
|
||||
`THIRD_PARTY_NOTICES` release gate is a real requirement, not boilerplate.
|
||||
- `Gpu/IntelIntegratedGpu.cs` has **no licence header** — an upstream
|
||||
inconsistency, not an Exhibit B problem. The repo-root LICENSE still governs.
|
||||
Worth re-checking on any version bump.
|
||||
|
||||
### ✅ M3 · NVAPI licensing and the import library — **CLEAR** (2026-08-02)
|
||||
|
||||
- Artifact: <https://github.com/NVIDIA/nvapi>, `main`.
|
||||
- **The import library is in the repository**: `amd64/nvapi64.lib` and
|
||||
`x86/nvapi.lib` are tracked files, not a separate SDK download. That was the
|
||||
crux of the question — a `.lib` obtained from the NVIDIA SDK installer would
|
||||
have come with the SDK's own agreement instead.
|
||||
- `License.txt` answers it in its first line, unusually explicitly:
|
||||
> `nvapi.lib and nvapi64.lib are licensed under the following terms:`
|
||||
followed by `SPDX-License-Identifier: MIT` and the standard MIT text. **The
|
||||
grant names the import libraries as its subject.**
|
||||
- Headers carry their own `SPDX-License-Identifier: MIT` blocks
|
||||
(`nvapi.h`, `nvapi_lite_common.h`, `nvapi_interface.h` all verified).
|
||||
- **Result: headers and `nvapi64.lib` are both MIT.** MIT is one-way compatible
|
||||
with GPL-3.0; vendoring is fine provided the notice is retained, which
|
||||
`tools/license-check.ps1` enforces. `legal/licenses/nvapi-MIT.txt` committed.
|
||||
- Reflex / PC latency (FR-4.6, the latency tab, `sessions.latency_*`) is
|
||||
therefore reachable. Ordinal resolution stays rejected — it was only ever a
|
||||
workaround for a constraint that does not exist.
|
||||
|
||||
---
|
||||
|
||||
Loaded 100 of 563 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user